wizata-dsapi 2.2.0.dev2__tar.gz → 2.2.0.dev5__tar.gz

{wizata_dsapi-2.2.0.dev2 → wizata_dsapi-2.2.0.dev5}/PKG-INFO

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

{wizata_dsapi-2.2.0.dev2 → wizata_dsapi-2.2.0.dev5}/wizata_dsapi/__init__.py

@@ -65,6 +65,7 @@ from .connection import Connection, ConnectionMapping, ConnectionDirection, Tran
     EdgeDeviceKey, EdgeDeviceKeyStatus
 from .connection_types import ConnectionType, CONNECTION_TYPES, TRANSFORM_SCHEMAS, get_connection_type, \
     list_connection_types
+from .product import ProductKind, Product, ProductComponent, BUILTIN_PRODUCT_KINDS, is_valid_product_key
 from .dashboard import Dashboard, DashboardType
 from .mobile_asset import MobileAssetTile, MobileAssetTileType, MobileAssetConfig
 from .graylog_log import GraylogLog

wizata_dsapi-2.2.0.dev5/wizata_dsapi/product.py

@@ -0,0 +1,210 @@
+"""
+Production Planner product definitions (DEV-6070, epic DEV-6044).
+
+ProductKind — what role a product plays: raw material, container, finished product,
+  or a kind the customer adds. The three built-in kinds (``BUILTIN_PRODUCT_KINDS``)
+  are seeded on every tenant and cannot be deleted.
+
+Product — something the plant consumes or makes, identified by a Wizata key
+  (e.g. ``can_33_coke``). ``category`` is a backend category id (Volume, Count, ...):
+  it says how a quantity of that product is expressed.
+
+ProductComponent — one line of a product's bill of materials: ``product`` is made of
+  ``quantity`` ``unit`` of ``composed_of``. The unit is a backend unit id and must
+  belong to the category of ``composed_of`` (33 ml of coke, 1 pcs of can).
+  ``unit_symbol`` is filled on read only.
+
+All of it is served under ``/dsapi/planner`` and gated by the Production Planner
+add-on license (DEV-6069).
+"""
+
+import re
+from datetime import datetime, timezone
+from typing import Optional
+
+#: key -> (name, description). Seeded by alembic 0019; editable, never deletable.
+BUILTIN_PRODUCT_KINDS = {
+    "raw": ("Raw Material",
+            "A material bought or produced upstream and consumed to make other "
+            "products (e.g. syrup, water, aluminium)."),
+    "container": ("Containers",
+                  "Packaging that holds or carries a product (e.g. can, bottle, box, pallet)."),
+    "finished": ("Finished Product",
+                 "A product ready to ship or sell, made from raw materials and containers."),
+}
+
+#: A Wizata key: starts with a letter or digit, then letters, digits, ``_ - .``.
+PRODUCT_KEY_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-.]{0,63}$")
+
+
+def is_valid_product_key(key) -> bool:
+    return isinstance(key, str) and PRODUCT_KEY_PATTERN.match(key) is not None
+
+
+def _ts_out(value):
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.isoformat()
+
+
+def _ts_in(value):
+    if value is None or isinstance(value, datetime):
+        return value
+    return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+
+
+def _uuid_str(value):
+    """Backend ids travel as strings, lower-cased so equal ids compare equal."""
+    if value is None or value == "":
+        return None
+    return str(value).lower()
+
+
+class ProductKind:
+    """ProductKind entity stored in PostgreSQL ``"ProductKind"``. PK ``key``."""
+
+    @classmethod
+    def route(cls):
+        return "planner/productkinds"
+
+    def __init__(self, key: str = None, name: str = None, description: str = None):
+        self.key: Optional[str] = key
+        self.name: Optional[str] = name
+        self.description: Optional[str] = description
+        self.created_at: Optional[datetime] = None
+        self.updated_at: Optional[datetime] = None
+
+    @property
+    def builtin(self) -> bool:
+        return self.key in BUILTIN_PRODUCT_KINDS
+
+    def to_dict(self) -> dict:
+        obj = {}
+        if self.key is not None:
+            obj["key"] = self.key
+        if self.name is not None:
+            obj["name"] = self.name
+        if self.description is not None:
+            obj["description"] = self.description
+        obj["builtin"] = self.builtin
+        if self.created_at is not None:
+            obj["createdAt"] = _ts_out(self.created_at)
+        if self.updated_at is not None:
+            obj["updatedAt"] = _ts_out(self.updated_at)
+        return obj
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ProductKind":
+        obj = cls()
+        obj.key = data.get("key")
+        obj.name = data.get("name")
+        obj.description = data.get("description")
+        obj.created_at = _ts_in(data.get("createdAt") or data.get("created_at"))
+        obj.updated_at = _ts_in(data.get("updatedAt") or data.get("updated_at"))
+        return obj
+
+    def api_id(self) -> str:
+        return self.key
+
+    def __repr__(self) -> str:
+        return f"ProductKind(key={self.key!r}, name={self.name!r})"
+
+
+class Product:
+    """Product entity stored in PostgreSQL ``"Product"``. PK ``key``."""
+
+    @classmethod
+    def route(cls):
+        return "planner/products"
+
+    def __init__(self, key: str = None, name: str = None, category=None,
+                 kind: str = None, description: str = None):
+        self.key: Optional[str] = key
+        self.name: Optional[str] = name
+        self.category: Optional[str] = _uuid_str(category)
+        self.kind: Optional[str] = kind
+        self.description: Optional[str] = description
+        self.created_at: Optional[datetime] = None
+        self.updated_at: Optional[datetime] = None
+
+    def to_dict(self) -> dict:
+        obj = {}
+        if self.key is not None:
+            obj["key"] = self.key
+        if self.name is not None:
+            obj["name"] = self.name
+        if self.category is not None:
+            obj["category"] = self.category
+        if self.kind is not None:
+            obj["kind"] = self.kind
+        if self.description is not None:
+            obj["description"] = self.description
+        if self.created_at is not None:
+            obj["createdAt"] = _ts_out(self.created_at)
+        if self.updated_at is not None:
+            obj["updatedAt"] = _ts_out(self.updated_at)
+        return obj
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Product":
+        obj = cls()
+        obj.key = data.get("key")
+        obj.name = data.get("name")
+        obj.category = _uuid_str(data.get("category"))
+        obj.kind = data.get("kind")
+        obj.description = data.get("description")
+        obj.created_at = _ts_in(data.get("createdAt") or data.get("created_at"))
+        obj.updated_at = _ts_in(data.get("updatedAt") or data.get("updated_at"))
+        return obj
+
+    def api_id(self) -> str:
+        return self.key
+
+    def __repr__(self) -> str:
+        return f"Product(key={self.key!r}, kind={self.kind!r}, category={self.category!r})"
+
+
+class ProductComponent:
+    """
+    One bill-of-materials line, stored in PostgreSQL ``"ProductComponent"``.
+    PK (``product``, ``composed_of``).
+    """
+
+    def __init__(self, product: str = None, composed_of: str = None,
+                 quantity: float = None, unit=None):
+        self.product: Optional[str] = product
+        self.composed_of: Optional[str] = composed_of
+        self.quantity: Optional[float] = quantity
+        self.unit: Optional[str] = _uuid_str(unit)
+        #: read-only, filled from the backend unit on read
+        self.unit_symbol: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        obj = {}
+        if self.product is not None:
+            obj["product"] = self.product
+        if self.composed_of is not None:
+            obj["composedOf"] = self.composed_of
+        if self.quantity is not None:
+            obj["quantity"] = self.quantity
+        if self.unit is not None:
+            obj["unit"] = self.unit
+        if self.unit_symbol is not None:
+            obj["unitSymbol"] = self.unit_symbol
+        return obj
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ProductComponent":
+        obj = cls()
+        obj.product = data.get("product")
+        obj.composed_of = data.get("composedOf") or data.get("composed_of")
+        obj.quantity = data.get("quantity")
+        obj.unit = _uuid_str(data.get("unit"))
+        obj.unit_symbol = data.get("unitSymbol") or data.get("unit_symbol")
+        return obj
+
+    def __repr__(self) -> str:
+        return (f"ProductComponent({self.product!r} <- {self.quantity!r} {self.unit_symbol or self.unit!r} "
+                f"of {self.composed_of!r})")

