pinexq-client 0.2.0.2024.607.8__py3-none-any.whl

hypermedia_client/core/model/sirenmodels.py

@@ -0,0 +1,155 @@
+import warnings
+from typing import List, Any, Union, Type, TypeVar, Self
+
+from httpx import URL
+from pydantic import BaseModel, ConfigDict, constr, Field, field_validator, model_validator
+
+TParameters = TypeVar('TParameters', bound='BaseModel')
+TEntity = TypeVar('TEntity', bound='Entity')
+
+
+class SirenBaseModel(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid'
+    )
+
+
+class ActionField(SirenBaseModel):
+    name: constr(min_length=1)
+    type: str | None = None
+    value: Any | None = None
+    class_: List[str] | None = Field(None, alias='class')
+    title: str | None = None
+    accept: str | None = None
+    maxFileSizeBytes: int | None = None
+    allowMultiple: bool | None = None
+
+
+class Action(SirenBaseModel):
+    name: constr(min_length=1)
+    href: constr(min_length=1)
+    class_: List[str] | None = Field(None, alias='class')
+    method: str | None = None
+    title: str | None = None
+    type: str | None = None
+    fields: List[ActionField] | None = None
+
+    def has_parameters(self) -> bool:
+        return (self.fields is not None) and (len(self.fields) > 0)
+
+    def get_default_parameters(self, parameter_type: Type[TParameters] = Any,
+                               default_if_none: TParameters | None = None) -> TParameters | None:
+        if not self.has_parameters():
+            raise Exception("Can not get default parameters for action without parameters")
+        if len(self.fields) > 1:
+            raise Exception("Action has more than one field, can not determine default parameters")
+        if not self.fields[0].value:
+            return default_if_none
+        dump = self.fields[0].model_dump(by_alias=True)['value']
+        return parameter_type.model_validate(dump)
+
+
+class EmbeddedLinkEntity(SirenBaseModel):
+    class_: List[str] | None = Field(None, alias='class')
+    rel: List[str]
+    href: constr(min_length=1)
+    title: str | None = None
+    type: str | None = None
+
+
+class Link(SirenBaseModel):
+    href: constr(min_length=1)
+    rel: List[str]
+    class_: List[str] | None = Field(None, alias='class')
+    title: str | None = None
+    type: str | None = None
+
+    @classmethod
+    def from_url(cls,
+                 url: URL,
+                 relation: list[str],
+                 title: str | None = None,
+                 mediatype: str | None = None,
+                 class_: list[str] | None = None) -> Self:
+        instance = cls(href=str(url), rel=relation, title=title, type=mediatype)
+        instance.class_ = class_
+        return instance
+
+
+class Entity(SirenBaseModel):
+    rel: List[str] = []  # used when embedded
+    class_: List[str] | None = Field(None, alias='class')
+    title: str | None = None
+    properties: Any | None = None
+    entities: List[Union['Entity', EmbeddedLinkEntity]] | None = None
+    actions: List[Action] | None = None
+    links: List[Link] | None = None
+
+    @model_validator(mode='after')
+    def _check_extra_properties(self) -> Self:
+        if type(self) is Entity:
+            # skip this validation for the base class
+            return self
+        if isinstance(self.properties, dict):
+            warnings.warn(f"Unresolved properties in Entity '{self.title}'! Implementation might be incomplete?")
+        elif isinstance(self.properties, BaseModel) and self.properties.model_extra:
+            warnings.warn(
+                f"Entity with extra properties received! Possibly a version mismatch "
+                f"between server and client? "
+                f"(unexpected properties: {[n for n in self.properties.model_extra.keys()]})"
+            )
+        return self
+
+    def find_first_entity_with_relation(self, searched_relation: str, entity_type: Type[TEntity] = 'Entity'
+                                        ) -> Union[TEntity, None]:
+        if self.entities is None:
+            return None
+
+        for entity in self.entities:
+            if self.contains_relation(entity.rel, searched_relation):
+                return entity_type.model_validate(entity.model_dump(by_alias=True))
+        return None
+
+    def find_all_entities_with_relation(self, searched_relation: str,
+                                        entity_type: Type[TEntity] = 'Entity') -> List[TEntity]:
+        if self.entities is None:
+            return []
+
+        result = []
+        for entity in self.entities:
+            if self.contains_relation(entity.rel, searched_relation):
+                # map to requested entity type so properties are not in a dict
+                mapped = entity_type.model_validate(entity.model_dump(by_alias=True))
+                result.append(mapped)
+        return result
+
+    def find_first_link_with_relation(self, searched_relation: str) -> Link | None:
+        if self.links is None:
+            return None
+
+        for link in self.links:
+            if self.contains_relation(link.rel, searched_relation):
+                return link
+        return None
+
+    def action_exists(self, name: str) -> bool:
+        return self.find_first_action_with_name(name) is not None
+
+    @staticmethod
+    def contains_relation(relations: list[str] | None, searched_relation: str) -> bool:
+        if relations is None:
+            return False
+
+        for relation in relations:
+            if relation == searched_relation:
+                return True
+        return False
+
+    def find_first_action_with_name(self, name: str):
+        if self.actions is None:
+            return None
+
+        for action in self.actions:
+            if action.name == name:
+                return action
+        return None

