albert 1.14.1__tar.gz → 1.16.0__tar.gz

albert-1.16.0/.github/workflows/release-please.yml

@@ -0,0 +1,19 @@
+name: release-please-poc
+
+on:
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          release-type: python
+          package-name: albert
+          target-branch: main

albert-1.16.0/.release-please-manifest.json

@@ -0,0 +1 @@
+{ ".": "1.14.1" }

{albert-1.14.1 → albert-1.16.0}/CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [1.15.0] - 2026-02-04
+
+### Added
+
+- Added `CustomTemplatesCollection.create` to support creating custom templates.
+- Added `CustomTemplatesCollection.update_acl` to support updating custom template ACLs.
+- Added `CustomTemplatesCollection.delete` to support deleting custom templates.
+
+### Changed
+
+- Standardized list-parameter normalization across collection filters so scalars and
+  iterables are handled consistently.
+
+### Fixed
+
+- Resolved custom-template ACL handling and schema parsing issues.
+- Defaulted missing custom-template workflow names to a sensible value.
+- Fixed enum parameter resolution to use session-level enum definitions.
+
 ## [1.14.0] - 2025-01-29
 
 ### Added

{albert-1.14.1 → albert-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.14.1
+Version: 1.16.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.16.0/release-please-config.json

@@ -0,0 +1,10 @@
+{
+  "release-type": "python",
+  "packages": {
+    ".": {
+      "package-name": "albert",
+      "version-file": "src/albert/__init__.py",
+      "include-v-in-tag": true
+    }
+  }
+}

{albert-1.14.1 → albert-1.16.0}/src/albert/__init__.py

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

{albert-1.14.1 → albert-1.16.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, DataColumnId, InventoryId
+from albert.core.shared.identifiers import AttachmentId, DataColumnId, InventoryId, ProjectId
 from albert.core.shared.types import MetadataItem
 from albert.resources.attachments import Attachment, AttachmentCategory
 from albert.resources.files import FileCategory, FileNamespace
@@ -288,3 +288,47 @@ class AttachmentCollection(BaseCollection):
 
         response = self.session.post(self.base_path, json=payload)
         return Attachment(**response.json())
+
+    @validate_call
+    def upload_and_attach_document_to_project(
+        self,
+        *,
+        project_id: ProjectId,
+        file_path: Path,
+    ) -> Attachment:
+        """Upload a file and attach it as a document to a project.
+
+        Args:
+            project_id: The Albert ID of the project (e.g. "PRO770").
+            file_path: Local path to the file to upload.
+
+        Returns:
+            The created Attachment record.
+        """
+        resolved_path = file_path.expanduser()
+        if not resolved_path.is_file():
+            raise FileNotFoundError(f"File not found at '{resolved_path}'")
+
+        content_type = mimetypes.guess_type(resolved_path.name)[0] or "application/octet-stream"
+        encoded_file_name = quote(resolved_path.name)
+        file_key = f"{project_id}/documents/original/{encoded_file_name}"
+
+        file_collection = self._get_file_collection()
+        with resolved_path.open("rb") as file_handle:
+            file_collection.sign_and_upload_file(
+                data=file_handle,
+                name=file_key,
+                namespace=FileNamespace.RESULT,
+                content_type=content_type,
+            )
+
+        payload = {
+            "parentId": project_id,
+            "category": AttachmentCategory.OTHER.value,
+            "name": encoded_file_name,
+            "key": file_key,
+            "nameSpace": FileNamespace.RESULT.value,
+        }
+
+        response = self.session.post(self.base_path, json=payload)
+        return Attachment(**response.json())

{albert-1.14.1 → albert-1.16.0}/src/albert/collections/btinsight.py

@@ -7,6 +7,7 @@ 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 BTInsightId
+from albert.core.utils import ensure_list
 from albert.resources.btinsight import BTInsight, BTInsightCategory, BTInsightState
 
 
@@ -132,17 +133,17 @@ class BTInsightCollection(BaseCollection):
         """
         params = {
             "offset": offset,
-            "order": OrderBy(order_by).value if order_by else None,
+            "order": order_by,
             "sortBy": sort_by,
             "text": text,
-            "name": name,
+            "name": ensure_list(name),
         }
-        if state:
-            state = state if isinstance(state, list) else [state]
-            params["state"] = [BTInsightState(x).value for x in state]
-        if category:
-            category = category if isinstance(category, list) else [category]
-            params["category"] = [BTInsightCategory(x).value for x in category]
+
+        state_values = ensure_list(state)
+        params["state"] = state_values if state_values else None
+
+        category_values = ensure_list(category)
+        params["category"] = category_values if category_values else None
 
         return AlbertPaginator(
             mode=PaginationMode.OFFSET,

{albert-1.14.1 → albert-1.16.0}/src/albert/collections/cas.py

@@ -106,7 +106,7 @@ class CasCollection(BaseCollection):
             An iterator over Cas entities.
         """
 
-        params: dict[str, Any] = {"orderBy": order_by.value}
+        params: dict[str, Any] = {"orderBy": order_by}
         if id is not None:
             yield self.get_by_id(id=id)
             return

{albert-1.14.1 → albert-1.16.0}/src/albert/collections/companies.py

@@ -7,6 +7,7 @@ from albert.core.logging import logger
 from albert.core.pagination import AlbertPaginator, PaginationMode
 from albert.core.session import AlbertSession
 from albert.core.shared.identifiers import CompanyId
+from albert.core.utils import ensure_list
 from albert.exceptions import AlbertException
 from albert.resources.companies import Company
 
@@ -62,9 +63,8 @@ class CompanyCollection(BaseCollection):
             "dupDetection": "false",
             "startKey": start_key,
         }
-        if name:
-            params["name"] = name if isinstance(name, list) else [name]
-            params["exactMatch"] = str(exact_match).lower()
+        params["name"] = ensure_list(name)
+        params["exactMatch"] = str(exact_match).lower()
 
         return AlbertPaginator(
             mode=PaginationMode.KEY,

albert-1.16.0/src/albert/collections/custom_templates.py

@@ -0,0 +1,414 @@
+from collections.abc import Iterator
+
+from pydantic import validate_call
+
+from albert.collections.base import BaseCollection
+from albert.collections.tags import TagCollection
+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, Status
+from albert.core.shared.identifiers import CustomTemplateId
+from albert.core.shared.models.patch import PatchOperation
+from albert.core.utils import ensure_list
+from albert.resources.acls import ACL
+from albert.resources.custom_templates import (
+    CustomTemplate,
+    CustomTemplateSearchItem,
+    TemplateCategory,
+)
+
+
+class CustomTemplatesCollection(BaseCollection):
+    """CustomTemplatesCollection is a collection class for managing CustomTemplate entities in the Albert platform."""
+
+    # _updatable_attributes = {"symbol", "synonyms", "category"}
+    _api_version = "v3"
+
+    def __init__(self, *, session: AlbertSession):
+        """
+        Initializes the CustomTemplatesCollection with the provided session.
+
+        Parameters
+        ----------
+        session : AlbertSession
+            The Albert session instance.
+        """
+        super().__init__(session=session)
+        self.base_path = f"/api/{CustomTemplatesCollection._api_version}/customtemplates"
+
+    @validate_call
+    def create(
+        self,
+        *,
+        custom_template: CustomTemplate | list[CustomTemplate],
+    ) -> list[CustomTemplate]:
+        """
+        Creates one or more custom templates.
+
+        Parameters
+        ----------
+        custom_template : CustomTemplate | list[CustomTemplate]
+            The template entities to create.
+
+        Returns
+        -------
+        list[CustomTemplate]
+            The created CustomTemplate entities.
+        """
+        templates = ensure_list(custom_template) or []
+        if len(templates) == 0:
+            raise ValueError("At least one CustomTemplate must be provided.")
+        if len(templates) > 10:
+            raise ValueError("A maximum of 10 CustomTemplates can be created at once.")
+
+        payload = [
+            template.model_dump(
+                mode="json",
+                by_alias=True,
+                exclude_none=True,
+                exclude_unset=True,
+            )
+            for template in templates
+        ]
+        response = self.session.post(url=self.base_path, json=payload)
+        response_data = response.json()
+        created_payloads = (
+            (response_data or {}).get("CreatedItems")
+            if response.status_code == 206
+            else response_data
+        ) or []
+
+        tag_collection = TagCollection(session=self.session)
+
+        def resolve_tag(tag_id: str | None) -> dict[str, str] | None:
+            if not tag_id:
+                return None
+            tag = tag_collection.get_by_id(id=tag_id)
+            return {"albertId": tag.id or tag_id, "name": tag.tag}
+
+        def populate_tag_names(section: dict | None) -> None:
+            if not isinstance(section, dict):
+                return
+            tags = section.get("Tags")
+            if not tags:
+                return
+            resolved_tags = []
+            for tag in tags:
+                if isinstance(tag, dict):
+                    tag_id = tag.get("id") or tag.get("albertId")
+                elif isinstance(tag, str):
+                    tag_id = tag
+                else:
+                    tag_id = None
+
+                resolved_tag = resolve_tag(tag_id)
+                if resolved_tag:
+                    resolved_tags.append(resolved_tag)
+            section["Tags"] = resolved_tags
+
+        for payload in created_payloads:
+            if not isinstance(payload, dict):
+                continue
+            populate_tag_names(payload.get("Data"))
+
+        if response.status_code == 206:
+            failed_items = response_data.get("FailedItems") or []
+            if failed_items:
+                error_messages = []
+                for failed in failed_items:
+                    errors = failed.get("errors") or []
+                    if errors:
+                        error_messages.extend(err.get("msg", "Unknown error") for err in errors)
+                joined = " | ".join(error_messages) if error_messages else "Unknown error"
+                logger.warning(
+                    "Custom template creation partially succeeded. Errors: %s",
+                    joined,
+                )
+
+        hydrated_templates = []
+        for payload in created_payloads:
+            template = CustomTemplate(**payload)
+            hydrated = self.get_by_id(id=template.id)
+            hydrated_templates.append(hydrated)
+
+        return hydrated_templates
+
+    def get_by_id(self, *, id: CustomTemplateId) -> CustomTemplate:
+        """Get a Custom Template by ID
+
+        Parameters
+        ----------
+        id : str
+            id of the custom template
+
+        Returns
+        -------
+        CustomTemplate
+            The CutomTemplate with the provided ID
+        """
+        url = f"{self.base_path}/{id}"
+        response = self.session.get(url)
+        return CustomTemplate(**response.json())
+
+    def search(
+        self,
+        *,
+        text: str | None = None,
+        offset: int | None = 0,
+        sort_by: str | None = None,
+        order_by: OrderBy | None = None,
+        status: Status | None = None,
+        created_by: str | None = None,
+        category: TemplateCategory | list[TemplateCategory] | None = None,
+        created_by_name: str | list[str] | None = None,
+        collaborator: str | list[str] | None = None,
+        facet_text: str | None = None,
+        facet_field: str | None = None,
+        contains_field: str | list[str] | None = None,
+        contains_text: str | list[str] | None = None,
+        my_role: str | list[str] | None = None,
+        max_items: int | None = None,
+    ) -> Iterator[CustomTemplateSearchItem]:
+        """
+        Search for CustomTemplate matching the provided criteria.
+
+        ⚠️ This method returns partial (unhydrated) entities to optimize performance.
+        To retrieve fully detailed entities, use :meth:`get_all` instead.
+
+        Parameters
+        ----------
+        text : str, optional
+            Free text search term.
+        offset : int, optional
+            Starting offset for pagination.
+        sort_by : str, optional
+            Field to sort on.
+        order_by : OrderBy, optional
+            Sort direction for `sort_by`.
+        status : Status | str, optional
+            Filter results by template status.
+        created_by : str, optional
+            Filter by creator id.
+        category : TemplateCategory | list[TemplateCategory], optional
+            Filter by template categories.
+        created_by_name : str | list[str], optional
+            Filter by creator display name(s).
+        collaborator : str | list[str], optional
+            Filter by collaborator ids.
+        facet_text : str, optional
+            Filter text within a facet.
+        facet_field : str, optional
+            Facet field to search inside.
+        contains_field : str | list[str], optional
+            Fields to apply contains search to.
+        contains_text : str | list[str], optional
+            Text values for contains search.
+        my_role : str | list[str], optional
+            Restrict templates to roles held by the calling user.
+        max_items : int, optional
+            Maximum number of items to yield client-side.
+
+        Returns
+        -------
+        Iterator[CustomTemplateSearchItem]
+            An iterator of CustomTemplateSearchItem items.
+        """
+
+        params = {
+            "text": text,
+            "offset": offset,
+            "sortBy": sort_by,
+            "order": order_by,
+            "status": status,
+            "createdBy": created_by,
+            "category": ensure_list(category),
+            "createdByName": ensure_list(created_by_name),
+            "collaborator": ensure_list(collaborator),
+            "facetText": facet_text,
+            "facetField": facet_field,
+            "containsField": ensure_list(contains_field),
+            "containsText": ensure_list(contains_text),
+            "myRole": ensure_list(my_role),
+        }
+
+        return AlbertPaginator(
+            mode=PaginationMode.OFFSET,
+            path=f"{self.base_path}/search",
+            session=self.session,
+            params=params,
+            max_items=max_items,
+            deserialize=lambda items: [
+                CustomTemplateSearchItem.model_validate(x)._bind_collection(self) for x in items
+            ],
+        )
+
+    def get_all(
+        self,
+        *,
+        name: str | list[str] | None = None,
+        created_by: str | None = None,
+        category: TemplateCategory | None = None,
+        start_key: str | None = None,
+        max_items: int | None = None,
+    ) -> Iterator[CustomTemplate]:
+        """Iterate over CustomTemplate entities with optional filters.
+
+        Parameters
+        ----------
+        name : str | list[str], optional
+            Filter by template name(s).
+        created_by : str, optional
+            Filter by creator id.
+        category : TemplateCategory, optional
+            Filter by category.
+        start_key : str, optional
+            Provide the `lastKey` from a previous request to resume pagination.
+        max_items : int, optional
+            Maximum number of items to return.
+
+        Returns
+        -------
+        Iterator[CustomTemplate]
+            An iterator of CustomTemplates.
+        """
+        params = {
+            "startKey": start_key,
+            "createdBy": created_by,
+            "category": category,
+        }
+        params["name"] = ensure_list(name)
+
+        return AlbertPaginator(
+            mode=PaginationMode.KEY,
+            path=self.base_path,
+            session=self.session,
+            params=params,
+            max_items=max_items,
+            deserialize=lambda items: [CustomTemplate(**item) for item in items],
+        )
+
+    @validate_call
+    def delete(self, *, id: CustomTemplateId) -> None:
+        """
+        Delete a custom template by id.
+
+        Parameters
+        ----------
+        id : CustomTemplateId
+            The id of the custom template to delete.
+
+        Returns
+        -------
+        None
+        """
+
+        url = f"{self.base_path}/{id}"
+        self.session.delete(url)
+
+    @validate_call
+    def update_acl(
+        self,
+        *,
+        custom_template_id: CustomTemplateId,
+        acl_class: str | None = None,
+        acls: list[ACL] | None = None,
+    ) -> CustomTemplate:
+        """
+        Replace a template's ACL class and/or entries with the provided values.
+
+        Parameters
+        ----------
+        custom_template_id : CustomTemplateId
+            The id of the custom template to update.
+        acl_class : str | None, optional
+            The ACL class to set (if provided).
+        acls : list[ACL] | None, optional
+            The ACL entries to replace on the template.
+
+        Returns
+        -------
+        CustomTemplate
+            The updated CustomTemplate.
+        """
+
+        if acl_class is None and acls is None:
+            raise ValueError("Provide an ACL class and/or ACL entries to update.")
+
+        data = []
+        current_template: CustomTemplate | None = None
+
+        if acl_class is not None:
+            acl_class_value = getattr(acl_class, "value", acl_class)
+            data.append(
+                {
+                    "operation": PatchOperation.UPDATE.value,
+                    "attribute": "class",
+                    "newValue": acl_class_value,
+                }
+            )
+
+        if acls is not None:
+            current_template = self.get_by_id(id=custom_template_id)
+            current_acl = (
+                current_template.acl.fgclist
+                if current_template.acl and current_template.acl.fgclist
+                else []
+            )
+            current_entries = {
+                entry.id: getattr(entry.fgc, "value", entry.fgc) for entry in current_acl
+            }
+
+            desired_entries = {entry.id: getattr(entry.fgc, "value", entry.fgc) for entry in acls}
+
+            to_add = []
+            to_delete = []
+            to_update = []
+
+            for entry_id, new_fgc in desired_entries.items():
+                if entry_id not in current_entries:
+                    payload = {"id": entry_id}
+                    if new_fgc is not None:
+                        payload["fgc"] = new_fgc
+                    to_add.append(payload)
+                else:
+                    old_fgc = current_entries[entry_id]
+                    if new_fgc is not None and old_fgc != new_fgc:
+                        to_update.append(
+                            {
+                                "operation": PatchOperation.UPDATE.value,
+                                "attribute": "fgc",
+                                "id": entry_id,
+                                "oldValue": old_fgc,
+                                "newValue": new_fgc,
+                            }
+                        )
+
+            for entry_id in current_entries:
+                if entry_id not in desired_entries:
+                    to_delete.append({"id": entry_id})
+
+            if to_add:
+                data.append(
+                    {
+                        "operation": PatchOperation.ADD.value,
+                        "attribute": "ACL",
+                        "newValue": to_add,
+                    }
+                )
+            if to_delete:
+                data.append(
+                    {
+                        "operation": PatchOperation.DELETE.value,
+                        "attribute": "ACL",
+                        "oldValue": to_delete,
+                    }
+                )
+            data.extend(to_update)
+
+        if not data:
+            return current_template or self.get_by_id(id=custom_template_id)
+
+        url = f"{self.base_path}/{custom_template_id}/acl"
+        self.session.patch(url, json={"data": data})
+        return self.get_by_id(id=custom_template_id)

{albert-1.14.1 → albert-1.16.0}/src/albert/collections/data_columns.py

@@ -7,6 +7,7 @@ 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
+from albert.core.utils import ensure_list
 from albert.resources.data_columns import DataColumn
 
 
@@ -102,12 +103,12 @@ class DataColumnCollection(BaseCollection):
             yield from (DataColumn(**item) for item in items)
 
         params = {
-            "orderBy": order_by.value,
+            "orderBy": order_by,
             "startKey": start_key,
-            "name": [name] if isinstance(name, str) else name,
+            "name": ensure_list(name),
             "exactMatch": exact_match,
             "default": default,
-            "dataColumns": [ids] if isinstance(ids, str) else ids,
+            "dataColumns": ensure_list(ids),
         }
 
         return AlbertPaginator(

{albert-1.14.1 → albert-1.16.0}/src/albert/collections/data_templates.py

@@ -285,7 +285,7 @@ class DataTemplateCollection(BaseCollection):
         """
         params = {
             "offset": offset,
-            "order": order_by.value,
+            "order": order_by,
             "text": name,
             "userId": user_id,
         }

{albert-1.14.1 → albert-1.16.0}/src/albert/collections/entity_types.py

@@ -282,10 +282,10 @@ class EntityTypeCollection(BaseCollection):
             Returns an iterator of EntityType items matching the search criteria.
         """
         params = {
-            "service": service.value if service else None,
+            "service": service,
             "limit": max_items,
             "startKey": start_key,
-            "orderBy": order.value if order else None,
+            "orderBy": order,
         }
         return AlbertPaginator(
             mode=PaginationMode.KEY,