wizata-dsapi 2.1.0.dev18__tar.gz → 2.1.0.dev20__tar.gz

{wizata_dsapi-2.1.0.dev18 → wizata_dsapi-2.1.0.dev20}/PKG-INFO

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

{wizata_dsapi-2.1.0.dev18 → wizata_dsapi-2.1.0.dev20}/wizata_dsapi/api_config.py

@@ -17,10 +17,33 @@ from .trigger import Trigger
 from .twin import Twin, TwinType
 from .pipeline import Pipeline
 from .pipeline_image import PipelineImage
+from .deployment import Deployment
 from .insight import Insight
 from .edge_device import EdgeDevice
 
 
+# Entities withdrawn from the client, and what to say instead.
+#
+# Removing one from `_registry` alone would fail with "Api entity triggers is not
+# supported", which reads as a bug in the client. These messages name the
+# replacement, so the first person to hit it can act instead of filing.
+#
+# The DTO itself is NOT removed — `wizata_dsapi.Trigger` is still imported and used
+# by the platform internally (the 12.1 adopt-triggers migration reads them through
+# `ApiDataManager.backend_api`, which never consults this registry). What goes is
+# the ability to schedule through the public client.
+_retired = {
+    "triggers": (
+        Trigger,
+        "triggers are no longer managed through this client (12.1). A schedule now "
+        "belongs to a Deployment, which owns its trigger and knows how to pause, "
+        "resume and remove it: use api.deploy(...) and the deployment methods. "
+        "Deleting a trigger on its own would leave a Deployment record claiming a "
+        "schedule that no longer exists, and nothing would find it again."
+    ),
+}
+
+
 # init APIs supported operations
 _registry = {
     "business_labels":
@@ -41,6 +64,17 @@ _registry = {
             "cloud_dsapi": ['lists', 'get_by_id', 'get_by_key', 'create', 'update', 'delete', 'search'],
             "cloud_context": ['get_by_id', 'get_by_key', 'create', 'update', 'delete', 'search']
         },
+    "deployments":
+        {
+            "class": Deployment,
+            # No 'create': a deployment is not posted into existence, it is the
+            # RESULT of deploying a pipeline — see WizataDSAPIClient.deploy, which
+            # runs merge, release, image and trigger as one call and returns the
+            # record to poll. Offering create here would invite a half-built record
+            # with no schedule behind it.
+            "cloud_dsapi": ['lists', 'get_by_id', 'update', 'delete', 'search'],
+            "cloud_context": []
+        },
     "datastores":
         {
             "class": DataStore,
@@ -137,12 +171,6 @@ _registry = {
             "cloud_dsapi": ['lists', 'get_by_id', 'create', 'update', 'delete'],
             "cloud_context": []
         },
-    "triggers":
-        {
-            "class": Trigger,
-            "cloud_dsapi": ['lists', 'get_by_id', 'create', 'update', 'delete'],
-            "cloud_context": ['get_by_id']
-        },
     "twins":
         {
             "class": Twin,

{wizata_dsapi-2.1.0.dev18 → wizata_dsapi-2.1.0.dev20}/wizata_dsapi/api_interface.py

@@ -134,14 +134,31 @@ class ApiInterface:
             if entity in self._dto_registry.keys():
                 self._verify_operation(entity, operation)
                 return self._dto_registry[entity]["class"]
-            else:
-                raise TypeError(f"Api entity {entity} is not supported.")
+            self._refuse(entity)
         else:
             for entity_name in self._dto_registry:
                 if self._dto_registry[entity_name]["class"] == entity:
                     self._verify_operation(entity_name, operation)
                     return entity
-            raise TypeError(f"Api entity {entity} is not supported.")
+            self._refuse(entity)
+
+    @staticmethod
+    def _refuse(entity):
+        """
+        Raise for an entity this client does not serve, saying WHY when it is one
+        that was withdrawn rather than one that never existed.
+
+        "Api entity triggers is not supported" reads as a bug in the client, and the
+        person reading it has no way to know a schedule is now a Deployment. Both
+        the plural name and the DTO class are matched, since callers reach the
+        registry through either.
+        """
+        from .api_config import _retired
+
+        for name, (dto, message) in _retired.items():
+            if entity == name or entity is dto:
+                raise TypeError(f"Api entity {name} is no longer supported: {message}")
+        raise TypeError(f"Api entity {entity} is not supported.")
 
     def _verify_operation(self,
                           entity,

{wizata_dsapi-2.1.0.dev18 → wizata_dsapi-2.1.0.dev20}/wizata_dsapi/deployment.py

@@ -210,6 +210,12 @@ class Deployment(ApiDto):
         if "updatedDate" in obj.keys() and obj["updatedDate"] is not None:
             self.updatedDate = obj["updatedDate"]
 
+    def to_dict(self) -> dict:
+        """Serialize the Deployment. Alias of :meth:`to_json`, which is the
+        canonical implementation here — the DTO convention accepts either
+        spelling, and the client calls ``to_dict``."""
+        return self.to_json()
+
     def to_json(self, target: str = None):
         obj = {
             "id": str(self.deployment_id),

wizata_dsapi-2.1.0.dev20/wizata_dsapi/version.py

@@ -0,0 +1 @@
+__version__ = "2.1.0.dev20"

{wizata_dsapi-2.1.0.dev18 → wizata_dsapi-2.1.0.dev20}/wizata_dsapi/wizata_dsapi_client.py

@@ -53,6 +53,7 @@ from .api_interface import ApiInterface
 from .mobile_asset import MobileAssetTile, MobileAssetConfig
 from .version import __version__
 import ast
+from .deployment import Deployment, DeploymentStatus
 from .api_config import _registry
 
 from .streamlit_utils import get_streamlit_token, get_streamlit_domain
@@ -713,39 +714,28 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
         else:
             return self.create(obj)
 
-    def query(self,
-              datapoints: list = None,
-              start: datetime = None,
-              end: datetime = None,
-              interval: int = None,
-              agg_method: str = "mean",
-              template: str = None,
-              twin: str = None,
-              null: str = None,
-              filters: dict = None,
-              options: dict = None,
-              group = None,
-              field=None,
-              bucket: str = None,
-              tags: dict = None,
-              scopes: list = None) -> pandas.DataFrame:
-        """
-        Query a dataframe from API.
-        :param agg_method:
-        :param datapoints: list of datapoints to fetch.
-        :param start: start datetime of range to fetch
-        :param end: end datetime of range to fetch
-        :param interval: interval in milliseconds.
-        :param template: template to fetch.
-        :param twin: hardware ID of twin to fetch based on template.
-        :param null: By default at 'drop' and dropping NaN values. If not intended behavior please set it to 'ignore' or 'all'.
-        :param group: can be use to set group system and event retrieving instructions (dict or list[dict]).
-        :param filters: dict of filters.
-        :param options: dict of options.
-        :param field: by default 'value' if none, accept str or list (e.g. value, reliability, eventId, ...)
-        :param bucket: specify on which bucket the query applies.
-        :param scopes: list of scope filters for SCOPED datapoints (e.g. ["normal", {"vibration": {"gte": 0.6}}]).
-        :return: dataframe
+    def _build_request(self,
+                       datapoints: list = None,
+                       start: datetime = None,
+                       end: datetime = None,
+                       interval: int = None,
+                       agg_method: str = "mean",
+                       template: str = None,
+                       twin: str = None,
+                       null: str = None,
+                       filters: dict = None,
+                       options: dict = None,
+                       group=None,
+                       field=None,
+                       bucket: str = None,
+                       tags: dict = None,
+                       scopes: list = None) -> Request:
+        """
+        Build the Request behind a time-series query.
+
+        Shared by :meth:`query` and :meth:`query_json` so the two cannot disagree
+        about what an argument means. They differ only in what they ask the server
+        to send back — a DataFrame or described JSON — never in what they ask for.
         """
         request = Request()
 
@@ -796,7 +786,47 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
         if bucket is not None:
             request.bucket = bucket
 
-        return self._query(request=request)
+        return request
+
+    def query(self,
+              datapoints: list = None,
+              start: datetime = None,
+              end: datetime = None,
+              interval: int = None,
+              agg_method: str = "mean",
+              template: str = None,
+              twin: str = None,
+              null: str = None,
+              filters: dict = None,
+              options: dict = None,
+              group = None,
+              field=None,
+              bucket: str = None,
+              tags: dict = None,
+              scopes: list = None) -> pandas.DataFrame:
+        """
+        Query a dataframe from API.
+        :param agg_method:
+        :param datapoints: list of datapoints to fetch.
+        :param start: start datetime of range to fetch
+        :param end: end datetime of range to fetch
+        :param interval: interval in milliseconds.
+        :param template: template to fetch.
+        :param twin: hardware ID of twin to fetch based on template.
+        :param null: By default at 'drop' and dropping NaN values. If not intended behavior please set it to 'ignore' or 'all'.
+        :param group: can be use to set group system and event retrieving instructions (dict or list[dict]).
+        :param filters: dict of filters.
+        :param options: dict of options.
+        :param field: by default 'value' if none, accept str or list (e.g. value, reliability, eventId, ...)
+        :param bucket: specify on which bucket the query applies.
+        :param scopes: list of scope filters for SCOPED datapoints (e.g. ["normal", {"vibration": {"gte": 0.6}}]).
+        :return: dataframe
+        """
+        return self._query(request=self._build_request(
+            datapoints=datapoints, start=start, end=end, interval=interval,
+            agg_method=agg_method, template=template, twin=twin, null=null,
+            filters=filters, options=options, group=group, field=field,
+            bucket=bucket, tags=tags, scopes=scopes))
 
     def batch_query(self,
                     step: timedelta,
@@ -1179,6 +1209,38 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
             raise ValueError("a pipeline key, UUID or Pipeline is required")
         return urllib.parse.quote(str(reference), safe="")
 
+    def _pipeline_uuid(self, pipeline) -> str:
+        """
+        Path segment for a route that addresses a pipeline by UUID only.
+
+        Distinct from :meth:`_pipeline_ref`, and the difference is not cosmetic: the
+        live-plot route resolves a key OR a UUID (DEV-6027), while the branch, deploy
+        and preview routes parse the segment with ``uuid.UUID(id)`` and answer
+        ``400 badly formed hexadecimal UUID string`` for a key.
+
+        Callers hold keys — that is what a pipeline is called everywhere a person
+        reads one — so the key is resolved here rather than refused.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :return: the pipeline's UUID as a path segment.
+        """
+        if isinstance(pipeline, Pipeline):
+            if pipeline.pipeline_id is not None:
+                return str(pipeline.pipeline_id)
+            pipeline = pipeline.key
+        if pipeline is None:
+            raise ValueError("a pipeline key, UUID or Pipeline is required")
+        if isinstance(pipeline, uuid.UUID):
+            return str(pipeline)
+        try:
+            return str(uuid.UUID(str(pipeline)))
+        except (ValueError, AttributeError, TypeError):
+            pass
+        resolved = self.get(pipeline_key=str(pipeline))
+        if resolved is None or resolved.pipeline_id is None:
+            raise ValueError(f"pipeline {pipeline!r} could not be resolved to an id")
+        return str(resolved.pipeline_id)
+
     def deployed_plots(self, pipeline, twin: str = None) -> list:
         """
         list a deployed pipeline's LIVE plots - what its deployments are currently
@@ -2013,6 +2075,294 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
         )
         return response.text
 
+    def query_json(self, include_format: bool = True, **kwargs) -> dict:
+        """
+        query time-series as JSON, described.
+
+        Takes the same arguments as :meth:`query`. Where ``query`` hands back a
+        DataFrame, this returns the rows as JSON — and by default wraps them in a
+        description of their own shape, so a caller that is not pandas can render
+        them without guessing:
+
+            {"columns": [...], "pivot": ..., "data": [...]}
+
+        That is what the front-end's query form is built on: an aggregated query
+        comes back pivoted with one column per datapoint, a raw one comes back long
+        with a 'value' column, and only the envelope says which you got (DEV-6031).
+
+        A separate method rather than a flag on :meth:`query`, deliberately — a
+        parameter that changes the return type between a DataFrame and a dict makes
+        every caller branch on what it asked for.
+
+        :param include_format: False to get the bare rows without the envelope.
+        :return: dict with columns/pivot/data, or the rows alone when
+            ``include_format`` is False.
+        """
+        request = self._build_request(**kwargs)
+        response = self._process_request(
+            method="POST",
+            route="data/",
+            params={"include-format": "true" if include_format else "false"},
+            data=json.dumps(request.to_json(), cls=DSAPIEncoder)
+        )
+        return response.json()
+
+    # ------------------------------------------------------------------ git branches
+
+    def branches(self, pipeline) -> dict:
+        """
+        list the branches relevant to a pipeline.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :return: dict with 'default', 'feature' and 'release' - feature branches are
+            this pipeline's drafts, release branches are the frozen refs deployments
+            run from.
+        """
+        response = self._process_request(
+            method="GET",
+            route=f"{Pipeline.route()}/{self._pipeline_uuid(pipeline)}/branches/"
+        )
+        return response.json()
+
+    def create_branch(self, pipeline, name: str = None, source: str = None) -> Pipeline:
+        """
+        create a branch for a pipeline and return the pipeline as it stands on it.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :param name: branch name. Leave None for a draft, which is named for you.
+            A release is named ``release/<name>``.
+        :param source: ref to branch from; the default branch when None.
+        :return: the Pipeline read at the new branch, with 'branch' set.
+        """
+        payload = {}
+        if name is not None:
+            payload["name"] = name
+        if source is not None:
+            payload["source"] = source
+        response = self._process_request(
+            method="POST",
+            route=f"{Pipeline.route()}/{self._pipeline_uuid(pipeline)}/branches/",
+            data=json.dumps(payload)
+        )
+        return Pipeline.from_dict(response.json())
+
+    def delete_branch(self, pipeline, branch: str) -> None:
+        """
+        discard a branch.
+
+        A draft goes on demand. A release is refused with 409 while a deployment or a
+        trigger still runs from it - pause or redeploy those first, rather than
+        leaving a schedule pointing at a ref that no longer exists.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :param branch: branch ref.
+        """
+        self._process_request(
+            method="DELETE",
+            route=f"{Pipeline.route()}/{self._pipeline_uuid(pipeline)}/branches/{branch}/"
+        )
+
+    def merge_branch(self, pipeline, branch: str) -> dict:
+        """
+        merge a draft into the default branch and delete it.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :param branch: the feature branch to publish.
+        :return: dict with 'merged_sha', 'deleted_branch' and 'files_changed'.
+        """
+        response = self._process_request(
+            method="POST",
+            route=f"{Pipeline.route()}/{self._pipeline_uuid(pipeline)}/branches/{branch}/merge"
+        )
+        return response.json()
+
+    def get_pipeline_at(self, pipeline, branch: str) -> Pipeline:
+        """
+        read a pipeline as it stands on a branch, rather than on the default one.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :param branch: branch ref.
+        :return: Pipeline.
+        """
+        response = self._process_request(
+            method="GET",
+            route=f"{Pipeline.route()}/{self._pipeline_uuid(pipeline)}/branches/{branch}/"
+        )
+        return Pipeline.from_dict(response.json())
+
+    def get_script_at(self, name: str, branch: str) -> Script:
+        """
+        read a RAW script's source as it stands on a branch.
+
+        A branch run executes the branch's script, so this is what actually runs
+        there - the default-branch copy may differ.
+
+        :param name: script name.
+        :param branch: branch ref.
+        :return: Script.
+        """
+        response = self._process_request(
+            method="GET",
+            route=f"{Script.route()}/{name}/branches/{branch}/"
+        )
+        return Script.from_dict(response.json())
+
+    def save_script_at(self, script: Script, branch: str) -> None:
+        """
+        save a RAW script on a branch, leaving the default branch untouched until the
+        branch is merged.
+
+        :param script: Script with its source set.
+        :param branch: branch ref.
+        """
+        self._process_request(
+            method="PUT",
+            route=f"{Script.route()}/{script.name}/branches/{branch}/",
+            files={"payload": (None, json.dumps(script.to_dict(), cls=DSAPIEncoder))}
+        )
+
+    # ------------------------------------------------------------------ deployments
+
+    def deploy(self,
+               pipeline,
+               twins: list = None,
+               interval: int = None,
+               delay: int = None,
+               packaging: str = None,
+               source: str = None,
+               properties: dict = None,
+               plot: bool = None,
+               train: bool = None,
+               write: bool = None) -> Deployment:
+        """
+        deploy a pipeline: merge the draft, cut the release, build the image and create
+        the schedule - the whole sequence, as one call.
+
+        Returns immediately with a Deployment to poll; an image build outlasts the
+        gateway timeout, so the record carries the progress instead of the request.
+        Poll it with :meth:`get` on the returned id, or :meth:`await_deployment`.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :param twins: hardware ids or twin UUIDs this schedule covers - both forms are
+            accepted - or ``{twin, target, deviceId}`` entries where target is "cloud"
+            (default) or "edge".
+        :param interval: milliseconds between runs.
+        :param delay: milliseconds to wait after each interval boundary.
+        :param packaging: "image" (default) or "release".
+        :param source: branch or ref to deploy from.
+        :param properties: pipeline properties for every run.
+        :param plot: produce plots on each run. Refused on edge.
+        :param train: train models on each run. Refused on edge, and on an
+            image-packaged deployment - the model would be trained and silently
+            discarded, because the image's frozen model is what predict uses.
+        :param write: write results back. Defaults on.
+        :return: Deployment to poll.
+        """
+        payload = {}
+        if twins is not None:
+            payload["twins"] = twins
+        for name, value in (("interval", interval), ("delay", delay),
+                            ("packaging", packaging), ("source", source),
+                            ("properties", properties)):
+            if value is not None:
+                payload[name] = value
+        for name, value in (("plot", plot), ("train", train), ("write", write)):
+            if value is not None:
+                payload[name] = value
+        response = self._process_request(
+            method="POST",
+            route=f"{Pipeline.route()}/{self._pipeline_uuid(pipeline)}/deploy/",
+            data=json.dumps(payload)
+        )
+        return Deployment.from_dict(response.json())
+
+    def deploy_preview(self, pipeline, **kwargs) -> dict:
+        """
+        plan a deploy without performing it: what would be merged, cut, built and
+        scheduled, and every reason it would be refused.
+
+        Writes nothing, and always answers 200 - read ``ok`` and ``problems`` rather
+        than catching an exception. Takes the same arguments as :meth:`deploy`.
+
+        :param pipeline: pipeline key, UUID or Pipeline.
+        :return: the plan, including 'ok' and 'problems'.
+        """
+        payload = {k: v for k, v in kwargs.items() if v is not None}
+        response = self._process_request(
+            method="POST",
+            route=f"{Pipeline.route()}/{self._pipeline_uuid(pipeline)}/deploy/preview/",
+            data=json.dumps(payload)
+        )
+        return response.json()
+
+    def _deployment_action(self, deployment, action: str) -> Deployment:
+        deployment_id = (deployment.deployment_id
+                         if isinstance(deployment, Deployment) else deployment)
+        response = self._process_request(
+            method="POST",
+            route=f"{Deployment.route()}/{deployment_id}/{action}/"
+        )
+        return Deployment.from_dict(response.json())
+
+    def pause_deployment(self, deployment) -> Deployment:
+        """
+        pause a deployment: delete its trigger, keep the record.
+
+        Synchronous. The manifest is kept, so :meth:`resume_deployment` rebuilds the
+        same schedule rather than asking for it again.
+
+        :param deployment: Deployment or its id.
+        :return: the updated Deployment.
+        """
+        return self._deployment_action(deployment, "pause")
+
+    def resume_deployment(self, deployment) -> Deployment:
+        """
+        resume a paused deployment, re-creating its trigger from the stored manifest.
+
+        :param deployment: Deployment or its id.
+        :return: the updated Deployment.
+        """
+        return self._deployment_action(deployment, "resume")
+
+    def retry_deployment(self, deployment) -> Deployment:
+        """
+        continue a failed or interrupted deployment from where it stopped.
+
+        Safe to call repeatedly: a merge or a release cut cannot be undone, so
+        completed steps are skipped rather than replayed.
+
+        :param deployment: Deployment or its id.
+        :return: the updated Deployment.
+        """
+        return self._deployment_action(deployment, "retry")
+
+    def await_deployment(self,
+                         deployment,
+                         timeout: int = 900,
+                         interval: int = 5) -> Deployment:
+        """
+        poll a deployment until it stops moving.
+
+        :param deployment: Deployment or its id.
+        :param timeout: seconds before giving up waiting.
+        :param interval: seconds between polls.
+        :return: the Deployment in its final state - check ``status``, which is
+            'deployed' on success and 'failed' otherwise.
+        """
+        import time
+        deployment_id = (deployment.deployment_id
+                         if isinstance(deployment, Deployment) else deployment)
+        deadline = time.time() + timeout
+        current = self.get(deployment_id=deployment_id)
+        while time.time() < deadline:
+            if current.status in (DeploymentStatus.DEPLOYED, DeploymentStatus.FAILED,
+                                  DeploymentStatus.PAUSED):
+                return current
+            time.sleep(interval)
+            current = self.get(deployment_id=deployment_id)
+        return current
+
     def build_image(self, key: str, branch: str = None) -> str:
         """
         build an image of a pipeline, store it on the image repository and return its pipeline image id.

{wizata_dsapi-2.1.0.dev18 → wizata_dsapi-2.1.0.dev20}/wizata_dsapi.egg-info/PKG-INFO

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

wizata_dsapi-2.1.0.dev18/wizata_dsapi/version.py

@@ -1 +0,0 @@
-__version__ = "2.1.0.dev18"