albert 1.14.0__py3-none-any.whl → 1.16.0__py3-none-any.whl

albert/__init__.py

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

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/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/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/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/collections/custom_templates.py

@@ -3,13 +3,20 @@ 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 PaginationMode
+from albert.core.shared.enums import OrderBy, PaginationMode, Status
 from albert.core.shared.identifiers import CustomTemplateId
-from albert.exceptions import AlbertHTTPError
-from albert.resources.custom_templates import CustomTemplate, CustomTemplateSearchItem
+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):
@@ -31,6 +38,102 @@ class CustomTemplatesCollection(BaseCollection):
         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
 
@@ -52,8 +155,20 @@ class CustomTemplatesCollection(BaseCollection):
         self,
         *,
         text: str | None = None,
-        max_items: int | 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.
@@ -64,20 +179,57 @@ class CustomTemplatesCollection(BaseCollection):
         Parameters
         ----------
         text : str, optional
-            Text to filter search results by.
-        max_items : int, optional
-            Maximum number of items to return in total. If None, fetches all available items.
+            Free text search term.
         offset : int, optional
-            Offset to begin pagination at. Default is 0.
+            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(
@@ -94,32 +246,169 @@ class CustomTemplatesCollection(BaseCollection):
     def get_all(
         self,
         *,
-        text: str | None = None,
+        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,
-        offset: int | None = 0,
     ) -> Iterator[CustomTemplate]:
-        """
-        Retrieve fully hydrated CustomTemplate entities with optional filters.
-
-        This method returns complete entity data using `get_by_id`.
-        Use :meth:`search` for faster retrieval when you only need lightweight, partial (unhydrated) entities.
+        """Iterate over CustomTemplate entities with optional filters.
 
         Parameters
         ----------
-        text : str, optional
-            Text filter for template name or content.
+        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 in total. If None, fetches all available items.
-        offset : int, optional
-            Offset for search pagination.
+            Maximum number of items to return.
 
         Returns
         -------
         Iterator[CustomTemplate]
-            An iterator of CustomTemplate entities.
+            An iterator of CustomTemplates.
         """
-        for item in self.search(text=text, max_items=max_items, offset=offset):
-            try:
-                yield self.get_by_id(id=item.id)
-            except AlbertHTTPError as e:
-                logger.warning(f"Error hydrating custom template {item.id}: {e}")
+        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/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/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/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,

albert/collections/inventory.py

@@ -16,6 +16,7 @@ from albert.core.shared.identifiers import (
     SearchProjectId,
     WorksheetId,
 )
+from albert.core.utils import ensure_list
 from albert.resources.facet import FacetItem
 from albert.resources.inventory import (
     ALL_MERGE_MODULES,
@@ -88,10 +89,10 @@ class InventoryCollection(BaseCollection):
         # define merge endpoint
         url = f"{self.base_path}/merge"
 
-        if isinstance(child_id, list):
-            child_inventories = [{"id": i} for i in child_id]
-        else:
-            child_inventories = [{"id": child_id}]
+        child_ids = ensure_list(child_id) or []
+        if not child_ids:
+            raise ValueError("At least one child inventory id is required for merge operations.")
+        child_inventories = [{"id": i} for i in child_ids]
 
         # define payload using the class
         payload = MergeInventory(
@@ -360,9 +361,9 @@ class InventoryCollection(BaseCollection):
 
         params = {
             "text": text,
-            "order": order.value if order is not None else None,
+            "order": order,
             "sortBy": sort_by if sort_by is not None else None,
-            "category": [c.value for c in category] if category is not None else None,
+            "category": category,
             "tags": tags,
             "manufacturer": [c.name for c in company] if company is not None else None,
             "cas": [c.number for c in cas] if cas is not None else None,
@@ -447,8 +448,7 @@ class InventoryCollection(BaseCollection):
         This can be used for example to fetch all remaining tags as part of an iterative
         refinement of a search.
         """
-        if isinstance(name, str):
-            name = [name]
+        name = ensure_list(name) or []
 
         facets = self.get_all_facets(
             text=text,

albert/collections/lists.py

@@ -92,7 +92,7 @@ class ListsCollection(BaseCollection):
         params = {
             "startKey": start_key,
             "name": names,
-            "category": category.value if isinstance(category, ListItemCategory) else category,
+            "category": category,
             "listType": list_type,
             "orderBy": order_by,
         }

albert/collections/locations.py

@@ -4,6 +4,7 @@ from albert.collections.base import BaseCollection
 from albert.core.pagination import AlbertPaginator
 from albert.core.session import AlbertSession
 from albert.core.shared.enums import PaginationMode
+from albert.core.utils import ensure_list
 from albert.resources.locations import Location
 
 
@@ -64,9 +65,8 @@ class LocationCollection(BaseCollection):
         }
         if ids:
             params["id"] = ids
-        if name:
-            params["name"] = [name] if isinstance(name, str) else name
-            params["exactMatch"] = exact_match
+        params["name"] = ensure_list(name)
+        params["exactMatch"] = exact_match
 
         return AlbertPaginator(
             mode=PaginationMode.KEY,