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

albert/collections/lots.py

@@ -10,6 +10,7 @@ from albert.core.session import AlbertSession
 from albert.core.shared.enums import OrderBy, PaginationMode
 from albert.core.shared.identifiers import InventoryId, LotId, TaskId
 from albert.core.shared.models.patch import PatchDatum, PatchOperation, PatchPayload
+from albert.core.utils import ensure_list
 from albert.resources.inventory import InventoryCategory
 from albert.resources.lots import Lot, LotSearchItem
 
@@ -188,39 +189,21 @@ class LotCollection(BaseCollection):
 
         search_text = text if (text is None or len(text) < 50) else text[:50]
 
-        def _ensure_list(value):
-            if value is None:
-                return None
-            if isinstance(value, list | tuple | set):
-                return list(value)
-            return [value]
-
-        def _format_categories(value):
-            raw = _ensure_list(value)
-            if raw is None:
-                return None
-            formatted: list[str] = []
-            for category in raw:
-                formatted.append(
-                    category.value if isinstance(category, InventoryCategory) else category
-                )
-            return formatted
-
         params = {
             "offset": offset,
-            "order": order_by.value,
+            "order": order_by,
             "text": search_text,
             "sortBy": sort_by,
             "isDropDown": is_drop_down,
-            "inventoryId": _ensure_list(inventory_id),
-            "locationId": _ensure_list(location_id),
-            "storageLocationId": _ensure_list(storage_location_id),
-            "taskId": _ensure_list(task_id),
-            "category": _format_categories(category),
-            "externalBarcodeId": _ensure_list(external_barcode_id),
-            "searchField": _ensure_list(search_field),
-            "sourceField": _ensure_list(source_field),
-            "additionalField": _ensure_list(additional_field),
+            "inventoryId": ensure_list(inventory_id),
+            "locationId": ensure_list(location_id),
+            "storageLocationId": ensure_list(storage_location_id),
+            "taskId": ensure_list(task_id),
+            "category": ensure_list(category),
+            "externalBarcodeId": ensure_list(external_barcode_id),
+            "searchField": ensure_list(search_field),
+            "sourceField": ensure_list(source_field),
+            "additionalField": ensure_list(additional_field),
         }
         params = {key: value for key, value in params.items() if value is not None}
 

albert/collections/notes.py