{wizata_dsapi-2.2.0.dev2 → wizata_dsapi-2.2.0.dev5}/wizata_dsapi/request.py

@@ -644,6 +644,17 @@ class Request(ApiDto):
 
         return query
 
+    @staticmethod
+    def _object(value, section: str) -> dict:
+        """
+        A section of the body that must be a JSON object. Anything else is the caller's
+        mistake, refused as a ValueError naming it (the DS API answers 400) - it used to
+        reach ``.keys()`` and fail as an AttributeError, answered 500.
+        """
+        if not isinstance(value, dict):
+            raise ValueError(f"'{section}' must be an object, got {type(value).__name__}: {value!r}"[:300])
+        return value
+
     def from_json(self, json_data):
         if "id" in json_data.keys():
             self.request_id = uuid.UUID(json_data["id"])
@@ -654,6 +665,7 @@ class Request(ApiDto):
         datapoints = []
         if "equipments_list" in json_data.keys():
             for equipment in json_data["equipments_list"]:
+                self._object(equipment, "equipments_list")
                 if "datapoints" not in equipment.keys():
                     raise KeyError("no 'datapoints' have been provided for equipment with id '" +
                                    str(equipment["id"]) + "'")
@@ -674,6 +686,7 @@ class Request(ApiDto):
             self._datapoints = []
 
         if "timeframe" in json_data.keys():