hypermedia_client/core/polling.py

@@ -0,0 +1,37 @@
+import time
+from typing import Callable
+
+
+class PollingException(Exception):
+    pass
+
+
+def wait_until(
+        condition: Callable,
+        polling_interval_ms: int = 200,
+        timeout_ms: int = 5000,
+        timeout_message: str | None = None,
+        error_condition: Callable | None = None,
+        error_condition_message: str | None = None,
+
+) -> None:
+    start = time.time()
+    timeout = start + timeout_ms / 1000
+    while True:
+        now = time.time()
+        next_due = now + polling_interval_ms / 1000
+        success = condition()
+        if success:
+            return
+
+        if error_condition:
+            error = error_condition()
+            if error:
+                raise PollingException(
+                    f"{f': {error_condition_message}' if error_condition_message else 'Error condition meet while waiting'}")
+
+        if (timeout > 0) and (now > timeout):
+            raise TimeoutError(
+                f"{f': {timeout_message}' if timeout_message else f'Timeout while waiting. Waited: {timeout_ms}ms'}")
+
+        time.sleep(next_due - now)

hypermedia_client/core/sirenaccess.py

@@ -0,0 +1,173 @@
+import json
+import logging
+from io import BytesIO
+from typing import Any, BinaryIO, Iterable, AsyncIterable
+
+import httpx
+from httpx import Response
+from httpx import URL
+from pydantic import BaseModel
+
+from .exceptions import SirenException
+from .http_headers import Headers
+from .base_relations import BaseRelations
+from .media_types import MediaTypes
+from .model.error import ProblemDetails
+from .model.sirenmodels import Entity, Link, Action, TEntity
+
+logger = logging.getLogger(__name__)
+
+
+# for now, we do not support navigations to non siren links (e.g. external)
+def get_resource(client: httpx.Client, href: str, media_type: str = MediaTypes.SIREN,
+                 parse_type: type[TEntity] = Entity) -> TEntity | ProblemDetails | Response:
+    try:
+        # assume get for links
+        response = client.get(href)
+    except (httpx.ConnectTimeout, httpx.ConnectError) as exc:
+        raise SirenException(f"Http-client error requesting resource: {href}") from exc
+    expected_type = media_type or MediaTypes.SIREN  # if not specified expect siren
+
+    if response.status_code == httpx.codes.OK:
+        if (media_type := response.headers.get(Headers.CONTENT_TYPE, MediaTypes.SIREN)) != expected_type:
+            logger.warning(f"Expected type {expected_type} not matched by response: "
+                           f"' got: '{media_type}'")
+
+        if media_type == MediaTypes.SIREN.value or media_type is None:  # assume siren if not specified
+            resp = response.content.decode()
+            entity = parse_type.model_validate_json(resp)
+            return entity
+        else:
+            return response
+
+    elif response.status_code >= 400:
+        return handle_error_response(response)
+    else:
+        logger.warning(f"Unexpected return code: {response.status_code}")
+        return response
+
+
+def navigate(client: httpx.Client, link: Link,
+             parse_type: type[TEntity] = Entity) -> TEntity | ProblemDetails | Response:
+    return get_resource(client, link.href, link.type, parse_type)
+
+
+def ensure_siren_response(response: TEntity | ProblemDetails | Response) -> TEntity:
+    if isinstance(response, ProblemDetails):
+        raise SirenException(
+            f"Error while navigating: {response}")
+    if isinstance(response, Response):
+        raise SirenException(
+            f"Error while navigating, unexpected response: {response}")
+    return response
+
+
+def upload_json(client: httpx.Client, action: Action, json_payload: Any,
+                filename: str) -> None | URL | ProblemDetails | Response:
+    return upload_binary(client, action, json.dumps(json_payload), filename, MediaTypes.APPLICATION_JSON)
+
+
+def upload_binary(client: httpx.Client, action: Action, content: str | bytes | Iterable[bytes] | AsyncIterable[bytes],
+                  filename: str,
+                  mediatype: str = MediaTypes.OCTET_STREAM) -> None | URL | ProblemDetails | Response:
+
+    if isinstance(content, str):
+        payload = BytesIO(content.encode(encoding="utf-8"))
+    elif isinstance(content, bytes):
+        payload = BytesIO(content)
+    else:
+        # Fixme: iterable are not supported. Use the 'content' instead of the 'file' parameter of the request call?
+        raise NotImplemented('Iterables are not supported as payload (yet)! Convert to bytes or string.')
+
+    return upload_file(client, action, payload, filename, mediatype)
+
+
+# for now no support for multi file upload
+def upload_file(client: httpx.Client, action: Action, file: BinaryIO, filename: str,
+                mediatype: str = MediaTypes.OCTET_STREAM) -> None | URL | ProblemDetails | Response:
+    if action.type != MediaTypes.MULTIPART_FORM_DATA:
+        raise SirenException(
+            f"Action with upload requires type: {MediaTypes.MULTIPART_FORM_DATA} but found: {action.type}")
+
+    files = {'upload-file': (filename, file, mediatype)}
+    try:
+        response = client.request(method=action.method, url=action.href, files=files)
+    except httpx.RequestError as exc:
+        raise SirenException(f"Error from httpx while uploading data to: {action.href}") from exc
+    return handle_action_result(response)
+
+
+def execute_action_on_entity(client: httpx.Client, entity: Entity, name: str, parameters: BaseModel | None = None):
+    action = entity.find_first_action_with_name(name)
+    if action is None:
+        raise SirenException(f"Entity does not contain expected action: {name}")
+
+    return execute_action(client, action, parameters)
+
+
+def execute_action(client: httpx.Client, action: Action,
+                   parameters: BaseModel | None = None) -> None | URL | ProblemDetails | Response:
+    if action.has_parameters() is False:
+        # no parameters required
+        if parameters is not None:
+            raise SirenException(f"Action requires no parameters but got some")
+    else:
+        # parameters required
+        if parameters is None:
+            raise SirenException(f"Action requires parameters but non provided")
+
+    action_parameters = None
+    if parameters is not None:
+        action_parameters = parameters.model_dump_json(by_alias=True, exclude_none=True)
+
+    try:
+        response = client.request(
+            method=action.method,
+            url=action.href,
+            content=action_parameters,
+            headers={Headers.CONTENT_TYPE.value: MediaTypes.APPLICATION_JSON.value}
+        )
+    except httpx.RequestError as exc:
+        raise SirenException(f"Error from httpx while executing action: {action.href}") from exc
+
+    return handle_action_result(response)
+
+
+def handle_action_result(response: Response) -> None | URL | ProblemDetails | Response:
+    if response.status_code == httpx.codes.OK:
+        return
+    if response.status_code == httpx.codes.CREATED:
+        location_header = response.headers.get(Headers.LOCATION_HEADER, None)
+        if location_header is None:
+            logger.warning(f"Got created response without location header")
+            return
+
+        return URL(location_header)
+
+    elif response.status_code >= 400:
+        return handle_error_response(response)
+    else:
+        logger.warning(f"Unexpected return code: {response.status_code}")
+        return response
+
+
+def handle_error_response(response: Response) -> ProblemDetails | Response:
+    content_type = response.headers.get(Headers.CONTENT_TYPE, '')
+    if content_type.startswith(MediaTypes.PROBLEM_DETAILS.value):
+        return ProblemDetails.model_validate(response.json())
+    else:
+        logger.warning(
+            f"Error case did not return media type: '{MediaTypes.PROBLEM_DETAILS.value}', "
+            f"got '{response.headers.get(Headers.CONTENT_TYPE, None)}' instead!")
+        return response
+
+
+def navigate_self(client: httpx.Client, entity: Entity) -> Entity | ProblemDetails | None:
+    if entity is None:
+        return None
+
+    self_link = entity.find_first_link_with_relation(BaseRelations.SELF)
+    if self_link is None:
+        return None
+
+    return navigate(client, self_link)