@@ -106,7 +106,7 @@ class NotesCollection(BaseCollection):
         """
         params = {
             "parentId": parent_id,
-            "orderBy": order_by.value,
+            "orderBy": order_by,
         }
         response = self.session.get(
             url=self.base_path,

albert/collections/parameter_groups.py

@@ -10,6 +10,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 ParameterGroupId
+from albert.core.utils import ensure_list
 from albert.exceptions import AlbertHTTPError
 from albert.resources.parameter_groups import (
     ParameterGroup,
@@ -97,9 +98,9 @@ class ParameterGroupCollection(BaseCollection):
         """
         params = {
             "offset": offset,
-            "order": order_by.value,
+            "order": order_by,
             "text": text,
-            "types": [types] if isinstance(types, PGType) else types,
+            "types": ensure_list(types),
         }
 
         return AlbertPaginator(

albert/collections/parameters.py

@@ -8,6 +8,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 ParameterId
+from albert.core.utils import ensure_list
 from albert.resources.parameters import Parameter
 
 
@@ -137,13 +138,12 @@ class ParameterCollection(BaseCollection):
             yield from (Parameter(**item) for item in items)
 
         params = {
-            "orderBy": order_by.value,
+            "orderBy": order_by,
             "parameters": ids,
             "startKey": start_key,
         }
-        if names:
-            params["name"] = [names] if isinstance(names, str) else names
-            params["exactMatch"] = exact_match
+        params["name"] = ensure_list(names)
+        params["exactMatch"] = exact_match
 
         return AlbertPaginator(
             mode=PaginationMode.KEY,

albert/collections/projects.py

@@ -7,9 +7,9 @@ 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 ProjectId
+from albert.core.shared.identifiers import ProjectId, SearchProjectId
 from albert.exceptions import AlbertHTTPError
-from albert.resources.projects import Project, ProjectSearchItem
+from albert.resources.projects import DocumentSearchItem, Project, ProjectSearchItem
 
 
 class ProjectCollection(BaseCollection):
@@ -187,7 +187,7 @@ class ProjectCollection(BaseCollection):
             An iterator of matching partial (unhydrated) Project results.
         """
         query_params = {
-            "order": order_by.value,
+            "order": order_by,
             "offset": offset,
             "text": text,
             "sortBy": sort_by,
@@ -219,6 +219,47 @@ class ProjectCollection(BaseCollection):
             ],
         )
 
+    @validate_call
+    def document_search(
+        self,
+        *,
+        linked_to: SearchProjectId,
+        text: str | None = None,
+        order_by: OrderBy = OrderBy.DESCENDING,
+        sort_by: str | None = None,
+        offset: int | None = None,
+        max_items: int | None = None,
+    ) -> Iterator[DocumentSearchItem]:
+        """Search for documents (attachments) linked to a project.
+
+        Args:
+            linked_to: The project ID to filter documents by (e.g. "P770").
+            text: Full-text search query for document names.
+            order_by: Sort order. Default is DESCENDING.
+            sort_by: Field to sort by (e.g. "createdAt").
+            offset: Pagination offset.
+            max_items: Maximum number of items to return. If None, fetches all.
+
+        Returns:
+            An iterator of DocumentSearchItem results.
+        """
+        query_params = {
+            "linkedTo": linked_to,
+            "text": text,
+            "order": order_by,
+            "sortBy": sort_by,
+            "offset": offset,
+        }
+
+        return AlbertPaginator(
+            mode=PaginationMode.OFFSET,
+            path=f"{self.base_path}/documentsearch",
+            session=self.session,
+            params=query_params,
+            max_items=max_items,
+            deserialize=lambda items: [DocumentSearchItem(**item) for item in items],
+        )
+
     @validate_call
     def get_all(
         self,

albert/collections/property_data.py

@@ -1,6 +1,5 @@
 from collections.abc import Iterator
 from contextlib import suppress
-from enum import Enum
 
 import pandas as pd
 from pydantic import validate_call
@@ -23,6 +22,7 @@ from albert.core.shared.identifiers import (
     UserId,
 )
 from albert.core.shared.models.patch import PatchOperation
+from albert.core.utils import ensure_list
 from albert.exceptions import NotFoundError
 from albert.resources.property_data import (
     BulkPropertyData,
@@ -1086,22 +1086,19 @@ class PropertyDataCollection(BaseCollection):
         def deserialize(items: list[dict]) -> list[PropertyDataSearchItem]:
             return [PropertyDataSearchItem.model_validate(x) for x in items]
 
-        def ensure_list(v):
-            if v is None:
-                return None
-            return [v] if isinstance(v, str | Enum) else v
+        category_values = ensure_list(category)
 
         params = {
             "result": result,
             "text": text,
-            "order": order.value if order else None,
+            "order": order,
             "sortBy": sort_by,
             "inventoryIds": ensure_list(inventory_ids),
             "projectIds": ensure_list(project_ids),
             "lotIds": ensure_list(lot_ids),
             "dataTemplateId": ensure_list(data_template_ids),
             "dataColumnId": ensure_list(data_column_ids),
-            "category": [c.value for c in ensure_list(category)] if category else None,
+            "category": category_values if category_values else None,
             "dataTemplates": ensure_list(data_templates),
             "dataColumns": ensure_list(data_columns),
             "parameters": ensure_list(parameters),

albert/collections/storage_locations.py

@@ -7,6 +7,7 @@ from albert.core.pagination import AlbertPaginator
 from albert.core.session import AlbertSession
 from albert.core.shared.enums import PaginationMode
 from albert.core.shared.models.base import EntityLink
+from albert.core.utils import ensure_list
 from albert.exceptions import AlbertHTTPError
 from albert.resources.locations import Location
 from albert.resources.storage_locations import StorageLocation
@@ -93,9 +94,8 @@ class StorageLocationsCollection(BaseCollection):
             "startKey": start_key,
         }
 
-        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,

albert/collections/tags.py

@@ -9,6 +9,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 TagId
+from albert.core.utils import ensure_list
 from albert.exceptions import AlbertException
 from albert.resources.tags import Tag
 
@@ -258,12 +259,12 @@ class TagCollection(BaseCollection):
             An iterator of Tag entities matching the filters.
         """
         params = {
-            "orderBy": order_by.value,
+            "orderBy": order_by,
             "startKey": start_key,
         }
 
         if name:
-            params["name"] = [name] if isinstance(name, str) else name
+            params["name"] = ensure_list(name)
             params["exactMatch"] = exact_match
 
         return AlbertPaginator(

albert/collections/tasks.py

@@ -25,6 +25,7 @@ from albert.core.shared.identifiers import (
     WorkflowId,
     remove_id_prefix,
 )
+from albert.core.utils import ensure_list
 from albert.exceptions import AlbertHTTPError
 from albert.resources.attachments import AttachmentCategory
 from albert.resources.data_templates import ImportMode
@@ -570,13 +571,12 @@ class TaskCollection(BaseCollection):
 
         params = {
             "offset": offset,
-            "order": order_by.value,
+            "order": order_by,
             "text": text,
             "sortBy": sort_by,
             "tags": tags,
             "taskId": task_id,
             "linkedTask": linked_task,
-            "category": category,
             "albertId": albert_id,
             "dataTemplate": data_template,
             "assignedTo": assigned_to,
@@ -588,6 +588,9 @@ class TaskCollection(BaseCollection):
             "projectId": project_id,
         }
 
+        category_values = ensure_list(category)
+        params["category"] = category_values if category_values else None
+
         return AlbertPaginator(
             mode=PaginationMode.OFFSET,
             path=f"{self.base_path}/search",
@@ -749,7 +752,7 @@ class TaskCollection(BaseCollection):
         """Fetch the audit history for the specified task."""
         params = {
             "limit": limit,
-            "orderBy": OrderBy(order).value if order else None,
+            "orderBy": order,
             "entity": entity,
             "blockId": blockId,
             "startKey": startKey,

albert/collections/units.py

@@ -8,6 +8,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 UnitId
+from albert.core.utils import ensure_list
 from albert.resources.units import Unit, UnitCategory
 
 
@@ -192,11 +193,11 @@ class UnitCollection(BaseCollection):
             An iterator of Unit entities.
         """
         params = {
-            "orderBy": order_by.value,
-            "name": [name] if isinstance(name, str) else name,
+            "orderBy": order_by,
+            "name": ensure_list(name),
             "exactMatch": exact_match,
             "verified": verified,
-            "category": category.value if isinstance(category, UnitCategory) else category,
+            "category": category,
             "startKey": start_key,
         }
 

albert/collections/users.py

@@ -135,7 +135,7 @@ class UserCollection(BaseCollection):
         params = {
             "text": text,
             "sortBy": sort_by,
-            "order": order_by.value,
+            "order": order_by,
             "roles": roles,
             "teams": teams,
             "locations": locations,
@@ -198,7 +198,7 @@ class UserCollection(BaseCollection):
         """
         params = {
             "status": status,
-            "type": type.value if type else None,
+            "type": type,
             "id": id,
             "startKey": start_key,
         }

albert/core/utils.py

@@ -0,0 +1,20 @@
+"""Utility helpers shared across Albert SDK modules."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def ensure_list(value: T | Iterable[T] | None) -> list[T] | None:
+    """Return ``value`` as a list, preserving ``None`` and existing lists."""
+
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple | set):
+        return list(value)
+    return [value]

albert/resources/custom_templates.py

@@ -5,7 +5,7 @@ from pydantic import Field, model_validator
 
 from albert.core.base import BaseAlbertModel
 from albert.core.shared.enums import SecurityClass, Status
-from albert.core.shared.identifiers import CustomTemplateId, NotebookId
+from albert.core.shared.identifiers import CustomTemplateId, EntityTypeId, NotebookId
 from albert.core.shared.models.base import BaseResource, EntityLink
 from albert.core.shared.types import MetadataItem, SerializeAsEntityLink
 from albert.resources._mixins import HydrationMixin
@@ -19,16 +19,27 @@ from albert.resources.tasks import TaskSource
 from albert.resources.users import User, UserClass
 
 
+class CustomTemplateInventoryLot(BaseAlbertModel):
+    id: str
+    barcode: str | None = None
+
+
 class DataTemplateInventory(EntityLink):
     batch_size: float | None = Field(default=None, alias="batchSize")
     sheet: list[Sheet | EntityLink] | None = Field(default=None)
     category: InventoryCategory | None = Field(default=None)
+    lots: list[CustomTemplateInventoryLot] | None = Field(default=None, alias="Lots")
 
 
 class DesignLink(EntityLink):
     type: DesignType
 
 
+class TemplateEntityType(BaseAlbertModel):
+    id: EntityTypeId | None = Field(default=None)
+    custom_category: str | None = Field(default=None, alias="customCategory")
+
+
 class TemplateCategory(str, Enum):
     PROPERTY_LIST = "Property Task"
     PROPERTY = "Property"
@@ -55,6 +66,7 @@ class GeneralData(BaseTaggedResource):
     priority: Priority | None = Field(default=None)
     sources: list[TaskSource] | None = Field(alias="Sources", default=None)
     parent_id: str | None = Field(alias="parentId", default=None)
+    metadata: dict[str, MetadataItem] | None = Field(default=None, alias="Metadata")
 
 
 class JobStatus(str, Enum):
@@ -79,7 +91,7 @@ class SamConfig(BaseResource):
 
 class Workflow(BaseResource):
     id: str
-    name: str
+    name: str | None = Field(default=None)
     # Some workflows may have SamConfig
     sam_config: list[SamConfig] | None = Field(default=None, alias="SamConfig")
 
@@ -176,7 +188,7 @@ class TemplateACL(BaseResource):
     acl_class: str | None = Field(default=None, alias="class")
 
 
-class CustomTemplate(BaseTaggedResource):
+class CustomTemplate(BaseTaggedResource, HydrationMixin["CustomTemplate"]):
     """A custom template entity.
 
     Attributes
@@ -186,11 +198,15 @@ class CustomTemplate(BaseTaggedResource):
     id : str
         The Albert ID of the template. Set when the template is retrieved from Albert.
     category : TemplateCategory
-        The category of the template. Allowed values are `Property Task`, `Property`, `Batch`, `Sheet`, `Notebook`, and `General`.
+        The category of the template.
     metadata : Dict[str, str | List[EntityLink] | EntityLink] | None
         The metadata of the template. Allowed Metadata fields can be found using Custim Fields.
     data : CustomTemplateData | None
         The data of the template.
+    entity_type : TemplateEntityType | None
+        The entity type associated with the template.
+    locked : bool | None
+        Whether the template is locked when loaded in the UI.
     team : List[TeamACL] | None
         The team of the template.
     acl : TemplateACL | None
@@ -198,10 +214,12 @@ class CustomTemplate(BaseTaggedResource):
     """
 
     name: str
-    id: CustomTemplateId = Field(alias="albertId")
+    id: CustomTemplateId | None = Field(default=None, alias="albertId")
     category: TemplateCategory = Field(default=TemplateCategory.GENERAL)
     metadata: dict[str, MetadataItem] | None = Field(default=None, alias="Metadata")
     data: CustomTemplateData | None = Field(default=None, alias="Data")
+    entity_type: TemplateEntityType | None = Field(default=None, alias="EntityType")
+    locked: bool | None = Field(default=None)
     team: list[TeamACL] | None = Field(default_factory=list)
     acl: TemplateACL | None = Field(default_factory=list, alias="ACL")
 
@@ -211,9 +229,13 @@ class CustomTemplate(BaseTaggedResource):
         """
         Initialize private attributes from the incoming data dictionary before the model is fully constructed.
         """
+        if not isinstance(data, dict):
+            return data
 
-        if "Data" in data and "category" in data and "category" not in data["Data"]:
-            data["Data"]["category"] = data["category"]
+        data_payload = data.get("Data")
+        category = data.get("category")
+        if isinstance(data_payload, dict) and category is not None:
+            data_payload.setdefault("category", category)
         return data
 
 
@@ -241,9 +263,9 @@ class CustomTemplateSearchItem(BaseAlbertModel, HydrationMixin[CustomTemplate]):
     id: CustomTemplateId = Field(alias="albertId")
     created_by_name: str = Field(..., alias="createdByName")
     created_at: str = Field(..., alias="createdAt")
-    category: str
+    category: str | None = None
     status: Status | None = None
     resource_class: SecurityClass | None = Field(default=None, alias="resourceClass")
     data: CustomTemplateSearchItemData | None = None
-    acl: list[CustomTemplateSearchItemACL]
-    team: list[CustomTemplateSearchItemTeam]
+    acl: list[CustomTemplateSearchItemACL] | None = None
+    team: list[CustomTemplateSearchItemTeam] | None = None

albert/resources/projects.py

@@ -3,7 +3,7 @@ from enum import Enum
 from pydantic import Field, field_validator
 
 from albert.core.base import BaseAlbertModel
-from albert.core.shared.identifiers import ProjectId
+from albert.core.shared.identifiers import AttachmentId, ProjectId
 from albert.core.shared.models.base import BaseResource
 from albert.core.shared.types import MetadataItem, SerializeAsEntityLink
 from albert.resources._mixins import HydrationMixin
@@ -110,3 +110,18 @@ class ProjectSearchItem(BaseAlbertModel, HydrationMixin[Project]):
     id: ProjectId | None = Field(None, alias="albertId")
     description: str = Field(min_length=1, max_length=2000)
     status: str | None = Field(default=None, exclude=True, frozen=True)
+
+
+class DocumentSearchItem(BaseAlbertModel):
+    """A document (attachment) search result item from a project."""
+
+    id: AttachmentId | None = Field(None, alias="albertId")
+    name: str | None = None
+    mime_type: str | None = Field(default=None, alias="mimeType")
+    file_size: int | None = Field(default=None, alias="fileSize")
+    project_id: str | None = Field(default=None, alias="projectId")
+    key: str | None = None
+    source: str | None = None
+    created_by: str | None = Field(default=None, alias="createdBy")
+    created_by_name: str | None = Field(default=None, alias="createdByName")
+    created_at: str | None = Field(default=None, alias="createdAt")

albert/resources/tags.py

@@ -1,13 +1,10 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import Any
 
-from pydantic import AliasChoices, Field, model_validator
+from pydantic import AliasChoices, Field
 
-from albert.core.logging import logger
 from albert.core.shared.models.base import BaseResource
-from albert.core.shared.types import SerializeAsEntityLink
 
 
 class TagEntity(str, Enum):
@@ -62,40 +59,3 @@ class Tag(BaseResource):
             The Tag object created from the string.
         """
         return cls(tag=tag)
-
-
-class BaseTaggedEntity(BaseResource):
-    """
-    BaseTaggedEntity is a Pydantic model that includes functionality for handling tags as either Tag objects or strings.
-
-    Attributes
-    ----------
-    tags : List[Tag | str] | None
-        A list of Tag objects or strings representing tags.
-    """
-
-    tags: list[SerializeAsEntityLink[Tag]] | None = Field(None, alias="Tags")
-
-    @model_validator(mode="before")  # must happen before to keep type validation
-    @classmethod
-    def convert_tags(cls, data: dict[str, Any]) -> dict[str, Any]:
-        if not isinstance(data, dict):
-            return data
-        tags = data.get("tags")
-        if not tags:
-            tags = data.get("Tags")
-        if tags:
-            new_tags = []
-            for t in tags:
-                if isinstance(t, Tag):
-                    new_tags.append(t)
-                elif isinstance(t, str):
-                    new_tags.append(Tag.from_string(t))
-                elif isinstance(t, dict):
-                    new_tags.append(Tag(**t))
-                else:
-                    # We do not expect this else to be hit because tags should only be Tag or str
-                    logger.warning(f"Unexpected value for Tag. {t} of type {type(t)}")
-                    continue
-            data["tags"] = new_tags
-        return data

{albert-1.14.0.dist-info → albert-1.16.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.14.0
+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