+            self._object(json_data["timeframe"], "timeframe")
             if "start" not in json_data["timeframe"].keys():
                 raise KeyError("No 'start time' have been selected, please set it up and re-try.")
 
@@ -695,6 +708,7 @@ class Request(ApiDto):
 
         if "aggregations" not in json_data.keys():
             raise KeyError("No 'aggregations' have been selected, please set it up and re-try.")
+        self._object(json_data["aggregations"], "aggregations")
 
         if "agg_method" not in json_data["aggregations"].keys():
             self.aggregation = None
@@ -751,7 +765,7 @@ class Request(ApiDto):
             self.null = json_data["null"]
 
         if "target_feat" in json_data.keys():
-            self.target_feat = json_data["target_feat"]
+            self.target_feat = self._object(json_data["target_feat"], "target_feat")
             if "sensor" not in self.target_feat.keys():
                 raise KeyError("No 'sensor' have been declared inside the target feature, this is a technical error.")
             if "operator" not in self.target_feat.keys():

wizata_dsapi-2.2.0.dev5/wizata_dsapi/version.py

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

{wizata_dsapi-2.2.0.dev2 → wizata_dsapi-2.2.0.dev5}/wizata_dsapi/wizata_dsapi_client.py

@@ -54,6 +54,7 @@ from .mobile_asset import MobileAssetTile, MobileAssetConfig
 from .version import __version__
 import ast
 from .deployment import Deployment, DeploymentStatus
+from .product import ProductKind, Product, ProductComponent
 from .api_config import _registry
 
 from .streamlit_utils import get_streamlit_token, get_streamlit_domain
@@ -2731,6 +2732,142 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
             raise self.__raise_error(response)
 
 
