albert 1.9.5__tar.gz → 1.12.0__tar.gz

{albert-1.9.5 → albert-1.12.0}/.circleci/config.yml

@@ -123,9 +123,11 @@ jobs:
                 exit 0
               fi
 
-              if [[ "$CIRCLE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              SEMVER_REGEX='^v[0-9]+\.[0-9]+\.[0-9]+((a|b|rc|dev)[0-9]+|-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$'
+
+              if [[ "$CIRCLE_TAG" =~ $SEMVER_REGEX ]]; then
                 VERSION="${CIRCLE_TAG#v}"
-                echo "Stable semver tag detected. Deploying $VERSION with alias: latest"
+                echo "Semver tag detected. Deploying $VERSION with alias: latest"
                 uv run mike deploy --push --update-aliases "$VERSION" latest
               else
                 echo "Non-semver release tag. Skipping docs deployment."
@@ -179,6 +181,6 @@ workflows:
             - Validate Release Tag
           filters:
             tags:
-              only: /^v[0-9]+\.[0-9]+\.[0-9]+$/
+              only: /^v[0-9]+\.[0-9]+\.[0-9]+(?:(?:a|b|rc|dev)[0-9]+|-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/
             branches:
               ignore: /.*/

{albert-1.9.5 → albert-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.9.5
+Version: 1.12.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
@@ -220,6 +220,7 @@ Requires-Dist: pandas<3,>=2.2.2
 Requires-Dist: pydantic[email]<3,>=2.8.2
 Requires-Dist: pyjwt<3,>=2.10.0
 Requires-Dist: requests<3,>=2.32.3
+Requires-Dist: tenacity>=8.2.3
 Description-Content-Type: text/markdown
 
 # Albert Python SDK

albert-1.12.0/docs/collections/synthesis.md

@@ -0,0 +1 @@
+::: albert.collections.synthesis.SynthesisCollection

{albert-1.9.5 → albert-1.12.0}/docs/concepts.md

@@ -67,7 +67,7 @@ project = Project(
 )
 
 # Or pass full object and let SDK convert
-location = client.locations.get_by_id("loc123")
+location = client.locations.get_by_id(id="loc123")
 project = Project(
     description="Example",
     locations=[location]  # Automatically converted
@@ -198,15 +198,15 @@ Tags are searchable and help categorize content.
 
 Concepts you should know:
 
-| Concept                 | Purpose                                      |
-|-------------------------|----------------------------------------------|
-| Resource Models         | Define the structure of data entities        |
-| Resource Collections    | Manage CRUD operations for each model        |
-| EntityLink              | Represents foreign key references            |
-| Custom Fields & Lists   | Add structured metadata to resources         |
-| SerializeAsEntityLink  | Allows transparent references or links       |
-| Authentication          | Supports static token, OAuth2, and SSO       |
-| Partial Records         | Lightweight search results                   |
-| Tags and Metadata       | Categorize and extend data                   |
+| Concept               | Purpose                                |
+| --------------------- | -------------------------------------- |
+| Resource Models       | Define the structure of data entities  |
+| Resource Collections  | Manage CRUD operations for each model  |
+| EntityLink            | Represents foreign key references      |
+| Custom Fields & Lists | Add structured metadata to resources   |
+| SerializeAsEntityLink | Allows transparent references or links |
+| Authentication        | Supports static token, OAuth2, and SSO |
+| Partial Records       | Lightweight search results             |
+| Tags and Metadata     | Categorize and extend data             |
 
 These concepts form the foundation of working effectively with the Albert SDK.

albert-1.12.0/docs/examples/notebook.md

@@ -0,0 +1,139 @@
+# Notebooks
+
+Notebooks in Albert Invent are a tool for organizing your laboratory work in a centralized, secure place that is connected to other parts of the Albert platform. They allow you to capture unstructured notes and data, attachments, images, and documents within Projects, set up complex synthesis instructions, document Standard Operating Procedures (SOPs), and collaborate with team members.
+
+## Create a notebook
+
+!!! example "Create an empty notebook"
+    ```python
+    from albert import Albert
+    from albert.resources.notebooks import Notebook
+
+    client = Albert.from_client_credentials()
+
+    notebook = Notebook(parent_id="PRJ123", name="Reaction Notes")
+    notebook = client.notebooks.create(notebook=notebook)
+    ```
+
+## Add different block types
+
+!!! example "Add header, paragraph, checklist, table, image, and attachment blocks"
+    ```python
+    from pathlib import Path
+
+    from albert import Albert
+    from albert.resources.notebooks import (
+        AttachesBlock,
+        AttachesContent,
+        ChecklistBlock,
+        ChecklistContent,
+        ChecklistItem,
+        HeaderBlock,
+        HeaderContent,
+        ImageBlock,
+        ImageContent,
+        ParagraphBlock,
+        ParagraphContent,
+        TableBlock,
+        TableContent,
+    )
+
+    client = Albert.from_client_credentials()
+
+    notebook = client.notebooks.get_by_id(id="NTB123")
+
+    # Provide a file path to upload for image and attachment blocks.
+    image_path = Path("/path/to/image.png")
+    image_block = ImageBlock(content=ImageContent(file_path=image_path, with_background=True))
+    attaches_block = AttachesBlock(content=AttachesContent(file_path=image_path))
+
+    notebook.blocks = [
+        HeaderBlock(content=HeaderContent(level=2, text="Notebook overview")),
+        ParagraphBlock(content=ParagraphContent(text="Run conditions and observations.")),
+        ChecklistBlock(
+            content=ChecklistContent(
+                items=[
+                    ChecklistItem(checked=False, text="Prepare reagents"),
+                    ChecklistItem(checked=True, text="Start reaction"),
+                ]
+            )
+        ),
+        TableBlock(
+            content=TableContent(
+                content=[
+                    ["Reagent", "Mass (mg)"],
+                    ["A", "10"],
+                    ["B", "25"],
+                ],
+                with_headings=True,
+            )
+        ),
+        image_block,
+        attaches_block,
+    ]
+
+    notebook = client.notebooks.update_block_content(notebook=notebook)
+    ```
+
+!!! note
+    When `file_path` is set on image or attachment content, the SDK uploads the file and fills in
+    `file_key`, `format`, and (for attachments) `title`.
+
+## Add a Ketcher block
+
+!!! example "Create a new Ketcher block with SMILES"
+    ```python
+    from albert import Albert
+    from albert.resources.notebooks import KetcherBlock, KetcherContent
+
+    client = Albert.from_client_credentials()
+
+    notebook = client.notebooks.get_by_id(id="NTB123")
+    notebook.blocks.append(
+        KetcherBlock(content=KetcherContent(smiles="CCO"))
+    )
+    notebook = client.notebooks.update_block_content(notebook=notebook)
+    ```
+
+!!! warning
+    Updating existing Ketcher blocks is not supported. To change a Ketcher block, remove
+    it from `notebook.blocks` and add a new Ketcher block with the desired `smiles`.
+
+## Replace a Ketcher block
+
+!!! example "Delete the old Ketcher block and add a new one"
+    ```python
+    from albert import Albert
+    from albert.resources.notebooks import KetcherBlock, KetcherContent
+
+    client = Albert.from_client_credentials()
+
+    notebook = client.notebooks.get_by_id(id="NTB123")
+
+    # Drop existing Ketcher blocks (this deletes them on update).
+    notebook.blocks = [b for b in notebook.blocks if b.type != "ketcher"]
+
+    # Add a new Ketcher block.
+    notebook.blocks.append(
+        KetcherBlock(content=KetcherContent(smiles="C1=CC=CC=C1"))
+    )
+
+    notebook = client.notebooks.update_block_content(notebook=notebook)
+    ```
+
+## Copy a notebook
+
+!!! example "Copy a notebook to another parent"
+    ```python
+    from albert import Albert
+    from albert.resources.notebooks import NotebookCopyInfo, NotebookCopyType
+
+    client = Albert.from_client_credentials()
+
+    copy_info = NotebookCopyInfo(id="NTB123", parent_id="PRJ456")
+    notebook_copy = client.notebooks.copy(
+        notebook_copy_info=copy_info,
+        type=NotebookCopyType.PROJECT,
+    )
+    print(notebook_copy.id)
+    ```

albert-1.12.0/docs/examples/property_data.md

@@ -0,0 +1,184 @@
+# Property Data
+
+Property data refers to the results collected from a Property Task in Albert. This data is captured using Data Templates, which allow for the collection of clean, structured data about your experiments.
+
+## Update an existing trial row
+
+!!! example "Update a trial row"
+    ```python
+    from albert import Albert
+    from albert.resources.property_data import (
+        CurvePropertyValue,
+        ImagePropertyValue,
+        TaskDataColumn,
+        TaskPropertyCreate,
+    )
+
+    client = Albert.from_client_credentials()
+
+    task_id = "TAS123"
+    inventory_id = "INV123"
+    block_id = "BLK1"
+
+    task_ptd = client.property_data.get_task_block_properties(
+        inventory_id=inventory_id,
+        task_id=task_id,
+        block_id=block_id,
+    )
+    dt = task_ptd.data_template
+
+    # trial_number maps to the row number in the task data.
+    # when provided, it updates that row for the given columns.
+    properties = [
+        TaskPropertyCreate(
+            data_column=TaskDataColumn(data_column_id="DAC123", column_sequence="COL4"),
+            value="10",
+            trial_number=2,
+            data_template=dt,
+        ),
+        TaskPropertyCreate(
+            data_column=TaskDataColumn(data_column_id="DAC456", column_sequence="COL5"),
+            value="enum2",
+            trial_number=1,
+            data_template=dt,
+        ),
+        # image property data
+        TaskPropertyCreate(
+            data_column=TaskDataColumn(data_column_id="DAC789", column_sequence="COL1"),
+            value=ImagePropertyValue(file_path="path/to/image.png"),
+            trial_number=1,
+            data_template=dt,
+        ),
+        # curve property data (CSV import by default)
+        TaskPropertyCreate(
+            data_column=TaskDataColumn(data_column_id="DAC313", column_sequence="COL3"),
+            value=CurvePropertyValue(
+                file_path="path/to/curve.csv",
+                field_mapping={"temperature": "Temperature", "cnt": "Count"},
+            ),
+            trial_number=1,
+            data_template=dt,
+        ),
+    ]
+
+    client.property_data.update_or_create_task_properties(
+        inventory_id=inventory_id,
+        task_id=task_id,
+        block_id=block_id,
+        properties=properties,
+        return_scope="block",
+    )
+    ```
+
+## Add a new trial row
+
+!!! example "Add a new trial row"
+    ```python
+    from albert.resources.property_data import TaskDataColumn, TaskPropertyCreate
+
+    task_ptd = client.property_data.get_task_block_properties(
+        inventory_id=inventory_id,
+        task_id=task_id,
+        block_id=block_id,
+    )
+    dt = task_ptd.data_template
+
+    # Omitting trial_number creates a new row in the task data table.
+    new_row = [
+        TaskPropertyCreate(
+            data_column=TaskDataColumn(data_column_id="DAC123", column_sequence="COL4"),
+            value="25",
+            data_template=dt,
+        )
+    ]
+
+    client.property_data.update_or_create_task_properties(
+        inventory_id=inventory_id,
+        task_id=task_id,
+        block_id=block_id,
+        properties=new_row,
+        return_scope="block",
+    )
+    ```
+
+## Void data row
+
+!!! example "Void task data"
+    ```python
+    from albert import Albert
+
+    client = Albert.from_client_credentials()
+
+    task_id = "TAS123"
+    inventory_id = "INV123"
+    block_id = "BLK1"
+
+    client.property_data.void_task_data(
+        inventory_id=inventory_id,
+        task_id=task_id,
+        block_id=block_id,
+    )
+    ```
+
+!!! example "Void interval data"
+    ```python
+    from albert import Albert
+
+    client = Albert.from_client_credentials()
+
+    task_id = "TAS123"
+    inventory_id = "INV123"
+    block_id = "BLK1"
+
+    interval_id = next(
+        (
+            combo.interval_id
+            for combo in client.property_data.check_for_task_data(task_id=task_id)
+            if combo.inventory_id == inventory_id and combo.block_id == block_id
+        ),
+        None,
+    )
+    if not interval_id:
+        raise ValueError("No interval data found for the block/inventory combination.")
+
+    client.property_data.void_interval_data(
+        inventory_id=inventory_id,
+        task_id=task_id,
+        block_id=block_id,
+        interval_id=interval_id,
+    )
+    ```
+
+!!! example "Void trial data"
+    ```python
+    from albert import Albert
+
+    client = Albert.from_client_credentials()
+
+    task_id = "TAS123"
+    inventory_id = "INV123"
+    block_id = "BLK1"
+
+    interval_id = next(
+        (
+            combo.interval_id
+            for combo in client.property_data.check_for_task_data(task_id=task_id)
+            if combo.inventory_id == inventory_id and combo.block_id == block_id
+        ),
+        None,
+    )
+    if not interval_id:
+        raise ValueError("No interval data found for the block/inventory combination.")
+
+    client.property_data.void_trial_data(
+        inventory_id=inventory_id,
+        task_id=task_id,
+        block_id=block_id,
+        trial_number=2,
+        interval_id=interval_id,
+    )
+    ```
+
+!!! note
+    Use the corresponding `unvoid_task_data`, `unvoid_interval_data`, and `unvoid_trial_data`
+    methods to unvoid records.

albert-1.12.0/docs/examples/tasks.md

@@ -0,0 +1,46 @@
+# Tasks
+
+Tasks in Albert Invent are a way to manage and track your daily work and collaborate with colleagues. There are three types of tasks: Batch Tasks, Property Tasks, and General Tasks.
+
+## Import results
+
+This feature enables users to import a .csv file straight into the Data Template of a Property Task allowing them to easily mass enter results without having to type them in manually or copy-paste.
+
+!!! example "Import results from a CSV file"
+    ```python
+    from albert import Albert
+    from albert.resources.data_templates import ImportMode
+
+    client = Albert.from_client_credentials()
+
+    task = client.tasks.import_results(
+        task_id="TAS123",
+        inventory_id="INV123",
+        data_template_id="DT123",
+        file_path="path/to/results.csv",
+        field_mapping={"comm": "Comments", "Solvent": " Solvent, ppm"},
+        mode=ImportMode.CSV,
+    )
+    print(task)
+    ```
+
+!!! example "Import results using a script"
+    ```python
+    from albert import Albert
+    from albert.resources.data_templates import ImportMode
+
+    client = Albert.from_client_credentials()
+
+    task = client.tasks.import_results(
+        task_id="TAS123",
+        inventory_id="INV123",
+        data_template_id="DT123",
+        block_id="BLK1",
+        file_path="path/to/results.csv",
+        mode=ImportMode.SCRIPT,
+    )
+    ```
+
+!!! warning
+    `import_results` deletes existing property data for the matching task/block/inventory/lot/interval
+    before writing new values. Use with care if you need to preserve older results.

albert-1.12.0/docs/resources/synthesis.md

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

{albert-1.9.5 → albert-1.12.0}/mkdocs.yml

@@ -23,7 +23,7 @@ use_directory_urls: true
 theme:
   name: "material"
   font:
-    text: Poppins
+    text: Aeonik Regular
   logo: assets/Wordmark_White.png
   favicon: assets/Vector_Favicon_Blue.svg
   features:
@@ -40,6 +40,7 @@ theme:
     - navigation.sections # Sidebar sections
     - navigation.top # Scroll-to-top button
     - navigation.tracking # Highlight section in sidebar
+    - navigation.collapse
     - search.suggest # Smart search suggestions
     - toc.follow # Highlight TOC entry while scrolling
 
@@ -123,11 +124,10 @@ nav:
       - Configuration: configuration.md
       - Migration Guide: migration.md
       - Contributing: CONTRIBUTING.md
-      - Changelog: CHANGELOG.md
   - SDK Reference:
       - Clients:
           - Albert Client: albert.md
-      - Authenticaton:
+      - Authentication:
           - Albert Client Credentials: credentials.md
           - Albert SSO Client: sso.md
       - Collections:
@@ -166,6 +166,7 @@ nav:
           - Storage Classes: collections/storage_classes.md
           - Storage Locations: collections/storage_locations.md
           - Substances: collections/substances.md
+          - Synthesis: collections/synthesis.md
           - Tags: collections/tags.md
           - Tasks: collections/tasks.md
           - UN Numbers: collections/un_numbers.md
@@ -209,6 +210,7 @@ nav:
           - Storage Classes: resources/storage_classes.md
           - Storage Locations: resources/storage_locations.md
           - Substances: resources/substances.md
+          - Synthesis: resources/synthesis.md
           - Tags: resources/tags.md
           - Tasks: resources/tasks.md
           - UN Numbers: resources/un_numbers.md
@@ -218,6 +220,10 @@ nav:
           - Worksheets:
               - Worksheets: resources/worksheets.md
               - Sheets: resources/sheets.md
+  - Examples:
+      - Property Data: examples/property_data.md
+      - Tasks: examples/tasks.md
+      - Notebooks: examples/notebook.md
 
 validation:
   omitted_files: warn

{albert-1.9.5 → albert-1.12.0}/pyproject.toml

@@ -23,6 +23,7 @@ dependencies = [
     "pandas>=2.2.2,<3",
     "pydantic[email]>=2.8.2,<3",
     "pyjwt>=2.10.0,<3",
+    "tenacity>=8.2.3",
 ]
 
 [dependency-groups]

{albert-1.9.5 → albert-1.12.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.9.5 → albert-1.12.0}/src/albert/__init__.py

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

{albert-1.9.5 → albert-1.12.0}/src/albert/client.py

@@ -38,6 +38,7 @@ from albert.collections.roles import RoleCollection
 from albert.collections.storage_classes import StorageClassesCollection
 from albert.collections.storage_locations import StorageLocationsCollection
 from albert.collections.substance import SubstanceCollection
+from albert.collections.synthesis import SynthesisCollection
 from albert.collections.tags import TagCollection
 from albert.collections.tasks import TaskCollection
 from albert.collections.un_numbers import UnNumberCollection
@@ -188,6 +189,10 @@ class Albert:
     def lots(self) -> LotCollection:
         return LotCollection(session=self.session)
 
+    @property
+    def synthesis(self) -> SynthesisCollection:
+        return SynthesisCollection(session=self.session)
+
     @property
     def units(self) -> UnitCollection:
         return UnitCollection(session=self.session)

{albert-1.9.5 → albert-1.12.0}/src/albert/collections/attachments.py

@@ -9,7 +9,7 @@ from pydantic import validate_call
 from albert.collections.base import BaseCollection
 from albert.collections.files import FileCollection
 from albert.collections.notes import NotesCollection
-from albert.core.shared.identifiers import AttachmentId, InventoryId
+from albert.core.shared.identifiers import AttachmentId, DataColumnId, InventoryId
 from albert.core.shared.types import MetadataItem
 from albert.resources.attachments import Attachment, AttachmentCategory
 from albert.resources.files import FileCategory, FileNamespace
@@ -49,7 +49,9 @@ class AttachmentCollection(BaseCollection):
         response = self.session.get(url=f"{self.base_path}/{id}")
         return Attachment(**response.json())
 
-    def get_by_parent_ids(self, *, parent_ids: list[str]) -> dict[str, list[Attachment]]:
+    def get_by_parent_ids(
+        self, *, parent_ids: list[str], data_column_ids: list[DataColumnId] | None = None
+    ) -> dict[str, list[Attachment]]:
         """Retrieves attachments by their parent IDs.
 
         Note: This method returns a dictionary where the keys are parent IDs
@@ -69,7 +71,10 @@ class AttachmentCollection(BaseCollection):
         dict[str, list[Attachment]]
             A dictionary mapping parent IDs to lists of Attachment objects associated with each parent ID.
         """
-        response = self.session.get(url=f"{self.base_path}/parents", params={"id": parent_ids})
+        response = self.session.get(
+            url=f"{self.base_path}/parents",
+            params={"id": parent_ids, "dataColumnId": data_column_ids},
+        )
         response_data = response.json()
         return {
             parent["parentId"]: [
@@ -125,7 +130,12 @@ class AttachmentCollection(BaseCollection):
         self.session.delete(f"{self.base_path}/{id}")
 
     def upload_and_attach_file_as_note(
-        self, parent_id: str, file_data: IO, note_text: str = "", file_name: str = ""
+        self,
+        parent_id: str,
+        file_data: IO,
+        note_text: str = "",
+        file_name: str = "",
+        upload_key: str | None = None,
     ) -> Note:
         """Uploads a file and attaches it to a new note. A user can be tagged in the note_text string by using f-string and the User.to_note_mention() method.
         This allows for easy tagging and referencing of users within notes. example: f"Hello {tagged_user.to_note_mention()}!"
@@ -140,35 +150,48 @@ class AttachmentCollection(BaseCollection):
             Any additional text to add to the note, by default ""
         file_name : str, optional
             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 ``{parent_id}/{note_id}/{file_name}``.
 
         Returns
         -------
         Note
             The created note.
         """
-        file_type = mimetypes.guess_type(file_name)[0]
-        file_collection = self._get_file_collection()
+        if not (upload_key or file_name):
+            raise ValueError("A file name or upload key must be provided for attachment upload.")
+
         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,
-            name=file_name,
+            name=upload_name,
             namespace=FileNamespace.RESULT.value,
             content_type=file_type,
         )
         file_info = file_collection.get_by_name(
-            name=file_name, namespace=FileNamespace.RESULT.value
-        )
-        note = Note(
-            parent_id=parent_id,
-            note=note_text,
+            name=upload_name, namespace=FileNamespace.RESULT.value
         )
-        registered_note = note_collection.create(note=note)
         self.attach_file_to_note(
             note_id=registered_note.id,
-            file_name=file_name,
+            file_name=attachment_name,
             file_key=file_info.name,
         )
+
         return note_collection.get_by_id(id=registered_note.id)
 
     @validate_call