hypermedia_client/job_management/__init__.py

@@ -0,0 +1,6 @@
+# ruff: noqa: F401
+from .enterjma import enter_jma
+from .tool import Job
+
+# Protocol version the JMA is using
+__jma_version__ = [6, 0, 0]

hypermedia_client/job_management/enterjma.py

@@ -0,0 +1,42 @@
+from typing import TypeVar, Type
+
+import httpx
+
+import logging
+
+from hypermedia_client.core import Entity
+from hypermedia_client.core.enterapi import enter_api
+from hypermedia_client.core.hco.hco_base import Hco
+from hypermedia_client.job_management.hcos.entrypoint_hco import EntryPointHco
+from hypermedia_client.job_management.model.sirenentities import EntryPointEntity
+import hypermedia_client.job_management
+
+LOG = logging.getLogger(__name__)
+
+THco = TypeVar("THco", bound=Hco)
+
+
+def _version_match_major_minor(ver1: list[int], ver2: list[int]) -> bool:
+    return all([v1 == v2 for v1, v2 in zip(ver1[:2], ver2[:2])])
+
+
+def enter_jma(
+    client: httpx.Client,
+    entrypoint_hco_type: Type[THco] = EntryPointHco,
+    entrypoint_entity_type: Type[Entity] = EntryPointEntity,
+    entrypoint: str = "api/EntryPoint",
+) -> EntryPointHco:
+    entry_point_hco = enter_api(client, entrypoint_hco_type, entrypoint_entity_type, entrypoint)
+
+    info = entry_point_hco.info_link.navigate()
+
+    # Check for matching protocol versions
+    client_version = hypermedia_client.job_management.__jma_version__
+    jma_version = [int(i) for i in str.split(info.api_version, '.')]
+    if not _version_match_major_minor(jma_version, client_version):
+        LOG.warning(
+            f"Version mismatch between 'hypermedia_client' (v{'.'.join(map(str ,client_version))}) "
+            f"and 'JobManagementAPI' (v{'.'.join(map(str, jma_version))})! "
+        )
+
+    return entry_point_hco

hypermedia_client/job_management/hcos/__init__.py

@@ -0,0 +1,12 @@
+from .input_dataslot_hco import *
+from .entrypoint_hco import *
+from .info_hco import *
+from .job_hco import *
+from .job_query_result_hco import *
+from .jobsroot_hco import *
+from .processing_step_hco import *
+from .processingstep_query_result_hco import *
+from .processingsteproot_hco import *
+from .workdata_hco import *
+from .workdata_query_result_hco import *
+from .workdataroot_hco import *

hypermedia_client/job_management/hcos/entrypoint_hco.py

@@ -0,0 +1,57 @@
+from enum import StrEnum
+from typing import Self
+
+import httpx
+
+from hypermedia_client.core.hco.hco_base import Hco
+from hypermedia_client.core.hco.link_hco import LinkHco
+from hypermedia_client.job_management.hcos.info_hco import InfoLink
+from hypermedia_client.job_management.hcos.jobsroot_hco import JobsRootLink
+from hypermedia_client.job_management.hcos.processingsteproot_hco import ProcessingStepsRootLink
+from hypermedia_client.job_management.hcos.workdataroot_hco import WorkDataRootLink
+from hypermedia_client.job_management.known_relations import Relations
+from hypermedia_client.job_management.model.sirenentities import EntryPointEntity
+
+
+class EntryPointLink(LinkHco):
+    def navigate(self) -> 'EntryPointHco':
+        return EntryPointHco.from_entity(self._navigate_internal(EntryPointEntity), self._client)
+
+
+class EntrypointRelations(StrEnum):
+    JOBS_ROOT = "JobsRoot"
+    WORKDATA_ROOT = "WorkDataRoot"
+    PROCESSINGSTEPS_ROOT = "ProcessingStepsRoot"
+    INFO = "Info"
+    ADMIN = "Admin"
+
+
+class EntryPointHco(Hco[EntryPointEntity]):
+    self_link: EntryPointLink
+    job_root_link: JobsRootLink
+    work_data_root_link: WorkDataRootLink
+    processing_step_root_link: ProcessingStepsRootLink
+    info_link: InfoLink
+
+    admin_link: LinkHco | None
+
+    @classmethod
+    def from_entity(cls, entity: EntryPointEntity, client: httpx.Client) -> Self:
+        instance = cls(client, entity)
+        Hco.check_classes(instance._entity.class_, ["EntryPoint"])
+
+        instance.self_link = EntryPointLink.from_entity(
+            instance._client, instance._entity, Relations.SELF)
+        instance.info_link = InfoLink.from_entity(
+            instance._client, instance._entity, EntrypointRelations.INFO)
+        instance.job_root_link = JobsRootLink.from_entity(
+            instance._client, instance._entity, EntrypointRelations.JOBS_ROOT)
+        instance.work_data_root_link = WorkDataRootLink.from_entity(
+            instance._client, instance._entity, EntrypointRelations.WORKDATA_ROOT)
+        instance.processing_step_root_link = ProcessingStepsRootLink.from_entity(
+            instance._client, instance._entity, EntrypointRelations.PROCESSINGSTEPS_ROOT)
+
+        instance.admin_link = LinkHco.from_entity_optional(
+            instance._client, instance._entity, EntrypointRelations.ADMIN)
+
+        return instance

hypermedia_client/job_management/hcos/info_hco.py

@@ -0,0 +1,42 @@
+from typing import Self
+
+import httpx
+
+from hypermedia_client.core.hco.hco_base import Hco, Property
+from hypermedia_client.core.hco.link_hco import LinkHco
+from hypermedia_client.job_management.hcos.user_hco import UserHco
+from hypermedia_client.job_management.known_relations import Relations
+from hypermedia_client.job_management.model.sirenentities import InfoEntity, UserEntity
+
+
+class InfoLink(LinkHco):
+    def navigate(self) -> "InfoHco":
+        return InfoHco.from_entity(self._navigate_internal(InfoEntity), self._client)
+
+
+class InfoHco(Hco[InfoEntity]):
+    api_version: str = Property()
+    build_version: str = Property()
+    current_user: UserHco
+    used_storage_in_bytes: int = Property()
+
+    self_link: InfoLink
+
+    @classmethod
+    def from_entity(cls, entity: InfoEntity, client: httpx.Client) -> Self:
+        instance = cls(client, entity)
+
+        Hco.check_classes(instance._entity.class_, ["Info"])
+
+        instance.self_link = InfoLink.from_entity(
+            instance._client, instance._entity, Relations.SELF
+        )
+
+        instance._extract_current_user()
+
+        return instance
+
+    def _extract_current_user(self):
+        user_entity = self._entity.find_first_entity_with_relation(
+            Relations.CURRENT_USER, UserEntity)
+        self.current_user = UserHco.from_entity(user_entity, self._client)

