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_blank_rows(row_names, ...) -> list[Row]\n Add multiple blank rows in one call.\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_task_row(task_id, ...) -> Row\n Link a task into the Results section as a task (TAS) row.\nadd_blank_column(name, ...) -> Column\n Add a blank column.\nadd_columns(names, ...) -> list[Column]\n Add multiple columns of one type in one call.\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.\nlock_columns(column_ids, locked=True) -> None\n Lock or unlock multiple columns in one call.\nrename_columns(columns) -> None\n Rename multiple columns in one call.\nhide_column(col_id) -> None\n Hide a column.\nhide_columns(column_ids) -> None\n Hide multiple columns in one call.\nshow_column(col_id) -> None\n Show a hidden column.\nshow_columns(column_ids) -> None\n Show multiple hidden columns in one call.\nset_columns_width(col_ids, width) -> None\n Set the display width of columns.\nreorder_columns(column_ids) -> None\n Reorder all columns left to right by column ID.\ndelete_column(column_id) -> None\n Delete a column.\ndelete_columns(column_ids) -> None\n Delete multiple columns in one call.\ndelete_row(row_id, design_id) -> None\n Delete a row.\ndelete_rows(row_ids, design_id) -> None\n Delete multiple rows from a Design section in one call.",
"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) -
sheets(list[Sheet]) -
project_name(str | None) -
sheets_enabled(bool) -
project_id(str)
Validators:
-
_bind_session -
add_session_to_sheets
Bases: BaseAlbertModel
An ingredient row on a formula search hit.
Show JSON schema:
{
"description": "An ingredient row on a formula search hit.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The inventory ID of the ingredient (format ``INV...``).",
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The name of the ingredient.",
"title": "Name"
}
},
"title": "WorksheetSearchInventoryLine",
"type": "object"
}
Fields:
-
id(InventoryId | None) -
name(str | None)
Bases: BaseAlbertModel
A tag on a formula search hit.
Show JSON schema:
{
"description": "A tag on a formula search hit.",
"properties": {
"tagId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The ID of the tag (format ``TAG...``).",
"title": "Tagid"
},
"tagName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The name of the tag.",
"title": "Tagname"
}
},
"title": "WorksheetSearchTag",
"type": "object"
}
Fields:
Bases: BaseAlbertModel
A lightweight formula result returned by worksheet search.
Returned by
search,
this is a partially populated view of a Formula inventory item built on a
Sheet, optimized for fast lookups. Pass its id to
get_by_id
to obtain the fully populated
InventoryItem.
Show JSON schema:
{
"$defs": {
"WorksheetSearchInventoryLine": {
"description": "An ingredient row on a formula search hit.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The inventory ID of the ingredient (format ``INV...``).",
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The name of the ingredient.",
"title": "Name"
}
},
"title": "WorksheetSearchInventoryLine",
"type": "object"
},
"WorksheetSearchTag": {
"description": "A tag on a formula search hit.",
"properties": {
"tagId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The ID of the tag (format ``TAG...``).",
"title": "Tagid"
},
"tagName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The name of the tag.",
"title": "Tagname"
}
},
"title": "WorksheetSearchTag",
"type": "object"
}
},
"description": "A lightweight formula result returned by worksheet search.\n\nReturned by\n[`search`][albert.collections.worksheets.WorksheetCollection.search],\nthis is a partially populated view of a Formula inventory item built on a\nSheet, optimized for fast lookups. Pass its ``id`` to\n[`get_by_id`][albert.collections.inventory.InventoryCollection.get_by_id]\nto obtain the fully populated\n[`InventoryItem`][albert.resources.inventory.InventoryItem].",
"properties": {
"albertId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Formula inventory ID (format ``INV...``).",
"title": "Albertid"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display name of the formula.",
"title": "Name"
},
"inventory": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/WorksheetSearchInventoryLine"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "The ingredient rows on the formula.",
"title": "Inventory"
},
"tags": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/WorksheetSearchTag"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "The tags on the formula.",
"title": "Tags"
}
},
"title": "WorksheetSearchItem",
"type": "object"
}
Fields:
-
id(InventoryId | None) -
name(str | None) -
inventory(list[WorksheetSearchInventoryLine] | None) -
tags(list[WorksheetSearchTag] | None)
inventory: list[WorksheetSearchInventoryLine] | None = None
The ingredient rows on the formula.