pinexq-client 0.2.0.2024.607.8__py3-none-any.whl

hypermedia_client/job_management/model/sirenentities.py

@@ -0,0 +1,112 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+from hypermedia_client.core import Entity
+from hypermedia_client.job_management.model.open_api_generated import (
+    InfoHtoOpenApiProperties,
+    EntryPointHtoOpenApiProperties,
+    JobsRootHtoOpenApiProperties,
+    JobQueryResultHtoOpenApiProperties,
+    JobHtoOpenApiProperties,
+    WorkDataHtoOpenApiProperties,
+    ProcessingStepHtoOpenApiProperties,
+    WorkDataQueryResultHtoOpenApiProperties,
+    WorkDataRootHtoOpenApiProperties,
+    ProcessingStepRootHtoOpenApiProperties,
+    ProcessingStepQueryResultHtoOpenApiProperties,
+    JobUsedTagsHtoOpenApiProperties,
+    ProcessingStepUsedTagsHtoOpenApiProperties,
+    UserHtoOpenApiProperties,
+    WorkDataUsedTagsQueryResultHtoOpenApiProperties,
+)
+
+
+# ToDo: make these Generics bound to Entity
+
+
+class EntryPointEntity(Entity):
+    properties: EntryPointHtoOpenApiProperties | None = None
+
+
+class InfoEntity(Entity):
+    properties: InfoHtoOpenApiProperties | None = None
+
+
+class JobsRootEntity(Entity):
+    properties: JobsRootHtoOpenApiProperties | None = None
+
+
+class JobQueryResultEntity(Entity):
+    properties: JobQueryResultHtoOpenApiProperties | None = None
+
+
+class JobEntity(Entity):
+    properties: JobHtoOpenApiProperties | None = None
+
+
+class WorkDataEntity(Entity):
+    properties: WorkDataHtoOpenApiProperties | None = None
+
+
+class WorkDataRootEntity(Entity):
+    properties: WorkDataRootHtoOpenApiProperties | None = None
+
+
+class WorkDataQueryResultEntity(Entity):
+    properties: WorkDataQueryResultHtoOpenApiProperties | None = None
+
+
+class ProcessingStepEntity(Entity):
+    properties: ProcessingStepHtoOpenApiProperties | None = None
+
+
+class ProcessingStepsRootEntity(Entity):
+    properties: ProcessingStepRootHtoOpenApiProperties | None = None
+
+
+class ProcessingStepQueryResultEntity(Entity):
+    properties: ProcessingStepQueryResultHtoOpenApiProperties | None = None
+
+
+class WorkDataUsedTagsQueryResultEntity(Entity):
+    properties: WorkDataUsedTagsQueryResultHtoOpenApiProperties | None = None
+
+
+class ProcessingStepUsedTagsEntity(Entity):
+    properties: ProcessingStepUsedTagsHtoOpenApiProperties | None = None
+
+
+class JobUsedTagsEntity(Entity):
+    properties: JobUsedTagsHtoOpenApiProperties | None = None
+
+
+class InputDataSlotHtoProperties(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+    )
+    is_configured: bool | None = Field(None, alias="IsConfigured")
+    title: str | None = Field(None, alias="Title")
+    description: str | None = Field(None, alias="Description")
+    media_type: str | None = Field(None, alias="MediaType")
+
+
+class InputDataSlotEntity(Entity):
+    properties: InputDataSlotHtoProperties | None = None
+
+
+class OutputDataSlotHtoProperties(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+    )
+    title: str | None = Field(None, alias="Title")
+    description: str | None = Field(None, alias="Description")
+    media_type: str | None = Field(None, alias="MediaType")
+
+
+class OutputDataSlotEntity(Entity):
+    properties: OutputDataSlotHtoProperties | None = None
+
+
+class UserEntity(Entity):
+    properties: UserHtoOpenApiProperties | None = None

hypermedia_client/job_management/tool/__init__.py

@@ -0,0 +1 @@
+from .job import Job

hypermedia_client/job_management/tool/job.py

