albert 1.10.0__tar.gz → 1.10.0rc1__tar.gz

{albert-1.10.0 → albert-1.10.0rc1}/.circleci/config.yml

@@ -12,6 +12,29 @@ commands:
           command: curl -LsSf https://astral.sh/uv/install.sh | sh
 
 jobs:
+  snyk_app_scan:
+    executor:
+      name: python/default
+      tag: "3.10.15"
+    steps:
+      - checkout
+      - add_ssh_keys:
+          fingerprints:
+            - "SHA256:8xP/cfKKsXJOx9XDojfxU3nx9NRtDCEVSVm0uL6qL5I"
+      - install_uv
+      - run:
+          name: Export dependencies
+          command: |
+            uv sync
+            uv export > requirements_lock.txt
+            uv pip compile requirements_lock.txt > requirements.txt
+            uv pip install --system -r requirements.txt
+      - snyk/scan:
+          fail-on-issues: true
+          monitor-on-build: true
+          severity-threshold: high
+          token-variable: SNYK_TOKEN
+
   test:
     executor:
       name: python/default
@@ -123,11 +146,9 @@ jobs:
                 exit 0
               fi
 
-              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
+              if [[ "$CIRCLE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
                 VERSION="${CIRCLE_TAG#v}"
-                echo "Semver tag detected. Deploying $VERSION with alias: latest"
+                echo "Stable 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."
@@ -138,6 +159,9 @@ jobs:
 workflows:
   main:
     jobs:
+      - snyk_app_scan:
+          name: Snyk App Scan
+          context: dev
       - test:
           name: Test
           context: dev
@@ -181,6 +205,6 @@ workflows:
             - Validate Release Tag
           filters:
             tags:
-              only: /^v[0-9]+\.[0-9]+\.[0-9]+(?:(?:a|b|rc|dev)[0-9]+|-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/
+              only: /^v[0-9]+\.[0-9]+\.[0-9]+$/
             branches:
               ignore: /.*/

{albert-1.10.0 → albert-1.10.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.10.0
+Version: 1.10.0rc1
 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.10.0 → albert-1.10.0rc1}/docs/concepts.md

@@ -67,7 +67,7 @@ project = Project(
 )
 
 # Or pass full object and let SDK convert
-location = client.locations.get_by_id(id="loc123")
+location = client.locations.get_by_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.10.0 → albert-1.10.0rc1}/mkdocs.yml

@@ -40,7 +40,6 @@ 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
 
@@ -127,7 +126,7 @@ nav:
   - SDK Reference:
       - Clients:
           - Albert Client: albert.md
-      - Authentication:
+      - Authenticaton:
           - Albert Client Credentials: credentials.md
           - Albert SSO Client: sso.md
       - Collections:
@@ -218,9 +217,6 @@ nav:
           - Worksheets:
               - Worksheets: resources/worksheets.md
               - Sheets: resources/sheets.md
-  - Examples:
-      - Property Data: examples/property_data.md
-      - Tasks: examples/tasks.md
 
 validation:
   omitted_files: warn

{albert-1.10.0 → albert-1.10.0rc1}/src/albert/__init__.py

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

{albert-1.10.0 → albert-1.10.0rc1}/src/albert/collections/custom_templates.py

@@ -1,7 +1,5 @@
 from collections.abc import Iterator
 
-from pydantic import validate_call
-
 from albert.collections.base import BaseCollection
 from albert.core.logging import logger
 from albert.core.pagination import AlbertPaginator
@@ -30,7 +28,6 @@ class CustomTemplatesCollection(BaseCollection):
         super().__init__(session=session)
         self.base_path = f"/api/{CustomTemplatesCollection._api_version}/customtemplates"
 
-    @validate_call
     def get_by_id(self, *, id: CustomTemplateId) -> CustomTemplate:
         """Get a Custom Template by ID
 

{albert-1.10.0 → albert-1.10.0rc1}/src/albert/collections/data_templates.py

@@ -1,14 +1,17 @@
 from collections.abc import Iterator
 from itertools import islice
+from pathlib import Path
 
 from pydantic import Field, validate_call
 
+from albert.collections.attachments import AttachmentCollection
 from albert.collections.base import BaseCollection
+from albert.collections.files import FileCollection
 from albert.core.logging import logger
 from albert.core.pagination import AlbertPaginator
 from albert.core.session import AlbertSession
 from albert.core.shared.enums import OrderBy, PaginationMode
-from albert.core.shared.identifiers import DataColumnId, DataTemplateId, UserId
+from albert.core.shared.identifiers import AttachmentId, DataColumnId, DataTemplateId, UserId
 from albert.core.shared.models.patch import (
     GeneralPatchDatum,
     GeneralPatchPayload,
@@ -17,21 +20,25 @@ from albert.core.shared.models.patch import (
 )
 from albert.exceptions import AlbertHTTPError
 from albert.resources.data_templates import (
-    CurveExample,
     DataColumnValue,
     DataTemplate,
     DataTemplateSearchItem,
-    ImageExample,
     ParameterValue,
 )
 from albert.resources.parameter_groups import DataType, EnumValidationValue, ValueValidation
+from albert.resources.tasks import ImportMode
 from albert.utils._patch import generate_data_template_patches
 from albert.utils.data_template import (
-    add_parameter_enums,
-    build_curve_example,
-    build_image_example,
+    build_curve_import_patch_payload,
+    create_curve_import_job,
+    derive_curve_csv_mapping,
+    exec_curve_script,
+    get_script_attachment,
     get_target_data_column,
+    prepare_curve_input_attachment,
+    validate_data_column_type,
 )
+from albert.utils.tasks import CSV_EXTENSIONS, fetch_csv_table_rows
 
 
 class DCPatchDatum(PGPatchPayload):
@@ -90,6 +97,255 @@ class DataTemplateCollection(BaseCollection):
         else:
             return self.add_parameters(data_template_id=dt.id, parameters=parameter_values)
 
+    @validate_call
+    def import_curve_data(
+        self,
+        *,
+        data_template_id: DataTemplateId,
+        data_column_id: DataColumnId | None = None,
+        data_column_name: str | None = None,
+        mode: ImportMode = ImportMode.CSV,
+        field_mapping: dict[str, str] | None = None,
+        file_path: str | Path | None = None,
+        attachment_id: AttachmentId | None = None,
+    ) -> DataTemplate:
+        """Import curve data in a data template column.
+
+        Parameters
+        ----------
+        data_template_id : DataTemplateId
+            Target data template Id.
+        data_column_id : DataColumnId | None, optional
+            Specific data column to upload the curve data to. Provide exactly one of ``data_column_id`` or
+            ``data_column_name``.
+        data_column_name : str | None, optional
+            Case-insensitive data column display name. Provide exactly one of the column
+            identifier or name.
+        mode : ImportMode, optional
+            Import mode. ``ImportMode.SCRIPT`` runs the attached automation script and requires
+            a script attachment on the data template; ``ImportMode.CSV`` ingests the
+            uploaded CSV directly. Defaults to ``ImportMode.CSV``.
+        field_mapping : dict[str, str] | None, optional
+            Optional manual mapping from CSV headers to curve result column names on the target column. Example: ``{"visc": "Viscosity"}`` maps the
+            "visc" CSV header to the "Viscosity" curve result column. Mappings are matched
+            case-insensitively and override auto-detection. In ``ImportMode.SCRIPT`` this applies to the headers emitted by the script before ingestion.
+        attachment_id : AttachmentId | None, optional
+            Existing attachment to use. Exactly one of ``attachment_id`` or ``file_path`` must be provided.
+        file_path : str | Path | None, optional
+            Local file to upload and attach to a new note on the data template. Exactly one of
+            ``attachment_id`` or ``file_path`` must be provided.
+        Returns
+        -------
+        DataTemplate
+            The data template refreshed after the curve import job completes.
+
+        Examples
+        --------
+        !!! example "Import curve data from a CSV file"
+            ```python
+            dt = client.data_templates.import_curve_data(
+                data_template_id="DT123",
+                data_column_name="APHA Color",
+                mode=ImportMode.CSV,
+                file_path="path/to/curve.csv",
+                field_mapping={"visc": "Viscosity"},
+            )
+            ```
+        """
+        data_template = self.get_by_id(id=data_template_id)
+        target_column = get_target_data_column(
+            data_template=data_template,
+            data_template_id=data_template_id,
+            data_column_id=data_column_id,
+            data_column_name=data_column_name,
+        )
+        validate_data_column_type(target_column=target_column)
+        column_id = target_column.data_column_id
+        attachment_collection = AttachmentCollection(session=self.session)
+
+        script_attachment_signed_url: str | None = None
+
+        if mode is ImportMode.SCRIPT:
+            script_attachment, script_extensions = get_script_attachment(
+                attachment_collection=attachment_collection,
+                data_template_id=data_template_id,
+                column_id=column_id,
+            )
+            if not script_extensions:
+                raise ValueError("Script attachment must define allowed extensions.")
+            script_attachment_signed_url = script_attachment.signed_url
+            allowed_extensions = set(script_extensions)
+        else:
+            allowed_extensions = set(CSV_EXTENSIONS)
+        raw_attachment = prepare_curve_input_attachment(
+            attachment_collection=attachment_collection,
+            data_template_id=data_template_id,
+            column_id=column_id,
+            allowed_extensions=allowed_extensions,
+            file_path=file_path,
+            attachment_id=attachment_id,
+            require_signed_url=mode is ImportMode.SCRIPT,
+        )
+        raw_key = raw_attachment.key
+        if raw_attachment.id is None:
+            raise ValueError("Curve input attachment did not return an identifier.")
+        resolved_attachment_id = AttachmentId(raw_attachment.id)
+
+        processed_input_key: str = raw_key
+        column_headers: dict[str, str] = {}
+
+        if mode is ImportMode.SCRIPT:
+            file_collection = FileCollection(session=self.session)
+            processed_input_key, column_headers = exec_curve_script(
+                session=self.session,
+                api_version=self._api_version,
+                data_template_id=data_template_id,
+                column_id=column_id,
+                raw_attachment=raw_attachment,
+                file_collection=file_collection,
+                script_attachment_signed_url=script_attachment_signed_url,
+            )
+        else:
+            table_rows = fetch_csv_table_rows(
+                session=self.session,
+                attachment_id=resolved_attachment_id,
+                headers_only=True,
+            )
+            header_row = table_rows[0]
+            if not isinstance(header_row, dict):
+                raise ValueError("Unexpected CSV header format returned by preview endpoint.")
+            column_headers = {
+                key: value
+                for key, value in header_row.items()
+                if isinstance(key, str) and isinstance(value, str) and value
+            }
+
+        csv_mapping = derive_curve_csv_mapping(
+            target_column=target_column,
+            column_headers=column_headers,
+            field_mapping=field_mapping,
+        )
+
+        job_id, partition_uuid, s3_output_key = create_curve_import_job(
+            session=self.session,
+            data_template_id=data_template_id,
+            column_id=column_id,
+            csv_mapping=csv_mapping,
+            raw_attachment=raw_attachment,
+            processed_input_key=processed_input_key,
+        )
+
+        patch_payload = build_curve_import_patch_payload(
+            target_column=target_column,
+            job_id=job_id,
+            csv_mapping=csv_mapping,
+            raw_attachment=raw_attachment,
+            partition_uuid=partition_uuid,
+            s3_output_key=s3_output_key,
+        )
+        self.session.patch(
+            f"{self.base_path}/{data_template_id}",
+            json=patch_payload.model_dump(by_alias=True, mode="json", exclude_none=True),
+        )
+
+        return self.get_by_id(id=data_template_id)
+
+    def _add_param_enums(
+        self,
+        *,
+        data_template_id: DataTemplateId,
+        new_parameters: list[ParameterValue],
+    ) -> list[EnumValidationValue]:
+        """Adds enum values to a parameter."""
+
+        data_template = self.get_by_id(id=data_template_id)
+        existing_parameters = data_template.parameter_values
+        enums_by_sequence = {}
+        for parameter in new_parameters:
+            this_sequence = next(
+                (
+                    p.sequence
+                    for p in existing_parameters
+                    if p.id == parameter.id and p.short_name == parameter.short_name
+                ),
+                None,
+            )
+            enum_patches = []
+            if (
+                parameter.validation
+                and len(parameter.validation) > 0
+                and isinstance(parameter.validation[0].value, list)
+            ):
+                existing_validation = (
+                    [x for x in existing_parameters if x.sequence == parameter.sequence]
+                    if existing_parameters
+                    else []
+                )
+                existing_enums = (
+                    [
+                        x
+                        for x in existing_validation[0].validation[0].value
+                        if isinstance(x, EnumValidationValue) and x.id is not None
+                    ]
+                    if (
+                        existing_validation
+                        and len(existing_validation) > 0
+                        and existing_validation[0].validation
+                        and len(existing_validation[0].validation) > 0
+                        and existing_validation[0].validation[0].value
+                        and isinstance(existing_validation[0].validation[0].value, list)
+                    )
+                    else []
+                )
+                updated_enums = (
+                    [
+                        x
+                        for x in parameter.validation[0].value
+                        if isinstance(x, EnumValidationValue)
+                    ]
+                    if parameter.validation[0].value
+                    else []
+                )
+
+                deleted_enums = [
+                    x for x in existing_enums if x.id not in [y.id for y in updated_enums]
+                ]
+
+                new_enums = [
+                    x for x in updated_enums if x.id not in [y.id for y in existing_enums]
+                ]
+
+                matching_enums = [
+                    x for x in updated_enums if x.id in [y.id for y in existing_enums]
+                ]
+
+                for new_enum in new_enums:
+                    enum_patches.append({"operation": "add", "text": new_enum.text})
+                for deleted_enum in deleted_enums:
+                    enum_patches.append({"operation": "delete", "id": deleted_enum.id})
+                for matching_enum in matching_enums:
+                    if (
+                        matching_enum.text
+                        != [x for x in existing_enums if x.id == matching_enum.id][0].text
+                    ):
+                        enum_patches.append(
+                            {
+                                "operation": "update",
+                                "id": matching_enum.id,
+                                "text": matching_enum.text,
+                            }
+                        )
+
+                if len(enum_patches) > 0:
+                    enum_response = self.session.put(
+                        f"{self.base_path}/{data_template_id}/parameters/{this_sequence}/enums",
+                        json=enum_patches,
+                    )
+                    enums_by_sequence[this_sequence] = [
+                        EnumValidationValue(**x) for x in enum_response.json()
+                    ]
+        return enums_by_sequence
+
     @validate_call
     def get_by_id(self, *, id: DataTemplateId) -> DataTemplate:
         """Get a data template by its ID.
@@ -107,7 +363,6 @@ class DataTemplateCollection(BaseCollection):
         response = self.session.get(f"{self.base_path}/{id}")
         return DataTemplate(**response.json())
 
-    @validate_call
     def get_by_ids(self, *, ids: list[DataTemplateId]) -> list[DataTemplate]:
         """Get a list of data templates by their IDs.
 
@@ -147,7 +402,6 @@ class DataTemplateCollection(BaseCollection):
                 return t.hydrate()
         return None
 
-    @validate_call
     def add_data_columns(
         self, *, data_template_id: DataTemplateId, data_columns: list[DataColumnValue]
     ) -> DataTemplate:
@@ -191,7 +445,6 @@ class DataTemplateCollection(BaseCollection):
         )
         return self.get_by_id(id=data_template_id)
 
-    @validate_call
     def add_parameters(
         self, *, data_template_id: DataTemplateId, parameters: list[ParameterValue]
     ) -> DataTemplate:
@@ -240,9 +493,7 @@ class DataTemplateCollection(BaseCollection):
             if param.id in initial_enum_values:
                 param.validation[0].value = initial_enum_values[param.id]
                 param.validation[0].datatype = DataType.ENUM
-                add_parameter_enums(
-                    session=self.session,
-                    base_path=self.base_path,
+                self._add_param_enums(
                     data_template_id=data_template_id,
                     new_parameters=[param],
                 )
@@ -313,12 +564,6 @@ class DataTemplateCollection(BaseCollection):
         -------
         DataTemplate
             The Updated DataTemplate object.
-
-        Warnings
-        --------
-        Only scalar data column values (text, number, dropdown) can be updated using this function. Use
-        `set_curve_example` / `set_image_example` to set example values for other data column types.
-
         """
 
         existing = self.get_by_id(id=data_template.id)
@@ -394,9 +639,7 @@ class DataTemplateCollection(BaseCollection):
                     param.validation[0].datatype = DataType.ENUM  # Add this line
 
             # Add enum values to newly created parameters
-            add_parameter_enums(
-                session=self.session,
-                base_path=self.base_path,
+            self._add_param_enums(
                 data_template_id=existing.id,
                 new_parameters=returned_parameters,
             )
@@ -480,7 +723,6 @@ class DataTemplateCollection(BaseCollection):
             )
         return self.get_by_id(id=data_template.id)
 
-    @validate_call
     def delete(self, *, id: DataTemplateId) -> None:
         """Deletes a data template by its ID.
 
@@ -549,99 +791,3 @@ class DataTemplateCollection(BaseCollection):
                 yield from hydrated_templates
             except AlbertHTTPError as e:
                 logger.warning(f"Error hydrating batch {batch}: {e}")
-
-    @validate_call
-    def set_curve_example(
-        self,
-        *,
-        data_template_id: DataTemplateId,
-        data_column_id: DataColumnId | None = None,
-        data_column_name: str | None = None,
-        example: CurveExample,
-    ) -> DataTemplate:
-        """Set a curve example on a Curve data column.
-
-        Parameters
-        ----------
-        data_template_id : DataTemplateId
-            Target data template ID.
-        data_column_id : DataColumnId, optional
-            Target curve column ID (provide exactly one of id or name).
-        data_column_name : str, optional
-            Target curve column name (provide exactly one of id or name).
-        example : CurveExample
-            Curve example payload
-
-        Returns
-        -------
-        DataTemplate
-            The updated data template after the example is applied.
-        """
-        data_template = self.get_by_id(id=data_template_id)
-        target_column = get_target_data_column(
-            data_template=data_template,
-            data_template_id=data_template_id,
-            data_column_id=data_column_id,
-            data_column_name=data_column_name,
-        )
-        payload = build_curve_example(
-            session=self.session,
-            data_template_id=data_template_id,
-            example=example,
-            target_column=target_column,
-        )
-        if not payload.data:
-            return data_template
-        self.session.patch(
-            f"{self.base_path}/{data_template_id}",
-            json=payload.model_dump(mode="json", by_alias=True, exclude_none=True),
-        )
-        return self.get_by_id(id=data_template_id)
-
-    @validate_call
-    def set_image_example(
-        self,
-        *,
-        data_template_id: DataTemplateId,
-        data_column_id: DataColumnId | None = None,
-        data_column_name: str | None = None,
-        example: ImageExample,
-    ) -> DataTemplate:
-        """Set an image example on a Image data column.
-
-        Parameters
-        ----------
-        data_template_id : DataTemplateId
-            Target data template ID.
-        data_column_id : DataColumnId, optional
-            Target image column ID (provide exactly one of id or name).
-        data_column_name : str, optional
-            Target image column name (provide exactly one of id or name).
-        example : ImageExample
-            Image example payload
-
-        Returns
-        -------
-        DataTemplate
-            The updated data template after the example is applied.
-        """
-        data_template = self.get_by_id(id=data_template_id)
-        target_column = get_target_data_column(
-            data_template=data_template,
-            data_template_id=data_template_id,
-            data_column_id=data_column_id,
-            data_column_name=data_column_name,
-        )
-        payload = build_image_example(
-            session=self.session,
-            data_template_id=data_template_id,
-            example=example,
-            target_column=target_column,
-        )
-        if not payload.data:
-            return data_template
-        self.session.patch(
-            f"{self.base_path}/{data_template_id}",
-            json=payload.model_dump(mode="json", by_alias=True, exclude_none=True),
-        )
-        return self.get_by_id(id=data_template_id)