albert 1.13.0b1__tar.gz → 1.14.0__tar.gz

{albert-1.13.0b1 → albert-1.14.0}/CHANGELOG.md

@@ -5,7 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.14.0] - 2025-01-29
+
+### Added
+
+- Added `ACLContainer` model for `{class, fgclist}` ACL payloads.
+- Added `WorksheetCollection.duplicate_sheet` functionality.
+- Added `WorksheetCollection.create_sheet_template` functionality.
+- Added a deprecation warning for `NotebookCopyACL`; formal deprecation planned for 2.0 (use `ACLContainer`).
 
 ## [1.2.0] - 2025-07-25
 

{albert-1.13.0b1 → albert-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.13.0b1
+Version: 1.14.0
 Summary: The official Python SDK for the Albert Invent platform.
 Project-URL: Homepage, https://www.albertinvent.com/
 Project-URL: Documentation, https://docs.developer.albertinvent.com/albert-python

albert-1.14.0/docs/examples/inventory.md

@@ -0,0 +1,37 @@
+# Inventory
+
+Albert Inventory serves as a digital manifestation of your physical inventory. It enables you to sort, filter, trace, and manage all types of inventory.
+
+## Inventory function on CAS
+
+Inventory function is a business-controlled, multi-select list on the Inventory ↔ CAS relationship.
+Use it by updating an existing inventory item.
+
+!!! example "Add inventory function values to a CAS entry"
+    ```python
+    from albert import Albert
+    from albert.resources.lists import ListItem, ListItemCategory
+
+    client = Albert.from_client_credentials()
+
+    inventory_id = "INV123"
+    cas_id = "CAS123"
+
+    # Optional: create a new inventoryFunction list item first.
+    list_item = ListItem(
+        name="Primary Function",
+        category=ListItemCategory.INVENTORY,
+        list_type="inventoryFunction",
+    )
+    list_item = client.lists.create(list_item=list_item)
+
+    inventory_item = client.inventory.get_by_id(id=inventory_id)
+    if inventory_item.cas:
+        for cas_amount in inventory_item.cas:
+            if cas_amount.id == cas_id:
+                cas_amount.inventory_function = [list_item]
+                break
+
+    updated_item = client.inventory.update(inventory_item=inventory_item)
+    print(updated_item.id)
+    ```

albert-1.14.0/docs/resources/acls.md

@@ -0,0 +1 @@
+::: albert.resources.acls

{albert-1.13.0b1 → albert-1.14.0}/mkdocs.yml

@@ -177,6 +177,7 @@ nav:
       - Resources:
           - Activities: resources/activities.md
           - Attachments: resources/attachments.md
+          - ACL: resources/acls.md
           - Batch Data: resources/batch_data.md
           - Breakthrough:
               - Breakthrough Datasets: resources/btdataset.md
@@ -221,6 +222,7 @@ nav:
               - Worksheets: resources/worksheets.md
               - Sheets: resources/sheets.md
   - Examples:
+      - Inventory: examples/inventory.md
       - Property Data: examples/property_data.md
       - Tasks: examples/tasks.md
       - Notebooks: examples/notebook.md

{albert-1.13.0b1 → albert-1.14.0}/scripts/validate_version_bump.py

@@ -1,6 +1,7 @@
 import argparse
+import re
+import subprocess
 import sys
-from os import popen
 from pathlib import Path
 
 from packaging import version
@@ -19,8 +20,15 @@ def main(base_branch: str):
     local_path = Path(__file__).parents[1] / version_file
     local_version = extract_version(local_path.read_text())
 
-    with popen(f"git fetch origin && git show {base_branch}:{version_file}") as fh:
-        base_version = extract_version(fh.read())
+    if not re.fullmatch(r"[A-Za-z0-9._/-]+", base_branch) or base_branch.startswith("-"):
+        raise ValueError(f"Invalid base branch ref: {base_branch!r}")
+
+    subprocess.run(["git", "fetch", "origin"], check=True)
+    base_contents = subprocess.check_output(
+        ["git", "show", f"{base_branch}:{version_file}"],
+        text=True,
+    )
+    base_version = extract_version(base_contents)
 
     if is_version_bump(local_version, base_version):
         print(f"Version bump detected: {base_version} -> {local_version}")

{albert-1.13.0b1 → albert-1.14.0}/src/albert/__init__.py

@@ -4,4 +4,4 @@ from albert.core.auth.sso import AlbertSSOClient
 
 __all__ = ["Albert", "AlbertClientCredentials", "AlbertSSOClient"]
 
-__version__ = "1.13.0b1"
+__version__ = "1.14.0"

{albert-1.13.0b1 → albert-1.14.0}/src/albert/collections/attachments.py

@@ -152,20 +152,30 @@ class AttachmentCollection(BaseCollection):
             The name of the file, by default ""
         upload_key : str | None, optional
             Override the storage key used when signing and uploading the file.
-            Defaults to the provided ``file_name``.
+            Defaults to ``{parent_id}/{note_id}/{file_name}``.
 
         Returns
         -------
         Note
             The created note.
         """
-        upload_name = upload_key or file_name
-        if not upload_name:
+        if not (upload_key or file_name):
             raise ValueError("A file name or upload key must be provided for attachment upload.")
 
-        file_type = mimetypes.guess_type(file_name or upload_name)[0]
-        file_collection = self._get_file_collection()
         note_collection = self._get_note_collection()
+        note = Note(
+            parent_id=parent_id,
+            note=note_text,
+        )
+        registered_note = note_collection.create(note=note)
+        if upload_key:
+            attachment_name = file_name or Path(upload_key).name
+            upload_name = upload_key
+        else:
+            attachment_name = file_name
+            upload_name = f"{parent_id}/{registered_note.id}/{file_name}"
+        file_type = mimetypes.guess_type(attachment_name or upload_name)[0]
+        file_collection = self._get_file_collection()
 
         file_collection.sign_and_upload_file(
             data=file_data,
@@ -176,16 +186,12 @@ class AttachmentCollection(BaseCollection):
         file_info = file_collection.get_by_name(
             name=upload_name, namespace=FileNamespace.RESULT.value
         )
-        note = Note(
-            parent_id=parent_id,
-            note=note_text,
-        )
-        registered_note = note_collection.create(note=note)
         self.attach_file_to_note(
             note_id=registered_note.id,
-            file_name=file_name or Path(upload_name).name,
+            file_name=attachment_name,
             file_key=file_info.name,
         )
+
         return note_collection.get_by_id(id=registered_note.id)
 
     @validate_call

{albert-1.13.0b1 → albert-1.14.0}/src/albert/collections/projects.py

@@ -142,17 +142,17 @@ class ProjectCollection(BaseCollection):
         ----------
         text : str, optional
             Full-text search query.
-        status : list of str, optional
+        status : list[str], optional
             Filter by project statuses.
-        market_segment : list of str, optional
+        market_segment : list[str], optional
             Filter by market segment.
-        application : list of str, optional
+        application : list[str], optional
             Filter by application.
-        technology : list of str, optional
+        technology : list[str], optional
             Filter by technology tags.
-        created_by : list of str, optional
+        created_by : list[str], optional
             Filter by user names who created the project.
-        location : list of str, optional
+        location : list[str], optional
             Filter by location(s).
         from_created_at : str, optional
             Earliest creation date in 'YYYY-MM-DD' format.
@@ -162,15 +162,15 @@ class ProjectCollection(BaseCollection):
             Facet field to filter on.
         facet_text : str, optional
             Facet text to search for.
-        contains_field : list of str, optional
+        contains_field : list[str], optional
             Fields to search inside.
-        contains_text : list of str, optional
+        contains_text : list[str], optional
             Values to search for within the `contains_field`.
         linked_to : str, optional
             Entity ID the project is linked to.
         my_project : bool, optional
             If True, return only projects owned by current user.
-        my_role : list of str, optional
+        my_role : list[str], optional
             User roles to filter by.
         order_by : OrderBy, optional
             Sort order. Default is DESCENDING.

albert-1.14.0/src/albert/collections/worksheets.py

@@ -0,0 +1,283 @@
+from pydantic import validate_call
+
+from albert.collections.base import BaseCollection
+from albert.collections.custom_templates import CustomTemplatesCollection
+from albert.core.session import AlbertSession
+from albert.core.shared.identifiers import ProjectId
+from albert.resources.acls import ACLContainer
+from albert.resources.custom_templates import CustomTemplate
+from albert.resources.worksheets import Worksheet
+from albert.utils.worksheets import (
+    get_columns_to_copy,
+    get_prg_rows_to_copy,
+    get_sheet_from_worksheet,
+    get_task_rows_to_copy,
+)
+
+
+class WorksheetCollection(BaseCollection):
+    """WorksheetCollection is a collection class for managing Worksheet entities in the Albert platform."""
+
+    _api_version = "v3"
+
+    def __init__(self, *, session: AlbertSession):
+        super().__init__(session=session)
+        self.base_path = f"/api/{WorksheetCollection._api_version}/worksheet"
+
+    def _add_session_to_sheets(self, response_json: dict):
+        sheets = response_json.get("Sheets")
+        if sheets:
+            for s in sheets:
+                s["session"] = self.session
+                s["project_id"] = response_json["projectId"]
+        response_json["session"] = self.session
+        return response_json
+
+    @validate_call
+    def get_by_project_id(self, *, project_id: ProjectId) -> Worksheet:
+        """Retrieve a worksheet by its project ID. Projects and Worksheets are 1:1 in the Albert platform.
+
+        Parameters
+        ----------
+        project_id : str
+            The project ID to retrieve the worksheet for.
+
+        Returns
+        -------
+        Worksheet
+            The Worksheet object for that project.
+        """
+
+        params = {"type": "project", "id": project_id}
+        response = self.session.get(self.base_path, params=params)
+
+        response_json = response.json()
+
+        # Sheets are themselves collections, and therefore need access to the session
+        response_json = self._add_session_to_sheets(response_json)
+        return Worksheet(**response_json)
+
+    @validate_call
+    def setup_worksheet(self, *, project_id: ProjectId, add_sheet=False) -> Worksheet:
+        """Setup a new worksheet for a project.
+
+        Parameters
+        ----------
+        project_id : str
+            The project ID to setup the worksheet for.
+        add_sheet : bool, optional
+            Whether to add a blank sheet to the worksheet, by default False
+
+        Returns
+        -------
+        Worksheet
+            The Worksheet object for the project.
+        """
+
+        params = {"sheets": str(add_sheet).lower()}
+        path = f"{self.base_path}/{project_id}/setup"
+        self.session.post(path, json=params)
+        return self.get_by_project_id(project_id=project_id)
+
+    @validate_call
+    def setup_new_sheet_from_template(
+        self, *, project_id: ProjectId, sheet_template_id: str, sheet_name: str
+    ) -> Worksheet:
+        """Create a new sheet in the Worksheet related to the specified Project from a template.
+
+        Parameters
+        ----------
+        project_id : str
+            _description_
+        sheet_template_id : str
+            _description_
+        sheet_name : str
+            _description_
+
+        Returns
+        -------
+        Worksheet
+            The Worksheet object for the project.
+        """
+        payload = {"name": sheet_name}
+        params = {"templateId": sheet_template_id}
+        path = f"{self.base_path}/project/{project_id}/sheets"
+        self.session.post(path, json=payload, params=params)
+        return self.get_by_project_id(project_id=project_id)
+
+    @validate_call
+    def add_sheet(self, *, project_id: ProjectId, sheet_name: str) -> Worksheet:
+        """Create a new blank sheet in the Worksheet with the specified name.
+
+        Parameters
+        ----------
+        project_id : str
+            The project ID for the Worksheet to add the sheet to.
+        sheet_name : str
+            The name of the new sheet.
+
+        Returns
+        -------
+        Worksheet
+            The Worksheet object for the project.
+        """
+        payload = {"name": sheet_name}
+        url = f"{self.base_path}/project/{project_id}/sheets"
+        self.session.put(url=url, json=payload)
+        return self.get_by_project_id(project_id=project_id)
+
+    @validate_call
+    def duplicate_sheet(
+        self,
+        *,
+        project_id: ProjectId,
+        source_sheet_name: str,
+        new_sheet_name: str,
+        copy_all_pd_rows: bool = True,
+        copy_all_pinned_columns: bool = True,
+        copy_all_unpinned_columns: bool = True,
+        column_names: list[str] | None = None,
+        task_row_names: list[str] | None = None,
+    ) -> Worksheet:
+        """Duplicate an existing sheet within the same project.
+
+        This creates a new sheet based on the specified source sheet. You can control
+        which Product Design (PD) & Results rows and columns are copied using the available options.
+        The final list of columns copied is the union of:
+            - all pinned columns (if copy_all_pinned_columns is True)
+            - all unpinned columns (if copy_all_unpinned_columns is True)
+            - explicitly listed column names (column_names)
+
+        Parameters
+        ----------
+        project_id : str
+            The project ID under which the sheet exists.
+        source_sheet_name : str
+            The name of the existing sheet to duplicate.
+        new_sheet_name : str
+            The name of the new sheet to create.
+        copy_all_pd_rows : bool, optional
+            When True, all PD (Product Design) rows from the source sheet are copied.
+            When False, only rows corresponding to the selected columns will be copied.
+            Default is True.
+        copy_all_pinned_columns : bool, optional
+            If True, includes all pinned columns from the source sheet. Default is True.
+        copy_all_unpinned_columns : bool, optional
+            If True, includes all unpinned columns from the source sheet. Default is True.
+        column_names : list[str], optional
+            A list of column names to explicitly copy. These are resolved internally
+            to column IDs using the sheet's product design grid.
+        task_row_names : list[str], optional
+            List of task row names to include from the tasks.
+
+        Returns
+        -------
+        Worksheet
+            The Worksheet entity containing newly created sheet.
+        """
+
+        worksheet = self.get_by_project_id(project_id=project_id)
+        sheet = get_sheet_from_worksheet(sheet_name=source_sheet_name, worksheet=worksheet)
+        columns = get_columns_to_copy(
+            sheet=sheet,
+            copy_all_pinned_columns=copy_all_pinned_columns,
+            copy_all_unpinned_columns=copy_all_unpinned_columns,
+            input_column_names=column_names,
+        )
+        task_rows = get_task_rows_to_copy(sheet=sheet, input_row_names=task_row_names)
+
+        payload = {
+            "name": new_sheet_name,
+            "sourceData": {
+                "projectId": project_id,
+                "sheetId": sheet.id,
+                "Columns": [{"id": col_id} for col_id in columns],
+                "copyAllPDRows": copy_all_pd_rows,
+                "TaskRows": [{"id": row_id} for row_id in task_rows],
+            },
+        }
+
+        path = f"{self.base_path}/project/{project_id}/sheets"
+        self.session.put(path, json=payload)
+        return self.get_by_project_id(project_id=project_id)
+
+    @validate_call
+    def create_sheet_template(
+        self,
+        *,
+        project_id: ProjectId,
+        source_sheet_name: str,
+        template_name: str,
+        copy_all_pd_rows: bool = True,
+        copy_all_pinned_columns: bool = True,
+        copy_all_unpinned_columns: bool = True,
+        column_names: list[str] | None = None,
+        task_row_names: list[str] | None = None,
+        prg_row_names: list[str] | None = None,
+        acl: ACLContainer | None = None,
+    ) -> CustomTemplate:
+        """Create a new sheet template from an existing sheet.
+
+        Parameters
+        ----------
+        project_id : str
+            The project ID under which the sheet exists.
+        source_sheet_name : str
+            The name of the existing sheet to use as the template source.
+        template_name : str
+            The name of the new template.
+        copy_all_pd_rows : bool, optional
+            When True, all PD (Product Design) rows from the source sheet are copied.
+            When False, only rows corresponding to the selected columns will be copied.
+        copy_all_pinned_columns : bool, optional
+            If True, includes all pinned columns from the source sheet. Default is True.
+        copy_all_unpinned_columns : bool, optional
+            If True, includes all unpinned columns from the source sheet. Default is True.
+        column_names : list[str], optional
+            A list of column names to explicitly copy. These are resolved internally
+            to column IDs using the sheet's product design grid.
+        task_row_names : list[str], optional
+            List of task row names to include from the tasks.
+        prg_row_names : list[str], optional
+            List of parameter group row names to include.
+        acl : ACLContainer, optional
+            ACL for the template.
+
+        Returns
+        -------
+        CustomTemplate
+            The CustomTemplate for the created sheet template.
+        """
+        worksheet = self.get_by_project_id(project_id=project_id)
+        sheet = get_sheet_from_worksheet(sheet_name=source_sheet_name, worksheet=worksheet)
+        columns = get_columns_to_copy(
+            sheet=sheet,
+            copy_all_pinned_columns=copy_all_pinned_columns,
+            copy_all_unpinned_columns=copy_all_unpinned_columns,
+            input_column_names=column_names,
+        )
+        if not columns:
+            raise ValueError("At least one column must be selected to create a template.")
+        task_rows = get_task_rows_to_copy(sheet=sheet, input_row_names=task_row_names)
+        prg_rows = get_prg_rows_to_copy(sheet=sheet, input_row_names=prg_row_names)
+
+        payload = {
+            "name": template_name,
+            "sourceData": {
+                "projectId": project_id,
+                "sheetId": sheet.id,
+                "Columns": [{"id": col_id} for col_id in columns],
+                "copyAllPDRows": copy_all_pd_rows,
+                "TaskRows": [{"id": row_id} for row_id in task_rows],
+                "PRGRows": [{"id": row_id} for row_id in prg_rows],
+            },
+        }
+
+        if acl is not None:
+            payload["ACL"] = acl.model_dump(exclude_none=True, by_alias=True, mode="json")
+
+        path = f"{self.base_path}/sheet/template"
+        response = self.session.post(path, json=payload)
+        response_json = response.json()
+        ctp_id = response_json.get("ctpId")
+        return CustomTemplatesCollection(session=self.session).get_by_id(id=ctp_id)

{albert-1.13.0b1 → albert-1.14.0}/src/albert/core/auth/_listener.py

@@ -31,6 +31,10 @@ class RequestHandler(BaseHTTPRequestHandler):
         status = "successful" if self.server.token else "failed (no token found)"
         self.send_response(200)
         self.send_header("Content-Type", "text/html")
+        self.send_header(
+            "Content-Security-Policy",
+            "default-src 'none'; frame-ancestors 'none'; base-uri 'none';",
+        )
         self.end_headers()
         self.wfile.write(
             f"""
@@ -38,8 +42,6 @@ class RequestHandler(BaseHTTPRequestHandler):
             <body>
                 <h1>Authentication {status}</h1>
                 <p>You can close this window now.</p>
-                <script>window.close()</script>
-                <button onclick="window.close()">Close Window</button>
             </body>
             </html>
             """.encode()

{albert-1.13.0b1 → albert-1.14.0}/src/albert/core/shared/enums.py

@@ -19,6 +19,7 @@ class SecurityClass(str, Enum):
     SHARED = "shared"
     RESTRICTED = "restricted"
     CONFIDENTIAL = "confidential"
+    # only used by "PROJECTS"
     PRIVATE = "private"
 
 

{albert-1.13.0b1 → albert-1.14.0}/src/albert/resources/acls.py

@@ -3,10 +3,11 @@ from enum import Enum
 from pydantic import Field
 
 from albert.core.base import BaseAlbertModel
+from albert.core.shared.models.base import BaseResource
 
 
 class AccessControlLevel(str, Enum):
-    """The fine grain control"""
+    """Access control levels you can grant users."""
 
     PROJECT_OWNER = "ProjectOwner"
     PROJECT_EDITOR = "ProjectEditor"
@@ -22,9 +23,32 @@ class AccessControlLevel(str, Enum):
 
 
 class ACL(BaseAlbertModel):
-    """The Access Control List (ACL) for a user"""
+    """A single access rule for a user.
+
+    Attributes
+    ----------
+    id : str
+        The user or team this rule applies to.
+    fgc : AccessControlLevel | None
+        The access level for that user or team.
+    """
 
     id: str = Field(description="The id of the user for which this ACL applies")
     fgc: AccessControlLevel | None = Field(
         default=None, description="The Fine-Grain Control Level"
     )
+
+
+class ACLContainer(BaseResource):
+    """Access settings with a default class and a list of rules.
+
+    Attributes
+    ----------
+    acl_class : str | None
+        The default access class (for example, "restricted" or "confidential").
+    fgclist : list[ACL] | None
+        Specific access rules for users or teams.
+    """
+
+    acl_class: str | None = Field(default=None, alias="class")
+    fgclist: list[ACL] | None = Field(default=None, alias="fgclist")

{albert-1.13.0b1 → albert-1.14.0}/src/albert/resources/notebooks.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import re
 import uuid
+import warnings
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
@@ -14,7 +15,7 @@ from albert.core.base import BaseAlbertModel
 from albert.core.shared.identifiers import LinkId, NotebookId, ProjectId, SynthesisId, TaskId
 from albert.core.shared.models.base import BaseResource, EntityLink
 from albert.exceptions import AlbertException
-from albert.resources.acls import ACL
+from albert.resources.acls import ACL, ACLContainer
 
 
 class ListBlockStyle(str, Enum):
@@ -297,13 +298,36 @@ class PutBlockPayload(BaseAlbertModel):
 
 
 class NotebookCopyACL(BaseResource):
+    """
+    Access settings applied to a copied notebook.
+
+    Warning
+    -----
+    Deprecated and will be removed in 2.0. Use ``ACLContainer`` instead.
+
+    Attributes
+    ----------
+    fgclist : list[ACL]
+        Specific access rules for users or teams.
+    acl_class : str
+        Default access class (for example, "restricted" or "confidential").
+    """
+
     fgclist: list[ACL] = Field(default=None)
     acl_class: str = Field(alias="class")
 
+    def __init__(self, **data):
+        warnings.warn(
+            "NotebookCopyACL is deprecated and will be removed in 2.0; use ACLContainer instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(**data)
+
 
 class NotebookCopyInfo(BaseAlbertModel):
     id: NotebookId
     parent_id: str = Field(alias="parentId")
     notebook_name: str | None = Field(default=None, alias="notebookName")
     name: str | None = Field(default=None)
-    acl: NotebookCopyACL | None = Field(default=None)
+    acl: ACLContainer | NotebookCopyACL | None = Field(default=None)