hypermedia_client/job_management/hcos/input_dataslot_hco.py

@@ -0,0 +1,82 @@
+from typing import Self
+
+import httpx
+
+from hypermedia_client.core import Link, MediaTypes
+from hypermedia_client.core.hco.action_hco import ActionHco
+from hypermedia_client.core.hco.action_with_parameters_hco import ActionWithParametersHco
+from hypermedia_client.core.hco.hco_base import Hco, Property
+from hypermedia_client.core.hco.link_hco import LinkHco
+from hypermedia_client.core.hco.upload_action_hco import UploadAction, UploadParameters
+from hypermedia_client.job_management.hcos.workdata_hco import WorkDataLink, WorkDataHco
+from hypermedia_client.job_management.known_relations import Relations
+from hypermedia_client.job_management.model.open_api_generated import SelectWorkDataForDataSlotParameters, \
+    SelectWorkDataCollectionForDataSlotParameters
+from hypermedia_client.job_management.model.sirenentities import InputDataSlotEntity, WorkDataEntity
+
+
+class InputDataSlotLink(LinkHco):
+    def navigate(self) -> 'InputDataSlotHco':
+        return InputDataSlotHco.from_entity(self._navigate_internal(InputDataSlotEntity), self._client)
+
+
+class InputDataSlotSelectWorkDataAction(ActionWithParametersHco[SelectWorkDataForDataSlotParameters]):
+    def execute(self, parameters: SelectWorkDataForDataSlotParameters):
+        self._execute(parameters)
+
+
+class InputDataSlotSelectWorkDataCollectionAction(ActionWithParametersHco[SelectWorkDataCollectionForDataSlotParameters]):
+    def execute(self, parameters: SelectWorkDataCollectionForDataSlotParameters):
+        self._execute(parameters)
+
+
+class InputDataSlotUploadWorkDataAction(UploadAction):
+    def execute(self, parameters: UploadParameters) -> WorkDataLink:
+        url = self._upload(parameters)
+        link = Link.from_url(url, [str(Relations.CREATED_RESSOURCE)], "Uploaded workdata", MediaTypes.SIREN)
+        return WorkDataLink.from_link(self._client, link)
+
+
+class InputDataSlotClearDataAction(ActionHco):
+    def execute(self):
+        self._execute_internal()
+
+
+class InputDataSlotHco(Hco[InputDataSlotEntity]):
+    is_configured: bool | None = Property()
+    title: str | None = Property()
+    description: str | None = Property()
+    media_type: str | None = Property()
+    selected_workdatas: list[WorkDataHco] | None
+
+    select_workdata_action: InputDataSlotSelectWorkDataAction | None
+    select_workdata_collection_action: InputDataSlotSelectWorkDataCollectionAction | None
+    clear_workdata_action: InputDataSlotClearDataAction | None
+
+    @classmethod
+    def from_entity(cls, entity: InputDataSlotEntity, client: httpx.Client) -> Self:
+        instance = cls(client, entity)
+        Hco.check_classes(instance._entity.class_, ["InputDataSlot"])
+
+        # actions
+        instance.select_workdata_action = InputDataSlotSelectWorkDataAction.from_entity_optional(
+            client, instance._entity, "SelectWorkData")
+        instance.select_workdata_collection_action = InputDataSlotSelectWorkDataCollectionAction.from_entity_optional(
+            client, instance._entity, "SelectWorkDataCollection")
+        instance.clear_workdata_action = InputDataSlotClearDataAction.from_entity_optional(
+            client, instance._entity, "Clear")
+
+        instance._extract_workdata()
+
+        return instance
+
+    def _extract_workdata(self):
+        self.selected_workdatas = []
+
+        workdatas: list[WorkDataEntity] = self._entity.find_all_entities_with_relation(Relations.SELECTED,
+                                                                                       WorkDataEntity)
+        if not workdatas:
+            return
+
+        self.selected_workdatas = list[WorkDataHco](
+            WorkDataHco.from_entity(workdata, self._client) for workdata in workdatas)