Worksheets
Bases: BaseSessionResource
An Excel-like grid paired one-to-one with a Project.
A Worksheet is the command center where formulations are designed. It groups
one or more Sheets (Sheet), each an
interactive grid organized into stacked sections (Product Design, Process
Design, Results, and Apps). Building a formulation on a Sheet is what
registers a Formula inventory item.
Retrieve a Worksheet with
get_by_project_id,
then work with its Sheets through the sheets attribute. Editing the
contents of a Sheet is done through the Sheet
objects themselves, which remain connected to the live session.
Example
Show JSON schema:
{
"$defs": {
"AuditFields": {
"description": "The audit fields for a resource",
"properties": {
"by": {
"default": null,
"title": "By",
"type": "string"
},
"byName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Byname"
},
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "At"
}
},
"title": "AuditFields",
"type": "object"
},
"Design": {
"description": "One section of a Sheet, backing the grid for a single [`DesignType`][albert.resources.sheets.DesignType].\n\nA Sheet is made up of stacked sections (Product Design, Process Design,\nResults, and Apps) and each section is a Design. Designs are largely an\ninternal detail: most work is done through the parent [`Sheet`][albert.resources.sheets.Sheet], which\nexposes its Designs as [`product_design`][albert.resources.sheets.Sheet.product_design],\n[`result_design`][albert.resources.sheets.Sheet.result_design], [`app_design`][albert.resources.sheets.Sheet.app_design], and\n[`process_design`][albert.resources.sheets.Sheet.process_design]. A Design is a live grid element that carries the\nsession and lazily loads its rows, columns, and grid on first access.\nMethods\n-------\ngroup_rows(name, child_row_ids, ...) -> RowGroup\n Create a named row group within this design.\nget_groups(refresh=False) -> list[RowGroup]\n Get all row groups in this design.",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"state": {
"anyOf": [
{
"$ref": "#/$defs/DesignState"
},
{
"type": "null"
}
],
"default": null,
"description": "The display state of the design. Optional. Default is None."
},
"albertId": {
"description": "The Albert ID of the design.",
"title": "Albertid",
"type": "string"
},
"designType": {
"anyOf": [
{
"$ref": "#/$defs/DesignType"
},
{
"type": "string"
}
],
"description": "The section of the Sheet this design backs. See [`DesignType`][albert.resources.sheets.DesignType]. Unknown legacy/tenant values parse as plain strings.",
"title": "Designtype"
}
},
"required": [
"albertId",
"designType"
],
"title": "Design",
"type": "object"
},
"DesignState": {
"description": "The display state of a Design section within a Sheet.",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"collapsed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether the Design section is collapsed in the Sheet view. Default is False.",
"title": "Collapsed"
}
},
"title": "DesignState",
"type": "object"
},
"DesignType": {
"description": "The section of a Sheet that a Design represents.\n\nA Sheet is organized into stacked sections, each backed by a Design\n([`Design`][albert.resources.sheets.Design]). The type identifies which section:\n\n- ``PRODUCTS``: Product Design, where formulations are built.\n- ``PROCESS``: Process Design.\n- ``RESULTS``: Results, holding Property Tasks and their data.\n- ``APPS``: Apps, holding insights, reporting, and notes.",
"enum": [
"apps",
"products",
"results",
"process",
"reagents"
],
"title": "DesignType",
"type": "string"
},
"Sheet": {
"description": "An interactive grid within a Worksheet where formulations are built.\n\nA Sheet is one grid inside a Worksheet ([`Worksheet`][albert.resources.worksheets.Worksheet]).\nIt is organized into stacked sections, each a [`Design`][albert.resources.sheets.Design]: Product Design\n(where formulations are built), Process Design, Results (Property Tasks and\ntheir data), and Apps (insights and notes). Access those sections through\n[`product_design`][albert.resources.sheets.Sheet.product_design], [`process_design`][albert.resources.sheets.Sheet.process_design], [`result_design`][albert.resources.sheets.Sheet.result_design], and\n[`app_design`][albert.resources.sheets.Sheet.app_design].\n\nA Sheet Column can be a formulation (the most common case for the SDK), a\nlookup column that displays an inventory attribute, or an ingredient name.\nRows typically represent ingredients (inventory items) and their amounts.\nAdding a formulation to a Sheet is what registers a Formula inventory item.\n\nThe Sheet is a live grid element that carries the session; its cells, columns,\nand rows are themselves interactive. Retrieve a Sheet from a Worksheet's\n[`sheets`][albert.resources.worksheets.Worksheet.sheets], then edit it in place\nwith the methods below.\n\n!!! example\n ```python\n from albert import Albert\n client = Albert()\n worksheet = client.worksheets.get_by_project_id(project_id=\"PROA9999999\")\n sheet = worksheet.sheets[0]\n print(sheet.grid)\n ```\nMethods\n-------\nrename(new_name) -> Sheet\n Rename the sheet.\nadd_formulation(formulation_name, components, ...) -> Column\n Build a formulation column from a list of components (registers a Formula).\nadd_components_to_formulation(components, ...) -> Column\n Add components to an existing formulation column.\nadd_formulation_columns(formulation_names, ...) -> list[Column]\n Add one or more empty formulation columns.\nadd_inventory_row(inventory_id, ...) -> Row\n Add an ingredient (inventory) row.\nadd_blank_row(row_name, ...) -> Row\n Add a blank row.\nadd_lookup_row(name, ...) -> Row\n Add a lookup row.\nadd_app_row(app_id, name, ...) -> Row\n Add an application row.\nadd_parameter_group_row(parameter_group_id, ...) -> Row\n Add a parameter group (PRG) row to Process Design.\nadd_blank_column(name, ...) -> Column\n Add a blank column.\nadd_lookup_column(name, ...) -> Column\n Add a lookup column.\nadd_function_column(name, ...) -> Column\n Add a function column.\nadd_property_column(name, attribute_id, ...) -> Column\n Add a property/result column.\nget_column(...) -> Column\n Retrieve a column by column ID, inventory ID, or name.\nupdate_cells(cells) -> tuple[list[Cell], list[Cell]]\n Write changed cells back to the sheet.\npin_columns(col_ids, side) -> None\n Pin columns to the left or right edge.\nunpin_columns(col_ids) -> None\n Unpin columns.\nlock_column(...) -> Column\n Lock or unlock a column.\nhide_column(col_id) -> None\n Hide a column.\nshow_column(col_id) -> None\n Show a hidden column.\nset_columns_width(col_ids, width) -> None\n Set the display width of columns.\ndelete_column(column_id) -> None\n Delete a column.\ndelete_row(row_id, design_id) -> None\n Delete a row.",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"albertId": {
"description": "The Albert ID of the sheet.",
"title": "Albertid",
"type": "string"
},
"name": {
"description": "The name of the sheet.",
"title": "Name",
"type": "string"
},
"Formulas": {
"description": "References to the formulations present on the sheet.",
"items": {
"$ref": "#/$defs/SheetFormulationRef"
},
"title": "Formulas",
"type": "array"
},
"hidden": {
"description": "Whether the sheet is hidden.",
"title": "Hidden",
"type": "boolean"
},
"isColumnRight": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "When True, copied columns are placed to the right of the source column; when False, to the left.",
"title": "Iscolumnright"
},
"colSizeMode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Column width sizing mode. Allowed values are ``\"minimum\"`` and ``\"fitToColumn\"``. ``None`` resets to the default grid width.",
"title": "Colsizemode"
},
"Designs": {
"description": "The Designs (sections) of the sheet.",
"items": {
"$ref": "#/$defs/Design"
},
"title": "Designs",
"type": "array"
},
"projectId": {
"description": "The ID of the Project the sheet belongs to (format ``PRO...``).",
"title": "Projectid",
"type": "string"
}
},
"required": [
"albertId",
"name",
"hidden",
"Designs",
"projectId"
],
"title": "Sheet",
"type": "object"
},
"SheetFormulationRef": {
"description": "A reference to a formulation in a sheet",
"properties": {
"id": {
"description": "The Albert ID of the inventory item that is the formulation",
"title": "Id",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The name of the formulation",
"title": "Name"
},
"hidden": {
"description": "Whether the formulation is hidden",
"title": "Hidden",
"type": "boolean"
}
},
"required": [
"id",
"hidden"
],
"title": "SheetFormulationRef",
"type": "object"
},
"Status": {
"description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n The resource is fully operational and visible in normal operations.\nINACTIVE : str\n The resource is hidden from normal operations and disabled from use.",
"enum": [
"active",
"inactive"
],
"title": "Status",
"type": "string"
}
},
"description": "An Excel-like grid paired one-to-one with a Project.\n\nA Worksheet is the command center where formulations are designed. It groups\none or more Sheets ([`Sheet`][albert.resources.sheets.Sheet]), each an\ninteractive grid organized into stacked sections (Product Design, Process\nDesign, Results, and Apps). Building a formulation on a Sheet is what\nregisters a Formula inventory item.\n\nRetrieve a Worksheet with\n[`get_by_project_id`][albert.collections.worksheets.WorksheetCollection.get_by_project_id],\nthen work with its Sheets through the [`sheets`][albert.resources.worksheets.Worksheet.sheets] attribute. Editing the\ncontents of a Sheet is done through the [`Sheet`][albert.resources.sheets.Sheet]\nobjects themselves, which remain connected to the live session.\n\n!!! example\n ```python\n from albert import Albert\n client = Albert()\n worksheet = client.worksheets.get_by_project_id(project_id=\"PROA9999999\")\n for sheet in worksheet.sheets:\n print(sheet.id, sheet.name)\n ```",
"properties": {
"status": {
"anyOf": [
{
"$ref": "#/$defs/Status"
},
{
"type": "null"
}
],
"default": null,
"description": "The status of the resource, optional."
},
"Created": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the creation of the resource, optional."
},
"Updated": {
"anyOf": [
{
"$ref": "#/$defs/AuditFields"
},
{
"type": "null"
}
],
"default": null,
"description": "Audit fields for the update of the resource, optional."
},
"Sheets": {
"description": "The Sheets contained in this Worksheet.",
"items": {
"$ref": "#/$defs/Sheet"
},
"title": "Sheets",
"type": "array"
},
"projectName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The name of the paired Project.",
"title": "Projectname"
},
"sheetEnabled": {
"default": true,
"description": "Whether Sheets are enabled for this Worksheet.",
"title": "Sheetenabled",
"type": "boolean"
},
"projectId": {
"description": "The ID of the paired Project (format ``PRO...``).",
"title": "Projectid",
"type": "string"
}
},
"required": [
"projectId"
],
"title": "Worksheet",
"type": "object"
}
Fields:
-
status(Status | None) -
created(AuditFields | None) -
updated(AuditFields | None) -
_session(AlbertSession | None) -
sheets(list[Sheet]) -
project_name(str | None) -
sheets_enabled(bool) -
project_id(str)
Validators: