albert 1.9.1__tar.gz → 1.9.3__tar.gz

{albert-1.9.1 → albert-1.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.9.1
+Version: 1.9.3
 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.9.1 → albert-1.9.3}/src/albert/__init__.py

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

{albert-1.9.1 → albert-1.9.3}/src/albert/collections/lots.py

@@ -7,10 +7,11 @@ from albert.collections.base import BaseCollection
 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.identifiers import InventoryId, LotId
+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.resources.lots import Lot
+from albert.resources.inventory import InventoryCategory
+from albert.resources.lots import Lot, LotSearchItem
 
 # 14 decimal places for inventory on hand delta calculations
 DECIMAL_DELTA_QUANTIZE = Decimal("0.00000000000000")
@@ -120,6 +121,120 @@ class LotCollection(BaseCollection):
         url = f"{self.base_path}?id={id}"
         self.session.delete(url)
 
+    @validate_call
+    def search(
+        self,
+        *,
+        text: str | None = None,
+        inventory_id: InventoryId | list[InventoryId] | None = None,
+        location_id: str | list[str] | None = None,
+        storage_location_id: str | list[str] | None = None,
+        task_id: TaskId | list[TaskId] | None = None,
+        category: InventoryCategory | str | list[InventoryCategory | str] | None = None,
+        external_barcode_id: str | list[str] | None = None,
+        search_field: str | list[str] | None = None,
+        source_field: str | list[str] | None = None,
+        additional_field: str | list[str] | None = None,
+        is_drop_down: bool | None = None,
+        order_by: OrderBy = OrderBy.DESCENDING,
+        sort_by: str | None = None,
+        offset: int | None = None,
+        max_items: int | None = None,
+    ) -> Iterator[LotSearchItem]:
+        """
+        Search for Lot records matching the provided filters.
+
+        ⚠️ 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 query matched against lot fields.
+        inventory_id : InventoryId or list[InventoryId], optional
+            Filter by parent inventory IDs.
+        location_id : str or list[str], optional
+            Filter by specific location IDs.
+        storage_location_id : str or list[str], optional
+            Filter by storage location IDs.
+        task_id : TaskId or list[TaskId], optional
+            Filter by source task IDs.
+        category : InventoryCategory or list[str], optional
+            Filter by parent inventory categories.
+        external_barcode_id : str or list[str], optional
+            Filter by external barcode IDs.
+        search_field : str or list[str], optional
+            Restrict the fields the `text` query searches.
+        source_field : str or list[str], optional
+            Restrict which fields are returned in the response.
+        additional_field : str or list[str], optional
+            Request additional columns from the search index.
+        is_drop_down : bool, optional
+            Use dropdown sanitization for the search text when True.
+        order_by : OrderBy, optional
+            Sort order for the results, default DESCENDING.
+        sort_by : str, optional
+            Attribute to sort by.
+        offset : int, optional
+            Pagination offset to start from.
+        max_items : int, optional
+            Maximum number of items to return in total. If None, fetches all available items.
+
+        Returns
+        -------
+        Iterator[LotSearchItem]
+            An iterator of matching partial (unhydrated) lot entities.
+        """
+
+        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,
+            "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),
+        }
+        params = {key: value for key, value in params.items() if value is not None}
+
+        return AlbertPaginator(
+            mode=PaginationMode.OFFSET,
+            path=f"{self.base_path}/search",
+            session=self.session,
+            params=params,
+            max_items=max_items,
+            deserialize=lambda items: [
+                LotSearchItem(**item)._bind_collection(self) for item in items
+            ],
+        )
+
     @validate_call
     def get_all(
         self,

{albert-1.9.1 → albert-1.9.3}/src/albert/resources/lots.py

@@ -3,9 +3,11 @@ from typing import Any
 
 from pydantic import Field, NonNegativeFloat, field_serializer, field_validator
 
+from albert.core.base import BaseAlbertModel
 from albert.core.shared.identifiers import InventoryId, LotId
 from albert.core.shared.models.base import BaseResource
 from albert.core.shared.types import MetadataItem, SerializeAsEntityLink
+from albert.resources._mixins import HydrationMixin
 from albert.resources.inventory import InventoryCategory
 from albert.resources.locations import Location
 from albert.resources.storage_locations import StorageLocation
@@ -143,3 +145,18 @@ class Lot(BaseResource):
     @field_serializer("inventory_on_hand", return_type=str)
     def serialize_inventory_on_hand(self, inventory_on_hand: NonNegativeFloat):
         return self._format_decimal(inventory_on_hand)
+
+
+class LotSearchItem(BaseAlbertModel, HydrationMixin[Lot]):
+    """Lightweight representation of a Lot returned from search()."""
+
+    id: LotId = Field(alias="albertId")
+    inventory_id: InventoryId | None = Field(default=None, alias="parentId")
+    parent_name: str | None = Field(default=None, alias="parentName")
+    parent_unit: str | None = Field(default=None, alias="parentUnit")
+    parent_category: InventoryCategory | None = Field(default=None, alias="parentIdCategory")
+    task_id: str | None = Field(default=None, alias="taskId")
+    barcode_id: str | None = Field(default=None, alias="barcodeId")
+    expiration_date: str | None = Field(default=None, alias="expirationDate")
+    manufacturer_lot_number: str | None = Field(default=None, alias="manufacturerLotNumber")
+    lot_number: str | None = Field(default=None, alias="number")

{albert-1.9.1 → albert-1.9.3}/src/albert/resources/sheets.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Any, ForwardRef, Union
+from typing import Any, ForwardRef, TypedDict, Union
 
 import pandas as pd
 from pydantic import Field, PrivateAttr, field_validator, model_validator, validate_call
@@ -7,6 +7,7 @@ from pydantic import Field, PrivateAttr, field_validator, model_validator, valid
 from albert.core.base import BaseAlbertModel
 from albert.core.shared.identifiers import InventoryId
 from albert.core.shared.models.base import BaseResource, BaseSessionResource
+from albert.core.shared.models.patch import PatchDatum
 from albert.exceptions import AlbertException
 from albert.resources.inventory import InventoryItem
 
@@ -15,6 +16,18 @@ Row = ForwardRef("Row")
 Column = ForwardRef("Column")
 Sheet = ForwardRef("Sheet")
 
+CellAttributeValue = str | float | int | dict[str, Any] | list[Any] | None
+
+
+class CellChangeId(TypedDict):
+    rowId: str
+    colId: str
+
+
+class CellChangePayload(TypedDict):
+    Id: CellChangeId
+    data: list[PatchDatum]
+
 
 class CellColor(str, Enum):
     """The allowed colors for a cell"""
@@ -611,6 +624,7 @@ class Sheet(BaseSessionResource):  # noqa:F811
         enforce_order: bool = False,
         clear: bool = True,
     ) -> Column:
+        all_cells: list[Cell] = []
         existing_formulation_names = [x.name for x in self.columns]
         if clear and formulation_name in existing_formulation_names:
             # get the existing column and clear it out to put the new formulation in
@@ -618,10 +632,10 @@ class Sheet(BaseSessionResource):  # noqa:F811
             self._clear_formulation_from_column(column=col)
         else:
             col = self.add_formulation_columns(formulation_names=[formulation_name])[0]
-        col_id = col.column_id
+        column_id = col.column_id
 
-        all_cells = []
         self.grid = None  # reset the grid for saftey
+        product_rows = list(self.product_design.rows)
 
         for component in components:
             component_inventory_id = component.inventory_item_id
@@ -629,6 +643,7 @@ class Sheet(BaseSessionResource):  # noqa:F811
                 inventory_id=component_inventory_id,
                 existing_cells=all_cells,
                 enforce_order=enforce_order,
+                product_rows=product_rows,
             )
             if row_id is None:
                 raise AlbertException(f"No Component with id {component_inventory_id}")
@@ -637,7 +652,7 @@ class Sheet(BaseSessionResource):  # noqa:F811
             min_value = str(component.min_value) if component.min_value is not None else None
             max_value = str(component.max_value) if component.max_value is not None else None
             this_cell = Cell(
-                column_id=col_id,
+                column_id=column_id,
                 row_id=row_id,
                 value=value,
                 calculation="",
@@ -651,48 +666,70 @@ class Sheet(BaseSessionResource):  # noqa:F811
             all_cells.append(this_cell)
 
         self.update_cells(cells=all_cells)
-        return self.get_column(column_id=col_id)
+        return self.get_column(column_id=column_id)
 
     def _get_row_id_for_component(
-        self, *, inventory_id: InventoryId, existing_cells, enforce_order
+        self,
+        *,
+        inventory_id: InventoryId,
+        existing_cells,
+        enforce_order,
+        product_rows: list["Row"],
     ):
-        self.grid = None
-
-        # within a sheet, the "INV" prefix is dropped
         sheet_inv_id = inventory_id
-        matching_rows = [x for x in self.product_design.rows if x.inventory_id == sheet_inv_id]
+        matching_rows = [row for row in product_rows if row.inventory_id == sheet_inv_id]
+
+        used_row_ids = [cell.row_id for cell in existing_cells]
 
-        used_row_ids = [x.row_id for x in existing_cells]
+        existing_inv_order: list[str] = []
+        index_last_row = 0
         if enforce_order:
             existing_inv_order = [
-                x.row_id for x in self.product_design.rows if x.inventory_id is not None
+                row.row_id for row in product_rows if row.inventory_id is not None
             ]
-            index_last_row = 0
             for row_id in used_row_ids:
                 if row_id in existing_inv_order:
                     this_row_index = existing_inv_order.index(row_id)
                     if this_row_index > index_last_row:
                         index_last_row = this_row_index
-        for r in matching_rows:
-            if r.row_id not in used_row_ids:
-                if enforce_order:
-                    if existing_inv_order.index(r.row_id) >= index_last_row:
-                        return r.row_id
-                    else:
-                        continue
-                else:
-                    return r.row_id
-        # Otherwise I need to add a new row
+
+        for row in matching_rows:
+            if row.row_id in used_row_ids:
+                continue
+            if not enforce_order:
+                return row.row_id
+
+            if row.row_id in existing_inv_order:
+                if existing_inv_order.index(row.row_id) >= index_last_row:
+                    return row.row_id
+                continue
+
         if enforce_order:
-            return self.add_inventory_row(
-                inventory_id=inventory_id,
-                position={
-                    "reference_id": existing_inv_order[index_last_row],
-                    "position": "below",
-                },
-            ).row_id
-        else:
-            return self.add_inventory_row(inventory_id=inventory_id).row_id
+            if existing_inv_order:
+                reference_row_id = existing_inv_order[index_last_row]
+                new_row = self.add_inventory_row(
+                    inventory_id=inventory_id,
+                    position={"reference_id": reference_row_id, "position": "below"},
+                )
+
+                insert_position = None
+                for idx, row in enumerate(product_rows):
+                    if row.row_id == reference_row_id:
+                        insert_position = idx + 1
+                        break
+                if insert_position is None:
+                    product_rows.append(new_row)
+                else:
+                    product_rows.insert(insert_position, new_row)
+                return new_row.row_id
+
+            new_row = self.add_inventory_row(inventory_id=inventory_id)
+            product_rows.append(new_row)
+            return new_row.row_id
+
+        new_row = self.add_inventory_row(inventory_id=inventory_id)
+        product_rows.append(new_row)
+        return new_row.row_id
 
     def add_formulation_columns(
         self,
@@ -816,69 +853,79 @@ class Sheet(BaseSessionResource):  # noqa:F811
         return (updated, failed)
 
     def _get_current_cell(self, *, cell: Cell) -> Cell:
-        filtered_columns = [
-            col for col in self.grid.columns if col.startswith(cell.column_id + "#")
-        ]
-        filtered_rows = [
-            idx for idx in self.grid.index if idx.startswith(cell.design_id + "#" + cell.row_id)
-        ]
+        def _matches_column(column_label: str) -> bool:
+            col_parts = column_label.split("#", 1)
+            return col_parts[0] == cell.column_id
+
+        def _matches_row(index_label: str) -> bool:
+            row_parts = index_label.split("#", 2)
+            if len(row_parts) < 2:
+                return False
+            return row_parts[0] == cell.design_id and row_parts[1] == cell.row_id
+
+        filtered_columns = [col for col in self.grid.columns if _matches_column(col)]
+        filtered_rows = [idx for idx in self.grid.index if _matches_row(idx)]
 
-        first_value = None
         for row in filtered_rows:
             for col in filtered_columns:
-                first_value = self.grid.loc[row, col]
-                return first_value
-        return first_value
+                return self.grid.loc[row, col]
+        return None
 
-    def _generate_attribute_change(self, *, new_value, old_value, api_attribute_name):
+    def _generate_attribute_change(
+        self,
+        *,
+        new_value: CellAttributeValue,
+        old_value: CellAttributeValue,
+        api_attribute_name: str,
+    ) -> PatchDatum | None:
         """Generates a change dictionary for a single attribute."""
         if new_value == old_value:
             return None
 
         if new_value is None or new_value in ("", {}):
-            return {
-                "operation": "delete",
-                "attribute": api_attribute_name,
-                "oldValue": old_value,
-            }
+            return PatchDatum(
+                operation="delete",
+                attribute=api_attribute_name,
+                old_value=old_value,
+            )
         if old_value is None or old_value in ("", {}):
-            return {
-                "operation": "add",
-                "attribute": api_attribute_name,
-                "newValue": new_value,
-            }
-        return {
-            "operation": "update",
-            "attribute": api_attribute_name,
-            "oldValue": old_value,
-            "newValue": new_value,
-        }
+            return PatchDatum(
+                operation="add",
+                attribute=api_attribute_name,
+                new_value=new_value,
+            )
+        return PatchDatum(
+            operation="update",
+            attribute=api_attribute_name,
+            old_value=old_value,
+            new_value=new_value,
+        )
 
-    def _get_cell_changes(self, *, cell: Cell) -> dict:
+    def _get_cell_changes(self, *, cell: Cell) -> CellChangePayload | None:
         current_cell = self._get_current_cell(cell=cell)
         if current_cell is None:
             return None
 
-        data = []
+        data: list[PatchDatum] = []
 
         # Handle format change
         if cell.format != current_cell.format:
             if cell.format is None or cell.format == {}:
                 data.append(
-                    {
-                        "operation": "delete",
-                        "attribute": "cellFormat",
-                        "oldValue": current_cell.format,
-                    }
+                    PatchDatum(
+                        operation="delete",
+                        attribute="cellFormat",
+                        old_value=current_cell.format,
+                    )
                 )
             else:
                 data.append(
-                    {
-                        "operation": "update",
-                        "attribute": "cellFormat",
-                        "oldValue": current_cell.format,
-                        "newValue": cell.format,
-                    }
+                    PatchDatum(
+                        operation="update",
+                        attribute="cellFormat",
+                        old_value=current_cell.format,
+                        new_value=cell.format,
+                    )
                 )
 
         # Handle calculation change
@@ -937,9 +984,9 @@ class Sheet(BaseSessionResource):  # noqa:F811
         return False
 
     def update_cells(self, *, cells: list[Cell]):
-        request_path_dict = {}
-        updated = []
-        failed = []
+        request_path_dict: dict[str, list[Cell]] = {}
+        updated: list[Cell] = []
+        failed: list[Cell] = []
         # sort by design ID
         for c in cells:
             if c.design_id not in request_path_dict:
@@ -948,57 +995,89 @@ class Sheet(BaseSessionResource):  # noqa:F811
                 request_path_dict[c.design_id].append(c)
 
         for design_id, cell_list in request_path_dict.items():
-            payloads = []
+            payload_entries: list[tuple[CellChangePayload, Cell]] = []
             for cell in cell_list:
                 change_dict = self._get_cell_changes(cell=cell)
-                if change_dict is not None:
-                    # For non-calculation cells, only one change is allowed at a time.
-                    is_calculation_cell = cell.calculation is not None and cell.calculation != ""
-                    max_items = 2 if is_calculation_cell else 1
-
-                    if len(change_dict["data"]) > max_items:
-                        for item in change_dict["data"]:
-                            payloads.append(
-                                {
-                                    "Id": change_dict["Id"],
-                                    "data": [item],
-                                }
-                            )
-                    else:
-                        payloads.append(change_dict)
-
-            if not payloads:
+                if change_dict is None:
+                    continue
+
+                is_calculation_cell = cell.calculation is not None and cell.calculation != ""
+                max_items = 2 if is_calculation_cell else 1
+
+                if len(change_dict["data"]) > max_items:
+                    for item in change_dict["data"]:
+                        single_change: CellChangePayload = {
+                            "Id": change_dict["Id"],
+                            "data": [item],
+                        }
+                        payload_entries.append((single_change, cell))
+                else:
+                    payload_entries.append((change_dict, cell))
+
+            if not payload_entries:
                 continue
 
             this_url = f"/api/v3/worksheet/{design_id}/values"
-            for payload in payloads:
-                response = self.session.patch(
-                    this_url,
-                    json=[payload],  # The API expects a list of changes
-                )
-
-                original_cell = next(
-                    (
-                        c
-                        for c in cell_list
-                        if c.row_id == payload["Id"]["rowId"]
-                        and c.column_id == payload["Id"]["colId"]
-                    ),
-                    None,
-                )
+            pending_by_cell: dict[tuple[str, str], list[tuple[CellChangePayload, Cell]]] = {}
+            for payload, cell in payload_entries:
+                key = (payload["Id"]["rowId"], payload["Id"]["colId"])
+                pending_by_cell.setdefault(key, []).append((payload, cell))
+
+            ordered_keys = list(pending_by_cell.keys())
+
+            def _unique_cells(cells: list[Cell]) -> list[Cell]:
+                seen: set[tuple[str, str, str]] = set()
+                result: list[Cell] = []
+                for c in cells:
+                    key = (c.design_id, c.row_id, c.column_id)
+                    if key not in seen:
+                        seen.add(key)
+                        result.append(c)
+                return result
+
+            batch_index = 0
+            while True:
+                batch_payloads: list[CellChangePayload] = []
+                batch_cells: list[Cell] = []
+                for key in ordered_keys:
+                    queue = pending_by_cell.get(key)
+                    if queue:
+                        payload, cell = queue.pop(0)
+                        batch_payloads.append(payload)
+                        batch_cells.append(cell)
+                if not batch_payloads:
+                    break
+
+                payload_body = [
+                    {
+                        "Id": payload["Id"],
+                        "data": [datum.model_dump(by_alias=True) for datum in payload["data"]],
+                    }
+                    for payload in batch_payloads
+                ]
+                response = self.session.patch(this_url, json=payload_body)
+                target_cells = _unique_cells(batch_cells)
 
                 if response.status_code == 204:
-                    if original_cell and original_cell not in updated:
-                        updated.append(original_cell)
+                    for c in target_cells:
+                        if c not in updated:
+                            updated.append(c)
                 elif response.status_code == 206:
                     cell_results = self._filter_cells(
-                        cells=[original_cell], response_dict=response.json()
+                        cells=target_cells, response_dict=response.json()
                     )
-                    updated.extend(cell_results[0])
-                    failed.extend(cell_results[1])
+                    for c in cell_results[0]:
+                        if c not in updated:
+                            updated.append(c)
+                    for c in cell_results[1]:
+                        if c not in failed:
+                            failed.append(c)
                 else:
-                    if original_cell and original_cell not in failed:
-                        failed.append(original_cell)
+                    for c in target_cells:
+                        if c not in failed:
+                            failed.append(c)
+
+                batch_index += 1
 
         # reset the in-memory grid after updates
         self.grid = None

{albert-1.9.1 → albert-1.9.3}/tests/collections/test_inventory.py

@@ -144,7 +144,6 @@ def test_inventory_update(client: Albert, seed_prefix: str):
         company="",
     )
     created = client.inventory.create(inventory_item=ii)
-
     # Give time for the DB to sync - somewhere between 1 and 4 seconds is needed
     # for this test to work
     time.sleep(4)