wizata-dsapi 2.2.0.dev22__tar.gz → 2.2.0.dev24__tar.gz

{wizata_dsapi-2.2.0.dev22 → wizata_dsapi-2.2.0.dev24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wizata_dsapi
-Version: 2.2.0.dev22
+Version: 2.2.0.dev24
 Summary: Wizata Data Science Toolkit
 Author: Wizata S.A.
 Author-email: info@wizata.com

{wizata_dsapi-2.2.0.dev22 → wizata_dsapi-2.2.0.dev24}/wizata_dsapi/__init__.py

@@ -75,6 +75,8 @@ from .connection_discovery import ConnectionSeenName, ConnectionSeenReport, Conn
 from .product import ProductKind, Product, ProductComponent, BUILTIN_PRODUCT_KINDS, is_valid_product_key
 from .inventory import (InventoryBalance, InventoryStorage, InventoryStorageDatapoint, inventory_mode,
                         InventoryStock, InventoryStockProduct, InventoryStockLine, InventoryStockCount, INVENTORY_OPTION, INVENTORY_MODES,
+                        InventoryCount, InventoryCountLine, InventoryCountControl, InventoryHistory,
+                        InventoryHistoryEvent, HISTORY_MOVEMENT, HISTORY_COUNT, round_quantity,
                         INVENTORY_MOVEMENTS, INVENTORY_BALANCES, INVENTORY_STOCK,
                         PRODUCT_TAG, PRODUCT_MESSAGE_KEY)
 from .dashboard import Dashboard, DashboardType

{wizata_dsapi-2.2.0.dev22 → wizata_dsapi-2.2.0.dev24}/wizata_dsapi/inventory.py

@@ -311,3 +311,260 @@ class InventoryStock:
     @classmethod
     def from_dict(cls, data: dict) -> "InventoryStock":
         return cls(as_of=data.get("asOf"), products=[InventoryStockProduct.from_dict(p) for p in data.get("products") or []])
+
+
+def round_quantity(value):
+    """
+    A quantity kept to 12 significant digits: every real digit, none of the binary noise
+    that sums and unit conversions leave (0.1 + 0.2, 540000 mL in L). Expected and counted
+    levels are compared after this, so a count that matches is never off by 1e-13.
+    """
+    if value is None:
+        return None
+    return float(f"{float(value):.12g}")
+
+
+def _twin_dict(twin_id, hardware_id, name) -> Optional[dict]:
+    if twin_id is None and hardware_id is None:
+        return None
+    return {"id": twin_id, "hardwareId": hardware_id, "name": name}
+
+
+class InventoryCountLine:
+    """
+    One line of a count (DEV-6128): the balance, its storage, and what the movements
+    predicted at that moment. ``expected`` is the stock just before this count, without
+    it: the count before it plus the movements since, in the datapoint's unit. With no
+    count before it there is nothing to check: ``expected``, ``difference`` and
+    ``verified`` are None (this count is the opening level).
+    """
+
+    def __init__(self, balance: InventoryBalance = None, twin_id=None, twin_hardware_id: str = None,
+                 twin_name: str = None, unit=None, unit_symbol: str = None, expected: float = None):
+        self.balance: InventoryBalance = balance if balance is not None else InventoryBalance()
+        self.twin_id: Optional[str] = _uuid_str(twin_id)
+        self.twin_hardware_id: Optional[str] = twin_hardware_id
+        self.twin_name: Optional[str] = twin_name
+        self.unit: Optional[str] = _uuid_str(unit)
+        self.unit_symbol: Optional[str] = unit_symbol
+        self.expected: Optional[float] = expected
+
+    @property
+    def difference(self) -> Optional[float]:
+        """Counted minus expected: negative when stock went missing."""
+        if self.expected is None or self.balance.quantity is None:
+            return None
+        return round_quantity(round_quantity(self.balance.quantity) - round_quantity(self.expected))
+
+    @property
+    def verified(self) -> Optional[bool]:
+        """The count matches the movements exactly (after unit rounding)."""
+        if self.expected is None or self.balance.quantity is None:
+            return None
+        return round_quantity(self.balance.quantity) == round_quantity(self.expected)
+
+    def to_dict(self) -> dict:
+        obj = self.balance.to_dict()
+        obj.update({"twin": _twin_dict(self.twin_id, self.twin_hardware_id, self.twin_name),
+                    "unit": self.unit, "unitSymbol": self.unit_symbol, "expected": self.expected,
+                    "difference": self.difference, "verified": self.verified})
+        return obj
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "InventoryCountLine":
+        twin = data.get("twin") or {}
+        balance = InventoryBalance.from_dict({k: v for k, v in data.items() if k != "unit"})
+        return cls(balance=balance, twin_id=twin.get("id"), twin_hardware_id=twin.get("hardwareId"),
+                   twin_name=twin.get("name"), unit=data.get("unit"), unit_symbol=data.get("unitSymbol"),
+                   expected=data.get("expected"))
+
+
+class InventoryCount:
+    """
+    A count as one object (DEV-6128): every balance written by one call shares its
+    ``count`` key. ``timestamp`` is the moment they were all counted, or None when an
+    API sync wrote several moments in one call (each line then carries its own).
+
+    Read with ``GET /dsapi/planner/inventory/counts/<count>/``, replaced with ``PUT``
+    (the count becomes exactly the lines sent, all or none), deleted with ``DELETE``.
+    """
+
+    def __init__(self, count=None, lines: list = None):
+        self.count: Optional[str] = _uuid_str(count)
+        self.lines: list = list(lines or [])
+
+    @property
+    def timestamp(self) -> Optional[datetime]:
+        moments = {line.balance.timestamp for line in self.lines}
+        return moments.pop() if len(moments) == 1 else None
+
+    def _first(self, attribute: str, latest: bool = False):
+        stamped = [(getattr(l.balance, attribute + "_at"), getattr(l.balance, attribute + "_by"))
+                   for l in self.lines if getattr(l.balance, attribute + "_at") is not None]
+        if not stamped:
+            return None, None
+        return (max if latest else min)(stamped, key=lambda s: s[0])
+
+    def to_dict(self) -> dict:
+        created_at, created_by = self._first("created")
+        updated_at, updated_by = self._first("updated", latest=True)
+        timestamp = self.timestamp
+        return {"count": self.count,
+                "timestamp": _ts_out(timestamp) if isinstance(timestamp, datetime) else timestamp,
+                "createdAt": _ts_out(created_at) if isinstance(created_at, datetime) else created_at,
+                "createdBy": created_by,
+                "updatedAt": _ts_out(updated_at) if isinstance(updated_at, datetime) else updated_at,
+                "updatedBy": updated_by,
+                "lines": [line.to_dict() for line in self.lines]}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "InventoryCount":
+        return cls(count=data.get("count"), lines=[InventoryCountLine.from_dict(l) for l in data.get("lines") or []])
+
+    def __repr__(self) -> str:
+        return f"InventoryCount({self.count!r}, {len(self.lines)} lines)"
+
+
+class InventoryCountControl:
+    """
+    How a count compares with the movements (DEV-6129): the ``previous`` count, the net
+    quantity ``moved`` since it, so ``expected`` = previous + moved, then ``counted``, their
+    ``difference`` and whether it is ``verified`` (difference 0 after unit rounding).
+
+    A count with no count before it cannot be checked: it is the opening level, and
+    ``previous``, ``moved``, ``expected``, ``difference`` and ``verified`` are None.
+    """
+
+    def __init__(self, previous: InventoryStockCount = None, moved: float = None, expected: float = None,
+                 counted: float = None):
+        self.previous: Optional[InventoryStockCount] = previous
+        self.moved: Optional[float] = moved
+        self.expected: Optional[float] = expected
+        self.counted: Optional[float] = counted
+
+    @property
+    def difference(self) -> Optional[float]:
+        if self.expected is None or self.counted is None:
+            return None
+        return round_quantity(round_quantity(self.counted) - round_quantity(self.expected))
+
+    @property
+    def verified(self) -> Optional[bool]:
+        if self.expected is None or self.counted is None:
+            return None
+        return round_quantity(self.counted) == round_quantity(self.expected)
+
+    def to_dict(self) -> dict:
+        return {"previous": self.previous.to_dict() if self.previous is not None else None,
+                "moved": self.moved, "expected": self.expected, "counted": self.counted,
+                "difference": self.difference, "verified": self.verified}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "InventoryCountControl":
+        previous = data.get("previous")
+        return cls(previous=InventoryStockCount.from_dict(previous) if previous else None,
+                   moved=data.get("moved"), expected=data.get("expected"), counted=data.get("counted"))
+
+
+#: The two kinds of event a stock history holds.
+HISTORY_MOVEMENT = "movement"
+HISTORY_COUNT = "count"
+
+
+class InventoryHistoryEvent:
+    """
+    One event of a stock history, in time order (DEV-6129): a ``movement`` (signed
+    ``quantity``) or a ``count`` (counted ``quantity``, its ``count`` key, balance ``id``,
+    who recorded it and its ``control``). ``stock`` is the level right after it.
+    """
+
+    def __init__(self, timestamp=None, type: str = None, quantity: float = None, stock: float = None,
+                 count=None, balance_id=None, by: str = None, control: InventoryCountControl = None):
+        self.timestamp: Optional[datetime] = _ts_in(timestamp)
+        self.type: Optional[str] = type
+        self.quantity: Optional[float] = quantity
+        self.stock: Optional[float] = stock
+        self.count: Optional[str] = _uuid_str(count)
+        self.id: Optional[str] = _uuid_str(balance_id)
+        self.by: Optional[str] = by
+        self.control: Optional[InventoryCountControl] = control
+
+    def to_dict(self) -> dict:
+        obj = {"timestamp": _ts_out(self.timestamp) if isinstance(self.timestamp, datetime) else self.timestamp,
+               "type": self.type, "quantity": self.quantity, "stock": self.stock}
+        if self.type == HISTORY_COUNT:
+            obj.update({"count": self.count, "id": self.id, "by": self.by,
+                        "control": self.control.to_dict() if self.control is not None else None})
+        return obj
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "InventoryHistoryEvent":
+        control = data.get("control")
+        return cls(timestamp=data.get("timestamp"), type=data.get("type"), quantity=data.get("quantity"),
+                   stock=data.get("stock"), count=data.get("count"), balance_id=data.get("id"), by=data.get("by"),
+                   control=InventoryCountControl.from_dict(control) if control else None)
+
+
+class InventoryHistory:
+    """
+    How one product's stock moved on one storage datapoint over a period, and whether
+    each count matched (DEV-6129, ``POST /dsapi/planner/inventory/history``).
+
+    ``opening`` is the stock at ``start``, ``closing`` at ``end``; ``events`` are every
+    movement and count in between, oldest first, each with the stock after it. A count
+    carries its control against the count before it, even when that one is before
+    ``start``. A count with no count before it is the opening level and is not checked.
+    ``summary`` gives the ``counts``, how many could be ``checked``, how many of those are
+    ``verified``, and the ``unexplained`` quantity (the sum of their differences). Past the
+    event limit, ``truncated`` is true and only the latest events are kept; the summary
+    still covers the whole period.
+    """
+
+    def __init__(self, datapoint: str = None, product: str = None, start=None, end=None, unit=None,
+                 unit_symbol: str = None, opening: float = None, closing: float = None, events: list = None,
+                 truncated: bool = False):
+        self.datapoint: Optional[str] = datapoint
+        self.product: Optional[str] = product
+        self.start: Optional[datetime] = _ts_in(start)
+        self.end: Optional[datetime] = _ts_in(end)
+        self.unit: Optional[str] = _uuid_str(unit)
+        self.unit_symbol: Optional[str] = unit_symbol
+        self.opening: Optional[float] = opening
+        self.closing: Optional[float] = closing
+        self.events: list = list(events or [])
+        self.truncated: bool = truncated
+        self.counts: int = 0
+        self.checked: int = 0
+        self.verified: int = 0
+        self.unexplained: float = 0.0
+
+    def to_dict(self) -> dict:
+        def ts(value):
+            return _ts_out(value) if isinstance(value, datetime) else value
+        return {"datapoint": self.datapoint, "product": self.product, "unit": self.unit,
+                "unitSymbol": self.unit_symbol,
+                "opening": {"timestamp": ts(self.start), "quantity": self.opening},
+                "closing": {"timestamp": ts(self.end), "quantity": self.closing},
+                "events": [e.to_dict() for e in self.events],
+                "summary": {"counts": self.counts, "checked": self.checked, "verified": self.verified,
+                            "unexplained": self.unexplained},
+                "truncated": self.truncated}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "InventoryHistory":
+        opening, closing = data.get("opening") or {}, data.get("closing") or {}
+        summary = data.get("summary") or {}
+        obj = cls(datapoint=data.get("datapoint"), product=data.get("product"), start=opening.get("timestamp"),
+                  end=closing.get("timestamp"), unit=data.get("unit"), unit_symbol=data.get("unitSymbol"),
+                  opening=opening.get("quantity"), closing=closing.get("quantity"),
+                  events=[InventoryHistoryEvent.from_dict(e) for e in data.get("events") or []],
+                  truncated=bool(data.get("truncated")))
+        obj.counts = summary.get("counts", 0)
+        obj.checked = summary.get("checked", 0)
+        obj.verified = summary.get("verified", 0)
+        obj.unexplained = summary.get("unexplained", 0.0)
+        return obj
+
+    def __repr__(self) -> str:
+        return (f"InventoryHistory({self.datapoint!r}, {self.product!r}, {len(self.events)} events, "
+                f"{self.verified}/{self.checked} checked counts verified)")

wizata_dsapi-2.2.0.dev24/wizata_dsapi/version.py

@@ -0,0 +1 @@
+__version__ = "2.2.0.dev24"

{wizata_dsapi-2.2.0.dev22 → wizata_dsapi-2.2.0.dev24}/wizata_dsapi/wizata_dsapi_client.py

@@ -56,7 +56,7 @@ from .version import __version__
 import ast
 from .deployment import Deployment, DeploymentStatus
 from .product import ProductKind, Product, ProductComponent
-from .inventory import InventoryBalance, InventoryStorage, InventoryStock
+from .inventory import InventoryBalance, InventoryStorage, InventoryStock, InventoryCount, InventoryHistory
 from .connection import EdgeDeviceKey
 from .edge_config import EdgeConfig
 from .api_config import _registry
@@ -3001,6 +3001,73 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
         self._planner_request("DELETE", f"planner/inventory/balances/{self._balance_id(balance)}/",
                               expected=(204,))
 
+    @staticmethod
+    def _count_key(value) -> str:
+        key = value.count if isinstance(value, (InventoryCount, InventoryBalance)) else value
+        if not key:
+            raise ValueError("please provide a count key")
+        return urllib.parse.quote(str(key), safe="")
+
+    def get_inventory_count(self, count):
+        """
+        A count as one object (DEV-6128): its lines (balances) with their storage, unit, and
+        the level the movements predicted for each (``expected``, ``difference``,
+        ``verified``).
+
+        :param count: the count key, or an InventoryBalance / InventoryCount carrying it.
+        :return: InventoryCount, or None when no balance carries that key.
+        """
+        response = self._planner_request("GET", f"planner/inventory/counts/{self._count_key(count)}/",
+                                         expected=(200, 404))
+        return InventoryCount.from_dict(response.json()) if response.status_code == 200 else None
+
+    def set_inventory_count(self, count, balances: list, timestamp=None) -> InventoryCount:
+        """
+        Replace a count, all or none: afterwards it holds exactly ``balances``.
+
+        A balance with an ``id`` changes that line (quantity, time; never its datapoint or
+        product). One without takes the count's line of the same datapoint and product, or
+        joins the count. A line left out is deleted. ``timestamp`` (datetime or ISO 8601) is
+        the time of every balance that has none. 409 when another count holds one of those
+        products at that time.
+
+        :param count: the count key, or an InventoryCount.
+        :param balances: InventoryBalance list (or dicts).
+        :return: the count afterwards, as :meth:`get_inventory_count` returns it.
+        """
+        body = {"balances": [b.to_dict() if isinstance(b, InventoryBalance) else b for b in balances]}
+        if timestamp is not None:
+            body["timestamp"] = timestamp.isoformat() if isinstance(timestamp, datetime.datetime) else timestamp
+        response = self._planner_request("PUT", f"planner/inventory/counts/{self._count_key(count)}/", body=body)
+        return InventoryCount.from_dict(response.json())
+
+    def delete_inventory_count(self, count):
+        """
+        Delete every balance of a count.
+
+        :param count: the count key, or an InventoryCount / InventoryBalance carrying it.
+        """
+        self._planner_request("DELETE", f"planner/inventory/counts/{self._count_key(count)}/", expected=(204,))
+
+    def get_inventory_history(self, datapoint: str, product: str, start=None, end=None) -> InventoryHistory:
+        """
+        How one product's stock moved on one storage datapoint (DEV-6129): every movement and
+        count in time order with the stock after each, and each count compared with the count
+        before it plus the movements since (``control``: expected, counted, difference,
+        verified). Default period: the last 7 days.
+
+        :param datapoint: hardware id of the storage's inventoryMovement datapoint.
+        :param product: product key.
+        :param start: datetime, ISO 8601, epoch ms or a relative ``now-7d``.
+        :param end: same; default now.
+        """
+        body = {"datapoint": datapoint, "product": product}
+        for name, value in (("start", start), ("end", end)):
+            if value is not None:
+                body[name] = value.isoformat() if isinstance(value, datetime.datetime) else value
+        response = self._planner_request("POST", "planner/inventory/history", body=body)
+        return InventoryHistory.from_dict(response.json())
+
     # ------------------------------------------------------------ edge (DEV-6013/6014)
 
     @staticmethod

{wizata_dsapi-2.2.0.dev22 → wizata_dsapi-2.2.0.dev24}/wizata_dsapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wizata_dsapi
-Version: 2.2.0.dev22
+Version: 2.2.0.dev24
 Summary: Wizata Data Science Toolkit
 Author: Wizata S.A.
 Author-email: info@wizata.com

wizata_dsapi-2.2.0.dev22/wizata_dsapi/version.py

@@ -1 +0,0 @@
-__version__ = "2.2.0.dev22"