@@ -0,0 +1,442 @@
+import json as json_
+from typing import Any, Self
+
+import httpx
+from httpx import URL
+
+from hypermedia_client.core import Link, MediaTypes
+from hypermedia_client.core.polling import wait_until, PollingException
+from hypermedia_client.job_management.enterjma import enter_jma
+from hypermedia_client.job_management.hcos import WorkDataLink
+from hypermedia_client.job_management.hcos.entrypoint_hco import EntryPointHco
+from hypermedia_client.job_management.hcos.job_hco import (
+    JobHco,
+    GenericProcessingConfigureParameters,
+    JobLink,
+)
+from hypermedia_client.job_management.hcos.job_query_result_hco import JobQueryResultHco
+from hypermedia_client.job_management.hcos.jobsroot_hco import JobsRootHco
+from hypermedia_client.job_management.hcos.processingsteproot_hco import (
+    ProcessingStepsRootHco,
+)
+from hypermedia_client.job_management.known_relations import Relations
+from hypermedia_client.job_management.model import (
+    CreateJobParameters,
+    ProcessingStepQueryParameters,
+    ProcessingStepFilterParameter,
+    SelectProcessingParameters,
+    JobStates,
+    CreateSubJobParameters,
+    JobQueryParameters,
+    JobSortPropertiesSortParameter,
+    JobFilterParameter,
+    SelectWorkDataForDataSlotParameters, SetJobTagsParameters, SelectWorkDataCollectionForDataSlotParameters,
+)
+
+
+class Job:
+    """Convenience wrapper for handling JobHcos in the JobManagement-Api.
+
+    This wrapper allows the API to be used with a fluent-style builder pattern:
+
+    job = (
+        Job(client)
+        .create(name='JobName')
+        .select_processing(processing_step='job_processing')
+        .configure_parameters(**job_parameters)
+        .start()
+        .wait_for_state(JobStates.completed)
+        .delete()
+    )
+    """
+
+    _client: httpx.Client
+    _entrypoint: EntryPointHco
+    _jobs_root: JobsRootHco
+    _job: JobHco | None = None
+    _processing_step_root: ProcessingStepsRootHco
+
+    def __init__(self, client: httpx.Client):
+        """
+
+        Args:
+            client: An httpx.Client instance initialized with the api-host-url as `base_url`
+        """
+        self._client = client
+        self._entrypoint = enter_jma(client)
+        self._jobs_root = self._entrypoint.job_root_link.navigate()
+        self._processing_step_root = (
+            self._entrypoint.processing_step_root_link.navigate()
+        )
+
+    def create(self, name: str) -> Self:
+        """
+        Creates a new job by name.
+
+        Args:
+            name: Name of the job to be created
+
+        Returns:
+            The newly created job as `Job` object
+        """
+        job_link = self._jobs_root.create_job_action.execute(
+            CreateJobParameters(name=name)
+        )
+        self._get_by_link(job_link)
+        return self
+
+    def _get_by_link(self, job_link: JobLink):
+        self._job = job_link.navigate()
+
+    @classmethod
+    def from_url(cls, client: httpx.Client, job_url: URL) -> Self:
+        """Initializes a `Job` object from an existing job given by its link as URL.
+
+        Args:
+            client: An httpx.Client instance initialized with the api-host-url as `base_url`
+            job_url:
+
+        Returns:
+            The newly created job as `Job` object
+        """
+        link = Link.from_url(
+            job_url,
+            [str(Relations.CREATED_RESSOURCE)],
+            "Created sub-job",
+            MediaTypes.SIREN,
+        )
+        job_instance = cls(client)
+        job_instance._get_by_link(JobLink.from_link(client, link))
+        return job_instance
+
+    def create_sub_job(self, name: str) -> "Job":
+        """Create a new job by name as a sub-job of the current one.
+
+        Args:
+            name:
+                Name of the job to be created
+        Returns:
+            The newly created job as `Job` object
+        """
+        parent_job_url = self._job.self_link.get_url()
+        sub_job_link = self._jobs_root.create_subjob_action.execute(
+            CreateSubJobParameters(name=name, parent_job_url=str(parent_job_url))
+        )
+        sub_job = Job(self._client)
+        sub_job._get_by_link(sub_job_link)
+        return sub_job
+
+    def refresh(self) -> Self:
+        """Updates the job from the server
+
+        Returns:
+            This `Job` object, but with updated properties.
+        """
+        self._job = self._job.self_link.navigate()
+        return self
+
+    def get_state(self) -> JobStates:
+        """Returns the current state of this job from the server
+
+        Returns:
+            The current state of this `Job` from JobStates
+        """
+        self.refresh()
+        return self._job.state
+
+    def select_processing(self, processing_step: str) -> Self:
+        """Set the processing step for this job given by name. This will query all
+        processing steps of this name from the server and select the first result.
+
+        Args:
+            processing_step: Name of the processing step as string
+
+        Returns:
+            This `Job` object
+        """
+        # ToDo: provide more parameters to query a processing step
+        query_param = ProcessingStepQueryParameters(
+            filter=ProcessingStepFilterParameter(
+                function_name_contains=processing_step,
+            )
+        )
+        query_result = self._processing_step_root.query_action.execute(query_param)
+        candidates = [p for p in query_result.processing_steps if p.function_name == processing_step]
+        if len(candidates) == 0:
+            raise AttributeError(f"No processing step with the name '{processing_step}' registered!")
+        if len(candidates) > 1:
+            raise AttributeError(f"Multiple results querying processing step '{processing_step}'!")
+        assert len(candidates) == 1
+        # Todo: For now we choose the first and only result. Make this more flexible?
+        processing_url = candidates[0].self_link.get_url()
+
+        self._job.select_processing_action.execute(
+            SelectProcessingParameters(processing_step_url=str(processing_url))
+        )
+
+        self.refresh()
+
+        return self
+
+    def configure_parameters(self, **parameters: Any) -> Self:
+        """Set the parameters to run the processing step with.
+
+        Args:
+            **parameters: Any keyword parameters provided will be forwarded as parameters
+                to the processing step function.
+
+        Returns:
+            This `Job` object
+        """
+        self._job.configure_processing_action.execute(
+            GenericProcessingConfigureParameters.model_validate(parameters)
+        )
+
+        self.refresh()
+        return self
+
+    def start(self) -> Self:
+        """Start processing this job.
+
+        Returns:
+            This `Job` object
+        """
+        self._job.start_processing_action.execute()
+        self.refresh()
+        return self
+
+    def get_result(self) -> Any:
+        """Get the return value of the processing step after its completion.
+
+        This value is not defined before completion, so check the state first or
+        wait explicitly for it to complete.
+
+        Returns:
+            The result of the processing step
+        """
+        # TODO: return Sentinel or Exception on 'NotDoneYet'
+        # TODO: handle return value equivalent to asyncio's Future objects
+        self.refresh()
+        result = self._job.result
+        return json_.loads(result) if result else None
+
+    def wait_for_state(self, state: JobStates, timeout_ms: int = 5000) -> Self:
+        """Wait for this job to reach a state.
+
+        Args:
+            state: The state to wait for. After the job enters this state this function returns.
+            timeout_ms: Time span in milliseconds to wait for reaching the state before
+                raising an exception.
+
+        Returns:
+            This `Job` object
+        """
+        try:
+            wait_until(
+                condition=lambda: self.get_state() == state,
+                timeout_ms=timeout_ms,
+                timeout_message="Waiting for job completion",
+                error_condition=lambda: self._job.state == JobStates.error,
+            )
+        except TimeoutError as timeout:
+            raise Exception(
+                f"Job did not reach state: '{state.value}' "
+                f"current state: '{self.get_state().value}'. Error:{str(timeout)}"
+            )
+        except PollingException:
+            if self._job.state == JobStates.error:
+                error_reason = self._job.error_description
+                raise Exception(f"Job failed'. Error:{error_reason}")
+            raise Exception("Job failed")
+
+        return self
+
+    def assign_input_dataslot(self, index: int, workdata_link: WorkDataLink) -> Self:
+        """Assign WorkData to DataSlots.
+
+        Args:
+            index: The numerical index of the dataslot.
+            workdata_link:  WorkData given by its URL
+
+        Returns:
+            This `Job` object
+        """
+        dataslot = self._job.input_dataslots[index]
+        dataslot.select_workdata_action.execute(
+            parameters=SelectWorkDataForDataSlotParameters(
+                work_data_url=str(workdata_link.get_url())
+            )
+        )
+        self.refresh()
+
+        return self
+
+    def assign_collection_input_dataslot(self, index: int, workdata_links: list[WorkDataLink]) -> Self:
+        """Assign WorkData to DataSlots.
+
+        Args:
+            index: The numerical index of the dataslot.
+            workdata_links:  WorkData collection given by their URLs
+
+        Returns:
+            This `Job` object
+        """
+        dataslot = self._job.input_dataslots[index]
+        dataslot.select_workdata_collection_action.execute(
+            parameters=SelectWorkDataCollectionForDataSlotParameters(
+                work_data_urls=list[str](str(workdata_link.get_url()) for workdata_link in workdata_links)
+            )
+        )
+        self.refresh()
+
+        return self
+
+    def clear_input_dataslot(self, index: int) -> Self:
+        """Clear the selected WorkData for a dataslot.
+
+        Args:
+            index: he numerical index of the dataslot.
+
+        Returns:
+            This `Job` object
+        """
+        dataslot = self._job.input_dataslots[index]
+
+        # already cleared
+        if not dataslot.clear_workdata_action:
+            return
+
+        dataslot.clear_workdata_action.execute()
+        self.refresh()
+
+        return self
+
+    def _get_sub_jobs(
+            self,
+            sort_by: JobSortPropertiesSortParameter | None = None,
+            state: JobStates | None = None,
+            name: str | None = None,
+            show_deleted: bool | None = None,
+            processing_step_url: str | None = None,
+    ) -> JobQueryResultHco:
+        filter_param = JobFilterParameter(
+            is_sub_job=True,
+            parent_job_url=str(self._job.self_link.get_url()),
+            state=state,
+            name=name,
+            show_deleted=show_deleted,
+            processing_step_url=processing_step_url,
+        )
+        query_param = JobQueryParameters(sort_by=sort_by, filter=filter_param)
+        job_query_result = self._jobs_root.job_query_action.execute(query_param)
+        return job_query_result
+
+    def get_sub_jobs(self, **tbd):
+        # todo: Query result iterator to go through paginated result
+        raise NotImplementedError
+
+    def sub_jobs_in_state(self, state: JobStates) -> int:
+        """Query how many sub-job are in a specific state.
+
+        Args:
+            state: Job state as `JobStates` enum.
+
+        Returns:
+            The number of sub-jobs in the requested state.
+        """
+        query_result = self._get_sub_jobs(state=state)
+        return query_result.total_entities
+
+    def wait_for_sub_jobs_complete(self, timeout_ms: int = 0) -> Self:
+        """Wait for all sub-jobs to reach the state 'completed'.
+
+        This function will block execution until the state is reached or raise an exception
+        if the operation timed out or a sub-job returned an error.
+
+        Args:
+            timeout_ms: Timeout to wait for the sub-jobs to reach the next state.
+
+        Returns:
+            This `Job` object
+        """
+        wait_until(
+            condition=lambda: self.sub_jobs_in_state(JobStates.pending) == 0,
+            timeout_ms=timeout_ms,
+            timeout_message=f"Timeout while waiting for sub-jobs to complete! [timeout: {timeout_ms}ms]",
+        )
+        wait_until(
+            condition=lambda: self.sub_jobs_in_state(JobStates.processing) == 0,
+            timeout_ms=timeout_ms,
+            timeout_message=f"Timeout while waiting for sub-jobs to complete! [timeout: {timeout_ms}ms]",
+        )
+        wait_until(
+            condition=lambda: self.sub_jobs_in_state(JobStates.completed) >= 0,
+            error_condition=lambda: self.sub_jobs_in_state(JobStates.error) >= 0,
+            error_condition_message="One or more sub-jobs returned an error!",
+            timeout_ms=timeout_ms,
+            timeout_message=f"Timeout while waiting for sub-jobs to complete! [timeout: {timeout_ms}ms]",
+        )
+        return self
+
+    def hide(self) -> Self:
+        """Mark this job as hidden.
+
+        Returns:
+            This `Job` object
+        """
+        self._job.hide_action.execute()
+        self.refresh()
+        return self
+
+    def unhide(self):
+        """Reveal this job again.
+
+        Returns:
+            This `Job` object"""
+        self._job.unhide_action.execute()
+        self.refresh()
+        return self
+
+    def allow_output_data_deletion(self):
+        """Mark all output workdata from this job as "deletable".
+
+        Returns:
+            This `Job` object"""
+        self._job.allow_output_data_deletion_action.execute()
+        self.refresh()
+        return self
+
+    def disallow_output_data_deletion(self):
+        """Mark all output workdata from this job as "not deletable".
+
+        Returns:
+            This `Job` object"""
+        self._job.disallow_output_data_deletion_action.execute()
+        self.refresh()
+        return self
+
+    def set_tags(self, tags: list[str]):
+        """Set tags to the job.
+
+        Returns:
+            This `Job` object"""
+        self._job.edit_tags_action.execute(SetJobTagsParameters(
+            tags=tags
+        ))
+        self.refresh()
+        return self
+
+
+    def get_input_data_slots(self):
+        """Returns list of InputDataSlotHco objects.
+
+        Returns:
+            `list[InputDataSlotHco]` object"""
+        return self._job.input_dataslots
+
+    def get_output_data_slots(self):
+        """Returns list of OutputDataSlotHco objects.
+
+        Returns:
+            `list[OutputDataSlotHco]` object"""
+        return self._job.output_dataslots