+    # ------------------------------------------------------------------
+    # Production Planner - product definitions (DEV-6070)
+    #
+    # Everything below answers 403 PLANNER_LICENSE_DISABLED while the
+    # Production Planner add-on is not active on the environment (DEV-6069).
+    # ------------------------------------------------------------------
+
+    def _planner_request(self, method: str, route: str, body=None, params: dict = None,
+                         expected=(200,)):
+        response = requests.request(
+            method,
+            self.__url() + route,
+            headers=self.__header(),
+            data=json.dumps(body) if body is not None else None,
+            params=params,
+        )
+        if response.status_code not in expected:
+            raise self.__raise_error(response)
+        return response
+
+    @staticmethod
+    def _planner_key(value) -> str:
+        key = value.key if hasattr(value, "key") else value
+        if not key:
+            raise ValueError("please provide a key")
+        return urllib.parse.quote(str(key), safe="")
+
+    def search_product_kinds(self, search_query=None) -> PagedQueryResult:
+        """
+        The only way to list product kinds: the built-in raw / container / finished and
+        the tenant's own.
+
+        :param search_query: SearchQuery or dict; filters on ``name``, ``_search`` over
+            key and name.
+        :return: PagedQueryResult with ProductKind results.
+        """
+        if search_query is None:
+            search_query = SearchQuery()
+        elif isinstance(search_query, dict):
+            search_query = SearchQuery.from_dict(search_query)
+        response = self._planner_request("POST", "planner/productkinds/search",
+                                         body=search_query.to_dict())
+        return PagedQueryResult.from_dict(response.json(), dto_class=ProductKind)
+
+    def get_product_kind(self, key: str):
+        """
+        :param key: product kind key (e.g. ``raw``).
+        :return: ProductKind, or None when it does not exist.
+        """
+        response = self._planner_request("GET", f"planner/productkinds/{self._planner_key(key)}/",
+                                         expected=(200, 404))
+        return ProductKind.from_dict(response.json()) if response.status_code == 200 else None
+
+    def create_product_kind(self, kind: ProductKind) -> ProductKind:
+        response = self._planner_request("POST", "planner/productkinds/", body=kind.to_dict(),
+                                         expected=(201,))
+        return ProductKind.from_dict(response.json())
+
+    def update_product_kind(self, kind: ProductKind) -> ProductKind:
+        response = self._planner_request("PUT", f"planner/productkinds/{self._planner_key(kind)}/",
+                                         body=kind.to_dict())
+        return ProductKind.from_dict(response.json())
+
+    def delete_product_kind(self, kind):
+        """
+        :param kind: ProductKind or its key. A built-in kind, or a kind still used by a
+            product, is refused (409).
+        """
+        self._planner_request("DELETE", f"planner/productkinds/{self._planner_key(kind)}/",
+                              expected=(204,))
+
+    def search_products(self, search_query=None) -> PagedQueryResult:
+        """
+        The only way to list products.
+
+        :param search_query: SearchQuery or dict; filters on ``kind``, ``category``
+            (backend category id), ``name``, and ``_search`` over key and name.
+        :return: PagedQueryResult with Product results.
+        """
+        if search_query is None:
+            search_query = SearchQuery()
+        elif isinstance(search_query, dict):
+            search_query = SearchQuery.from_dict(search_query)
+        response = self._planner_request("POST", "planner/products/search",
+                                         body=search_query.to_dict())
+        return PagedQueryResult.from_dict(response.json(), dto_class=Product)
+
+    def get_product(self, key: str):
+        """
+        :return: Product, or None when it does not exist.
+        """
+        response = self._planner_request("GET", f"planner/products/{self._planner_key(key)}/",
+                                         expected=(200, 404))
+        return Product.from_dict(response.json()) if response.status_code == 200 else None
+
+    def create_product(self, product: Product) -> Product:
+        response = self._planner_request("POST", "planner/products/", body=product.to_dict(),
+                                         expected=(201,))
+        return Product.from_dict(response.json())
+
+    def update_product(self, product: Product) -> Product:
+        response = self._planner_request("PUT", f"planner/products/{self._planner_key(product)}/",
+                                         body=product.to_dict())
+        return Product.from_dict(response.json())
+
+    def delete_product(self, product):
+        """
+        :param product: Product or its key. Refused (409) while another product is made
+            of it; its own bill of materials is deleted with it.
+        """
+        self._planner_request("DELETE", f"planner/products/{self._planner_key(product)}/",
+                              expected=(204,))
+
+    def get_product_components(self, product) -> list:
+        """
+        :param product: Product or its key.
+        :return: its bill of materials, a list of ProductComponent with unit_symbol set.
+        """
+        response = self._planner_request(
+            "GET", f"planner/products/{self._planner_key(product)}/components/")
+        return [ProductComponent.from_dict(c) for c in response.json()]
+
+    def set_product_components(self, product, components: list) -> list:
+        """
+        Replace a product's bill of materials (an empty list clears it).
+
+        :param product: Product or its key.
+        :param components: list of ProductComponent (``product`` may be left unset).
+        :return: the stored components, unit_symbol set.
+        """
+        body = [c.to_dict() if isinstance(c, ProductComponent) else c for c in components]
+        response = self._planner_request(
+            "PUT", f"planner/products/{self._planner_key(product)}/components/", body=body)
+        return [ProductComponent.from_dict(c) for c in response.json()]
+
+
 def api() -> WizataDSAPIClient:
     """
     Create a WizataDSAPIClient from environment variables.

{wizata_dsapi-2.2.0.dev2 → wizata_dsapi-2.2.0.dev5}/wizata_dsapi.egg-info/PKG-INFO

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

{wizata_dsapi-2.2.0.dev2 → wizata_dsapi-2.2.0.dev5}/wizata_dsapi.egg-info/SOURCES.txt

@@ -36,6 +36,7 @@ wizata_dsapi/paged_query_result.py
 wizata_dsapi/pipeline.py
 wizata_dsapi/pipeline_image.py
 wizata_dsapi/plot.py
+wizata_dsapi/product.py
 wizata_dsapi/request.py
 wizata_dsapi/script.py
 wizata_dsapi/search.py

wizata_dsapi-2.2.0.dev2/wizata_dsapi/version.py

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