pinexq_client-0.2.0.2024.607.8.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.1
+Name: pinexq-client
+Version: 0.2.0.2024.607.8
+Summary: A hypermedia-based client for the DataCybernetics PinexQ platform.
+Author-Email: =?utf-8?q?Sebastian_H=C3=B6fer?= <hoefer@data-cybernetics.com>, Mathias Reichardt <reichardt@data-cybernetics.com>
+Maintainer-Email: Mathias Reichardt <reichardt@data-cybernetics.com>, =?utf-8?q?Sebastian_H=C3=B6fer?= <hoefer@data-cybernetics.com>, Carsten Blank <blank@data-cybernetics.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3.0.0,>=2.1.0
+Requires-Dist: httpx<1.0.0,>=0.25.0
+Description-Content-Type: text/markdown
+
+# Pine-x-Q Python Client
+
+A hypermedia-based client for the DataCybernetics PinexQ platform.
+
+This module contains the submodules:
+
+- `core`: A generic *hypermedia client* (HC) to work with siren hypermedia APIs
+[Siren on GitHub](https://github.com/kevinswiber/siren)
+
+- `job_management`: Specialized HC-object (HCO) implementations for the PinexQ *Job-Management API* (JMA).
+
+## Installation
+
+Install from PyPI by running
+
+```pip install pinexq-client```
+
+## Setup the Client
+
+The hypermedia client uses [HTTPX](https://github.com/projectdiscovery/httpx) as a backend.
+To access the API you need to provide a pre-configured HTTPX-client with a valid API key for authentication. 
+From The API key the user and permissions are derived so do not share the API key and store it securely.
+
+To initialize the client parts must be supplied:
+
+- The API key (as header)
+- The API host as URL with port if required
+
+```python
+from httpx import Client
+
+from hypermedia_client.job_management.enterjma import enter_jma
+from hypermedia_client.job_management.hcos.entrypoint_hco import EntryPointHco
+
+
+client = Client(
+    base_url="https://myapihost.com:80", 
+    headers={'x-api-key': '<SECRET_PAT>'}
+)
+
+# the client is now ready to be passed to function entering the API
+entrypoint: EntryPointHco = enter_jma(client)
+```
+
+
+## Using the API
+
+There is a convenience layer wrapping job-management-specific objects in interface classes for ease of use.
+In the spirit of a hypermedia API you can also use low level calls to navigate the API.
+
+### Job-Management Interface
+
+The main concepts of the job-management-API (e.g. "Jobs") are wrapped in  
+
+```python
+from hypermedia_client.job_management.tool import Job
+from hypermedia_client.job_management.model import JobStates
+job = (
+    Job(client)
+    .create(name="JobName")
+    .select_processing(processing_step="step_function_name")
+    .configure_parameters(param_name="value")
+    .start()
+    .wait_for_state(JobStates.completed)
+)
+result = job.get_result()
+```
+
+### Raw Hypermedia API
+
+You can navigate and use the full API with raw hypermedia primitives, e.g. when features are not yet exposed in the convenience wrapper.
+
+```python
+from hypermedia_client.job_management.enterjma import enter_jma
+from hypermedia_client.job_management.hcos.entrypoint_hco import EntryPointHco
+from hypermedia_client.job_management.model import CreateJobParameters, SetJobTagsParameters
+
+entrypoint: EntryPointHco = enter_jma(client)
+# Get to jobs root
+job_root = entrypoint.job_root_link.navigate()
+# Create a new job
+parameters = CreateJobParameters(name="Test Job")
+job = job_root.create_job_action.execute(parameters).navigate()
+# Edit the job's tags
+job.edit_tags_action.execute(SetJobTagsParameters(tags=["test", ]))
+
+...
+```
+
+
+
+
+