pinexq-client 0.3.0.2024.607.9__py3-none-any.whl → 0.3.0.2024.620.1__py3-none-any.whl

pinexq_client/core/__init__.py

@@ -0,0 +1,8 @@
+# ruff: noqa: F403, F401
+from .sirenaccess import *
+from .model.sirenmodels import *
+from .model.error import *
+from .media_types import *
+from .http_headers import *
+from .exceptions import *
+from .base_relations import BaseRelations

pinexq_client/core/base_relations.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+
+class BaseRelations(StrEnum):
+    SELF = "self"
+    ITEM = "item"
+    DOWNLOAD = "Download"
+    CREATED_RESSOURCE = "created-resource"

pinexq_client/core/enterapi.py

@@ -0,0 +1,17 @@
+from typing import TypeVar, Type
+
+import httpx
+
+from pinexq_client.core import Entity
+from pinexq_client.core.hco.hco_base import Hco
+
+THco = TypeVar('THco', bound=Hco)
+
+
+def enter_api(client: httpx.Client, entrypoint_hco_type: Type[THco], entrypoint_entity_type: Type[Entity] = Entity,
+              entrypoint: str = "api/EntryPoint") -> THco:
+    entry_point_response = client.get(url=entrypoint)
+    entry_point_response.raise_for_status()
+    entrypoint_entity = entrypoint_entity_type.model_validate_json(entry_point_response.read())
+
+    return entrypoint_hco_type.from_entity(entrypoint_entity, client)

pinexq_client/core/exceptions.py

@@ -0,0 +1,2 @@
+class SirenException(Exception):
+    pass

pinexq_client/core/hco/action_hco.py

@@ -0,0 +1,70 @@
+from typing import TypeVar, Self
+
+import httpx
+from httpx import Response
+from httpx import URL
+
+from pinexq_client.core import SirenException, Entity, Action, ProblemDetails, execute_action
+from pinexq_client.core.hco.hco_base import ClientContainer
+
+TEntity = TypeVar('TEntity', bound=Entity)
+THcoEntity = TypeVar('THcoEntity', bound=Entity)
+
+
+class ActionHco(ClientContainer):
+    _client: httpx.Client
+    _action: Action
+
+    @classmethod
+    def from_action_optional(cls, client: httpx.Client, action: Action | None) -> Self | None:
+        if action is None:
+            return None
+
+        if action.has_parameters():
+            raise SirenException(f"Error while mapping action: expected action no parameters but got some")
+
+        instance = cls(client)
+        instance._action = action
+        return instance
+
+    @classmethod
+    def from_entity_optional(cls, client: httpx.Client, entity: Entity, name: str) -> Self | None:
+        if entity is None:
+            return None
+
+        action = entity.find_first_action_with_name(name)
+        return cls.from_action_optional(client, action)
+
+    @classmethod
+    def from_action(cls, client: httpx.Client, action: Action) -> Self:
+        action = cls.from_action_optional(client, action)
+        if action is None:
+            raise SirenException(
+                f"Error while mapping mandatory action: does not exist")
+        return action
+
+    @classmethod
+    def from_entity(cls, client: httpx.Client, entity: Entity, name: str) -> Self:
+        result = cls.from_entity_optional(client, entity, name)
+        if result is None:
+            raise SirenException(
+                f"Error while mapping mandatory action {name}: does not exist")
+        return result
+
+    def _execute_internal(self) -> None | URL:
+        response = execute_action(self._client, self._action)
+
+        if isinstance(response, ProblemDetails):
+            raise SirenException(
+                f"Error while executing action: {response}")
+        if isinstance(response, Response):
+            raise SirenException(
+                f"Error while executing action, unexpected response: {response}")
+        return response
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}: '{self._action.name}'>"
+
+
+
+

pinexq_client/core/hco/action_with_parameters_hco.py

@@ -0,0 +1,86 @@
+from typing import TypeVar, Type, Self, Generic
+
+import httpx
+from httpx import Response
+from httpx import URL
+from pydantic import BaseModel
+
+from pinexq_client.core import SirenException, Entity, Action, ProblemDetails, execute_action
+from pinexq_client.core.hco.hco_base import ClientContainer
+
+TParameters = TypeVar('TParameters', bound=BaseModel)
+
+
+class ActionWithParametersHco(ClientContainer, Generic[TParameters]):
+    _client: httpx.Client
+    _action: Action
+
+    @classmethod
+    def from_action_optional(cls, client: httpx.Client, action: Action | None) -> Self | None:
+        if action is None:
+            return None
+
+        if not action.has_parameters():
+            raise SirenException(
+                f"Error while mapping action: expected action with parameters but got none")
+
+        instance = cls(client)
+        instance._action = action
+        return instance
+
+    @classmethod
+    def from_entity_optional(cls, client: httpx.Client, entity: Entity, name: str) -> Self | None:
+        if entity is None:
+            return None
+
+        action = entity.find_first_action_with_name(name)
+        return cls.from_action_optional(client, action)
+
+    @classmethod
+    def from_action(cls, client: httpx.Client, action: Action) -> Self:
+        action = cls.from_action_optional(client, action)
+        if action is None:
+            raise SirenException(
+                f"Error while mapping mandatory action: action does not exist")
+        return action
+
+    @classmethod
+    def from_entity(cls, client: httpx.Client, entity: Entity, name: str) -> Self:
+        result = cls.from_entity_optional(client, entity, name)
+        if result is None:
+            raise SirenException(
+                f"Error while mapping mandatory action {name}: action does not exist")
+        return result
+
+    def _execute_internal(self, parameters: BaseModel) -> None | URL:
+        if parameters is None:
+            raise SirenException(f"Error while executing action: action requires parameters")
+
+        response = execute_action(self._client, self._action, parameters)
+
+        if isinstance(response, ProblemDetails):
+            raise SirenException(
+                f"Error while executing action: {response}")
+        if isinstance(response, Response):
+            raise SirenException(
+                f"Error while executing action, unexpected response: {response}")
+        return response
+
+    def _execute(self, parameters: TParameters):
+        result = self._execute_internal(parameters)
+        if result is not None:
+            raise SirenException("Action did respond with unexpected URL")
+        return
+
+    def _execute_returns_url(self, parameters: TParameters) -> URL:
+        result = self._execute_internal(parameters)
+        if result is None:
+            raise SirenException("Action did not respond with URL")
+        return result
+
+    def _get_default_parameters(self, parameter_type: Type[TParameters],
+                                default_if_none: TParameters) -> TParameters:
+        return self._action.get_default_parameters(parameter_type, default_if_none)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}: '{self._action.name}'>"

pinexq_client/core/hco/download_link_hco.py

@@ -0,0 +1,37 @@
+from io import BytesIO
+from typing import Self
+
+import httpx
+from httpx import Response
+
+from pinexq_client.core import Link, Entity, get_resource, SirenException
+from pinexq_client.core.hco.link_hco import LinkHco
+
+
+class DownloadLinkHco(LinkHco):
+
+    @classmethod
+    def from_link_optional(cls, client: httpx.Client, link: Link | None) -> Self | None:
+        return super(DownloadLinkHco, cls).from_link_optional(client, link)
+
+    @classmethod
+    def from_entity_optional(cls, client: httpx.Client, entity: Entity, link_relation: str) -> Self | None:
+        return super(DownloadLinkHco, cls).from_entity_optional(client, entity, link_relation)
+
+    @classmethod
+    def from_link(cls, client: httpx.Client, link: Link) -> Self:
+        return super(DownloadLinkHco, cls).from_link(client, link)
+
+    @classmethod
+    def from_entity(cls, client: httpx.Client, entity: Entity, link_relation: str) -> Self:
+        return super(DownloadLinkHco, cls).from_entity(client, entity, link_relation)
+
+    def download(self) -> bytes:
+        response: Response = get_resource(self._client, self._link.href, self._link.type)
+        if not isinstance(response, Response):
+            raise SirenException(
+                f"Error while downloading resource: did not get response type")
+
+        return response.content
+
+    # TODO: download for large files

pinexq_client/core/hco/hco_base.py

@@ -0,0 +1,91 @@
+from dataclasses import dataclass
+from typing import List, TypeVar, Generic, Callable, Any
+
+import httpx
+from httpx import URL
+
+from pinexq_client.core import SirenException, Entity, BaseRelations, Link
+
+TEntity = TypeVar('TEntity', bound=Entity)
+THcoEntity = TypeVar('THcoEntity', bound=Entity)
+
+
+class ClientContainer:
+    _client: httpx.Client
+
+    def __init__(self, client: httpx.Client):
+        self._client = client
+
+    def __repr__(self):
+        variables = [f"{k}: {repr(v)}" for k, v in vars(self).items() if not k.startswith('_')]
+        var_repr = f" ({', '.join(variables)})"
+        return f"<{self.__class__.__name__}{var_repr if variables else ''}>"
+
+
+@dataclass
+class Property:
+    """
+    Sentinel object marking properties in an HCO object to be copied from the entity.
+
+    Args:
+        name: Name of the property in the entity. If not provided, it's assumed to be
+            the same as the property name in the Hco. [optional]
+        converter: A callable that will be applied to the value in the entity before
+            being assigned to the property in the Hco. [optional]
+    """
+    name: str | None = None
+    converter: Callable[[Any], Any] | None = None
+
+
+class Hco(ClientContainer, Generic[THcoEntity]):
+    _entity: THcoEntity
+
+    def __init__(self, client: httpx.Client, entity: THcoEntity):
+        super().__init__(client)
+        self._entity = entity
+        self._set_properties()
+
+    def __hash__(self):
+        # TODO: write a unit test ;)
+        candidate_self_link: Link | None = self._entity.find_first_link_with_relation(BaseRelations.SELF)
+        if candidate_self_link is not None:
+            return hash(URL(candidate_self_link.href).path)
+        else:
+            return super().__hash__()
+
+    def __eq__(self, other):
+        # TODO: write a unit test ;)
+        if isinstance(other, Hco):
+            return hash(self) == hash(other)
+        else:
+            return False
+
+    @staticmethod
+    def check_classes(existing_classes: List[str], expected_classes: List[str]):
+        for expected_class in expected_classes:
+            if expected_class not in existing_classes:
+                raise SirenException(
+                    f"Error while mapping entity:expected hco class {expected_class} is not a class of generic entity "
+                    f"with classes {existing_classes}")
+
+    def _set_properties(self):
+        """Initializes Hco properties from the entity.
+
+        Iterates over all properties defined in the class annotation. If one is initialized
+        with `Property()` the variable gets set from a property in self._entity.properties
+        with the same name.
+        """
+        for var_name, var_type in self.__annotations__.items():
+            # Get the initialized object. The annotation contain only the annotated type.
+            hco_property = getattr(self, var_name, None)
+            # Skip everything that is not initialized as `Property()`
+            if not (hco_property and isinstance(hco_property, Property)):
+                continue
+
+            if not hco_property.name:
+                hco_property.name = var_name
+            property_value = getattr(self._entity.properties, var_name)
+            if hco_property.converter:
+                property_value = hco_property.converter(property_value)
+            setattr(self, var_name, property_value)
+

pinexq_client/core/hco/link_hco.py

@@ -0,0 +1,57 @@
+from typing import Self, Type
+
+import httpx
+from httpx import URL
+
+from pinexq_client.core import Link, SirenException, Entity, navigate, ensure_siren_response
+from pinexq_client.core.hco.hco_base import ClientContainer, TEntity
+
+
+class LinkHco(ClientContainer):
+    _client: httpx.Client
+    _link: Link
+
+    @classmethod
+    def from_link_optional(cls, client: httpx.Client, link: Link | None) -> Self | None:
+        if link is None:
+            return None
+
+        instance = cls(client)
+        instance._link = link
+        return instance
+
+    @classmethod
+    def from_entity_optional(cls, client: httpx.Client, entity: Entity, link_relation: str) -> Self | None:
+        if entity is None:
+            return None
+
+        link = entity.find_first_link_with_relation(link_relation)
+        return cls.from_link_optional(client, link)
+
+    @classmethod
+    def from_link(cls, client: httpx.Client, link: Link) -> Self:
+        result = cls.from_link_optional(client, link)
+        if result is None:
+            raise SirenException(f"Error while mapping mandatory link: link is None")
+
+        return result
+
+    @classmethod
+    def from_entity(cls, client: httpx.Client, entity: Entity, link_relation: str) -> Self:
+        result = cls.from_entity_optional(client, entity, link_relation)
+        if result is None:
+            raise SirenException(
+                f"Error while mapping mandatory link: entity contains no link with relation {link_relation}")
+
+        return result
+
+    def _navigate_internal(self, parse_type: Type[TEntity] = Entity) -> TEntity:
+        response = navigate(self._client, self._link, parse_type)
+        return ensure_siren_response(response)
+
+    def get_url(self) -> URL:
+        return URL(self._link.href)
+
+    def __repr__(self):
+        rel_names = ', '.join((f"'{r}'" for r in self._link.rel))
+        return f"<{self.__class__.__name__}: {rel_names}>"

pinexq_client/core/hco/upload_action_hco.py

@@ -0,0 +1,113 @@
+from io import IOBase
+from typing import BinaryIO, Iterable, AsyncIterable, Any, Self, List
+
+import httpx
+from httpx import URL
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from pinexq_client.core import upload_file, upload_binary, upload_json, SirenException, MediaTypes, Action, Entity, \
+    SirenClasses
+from pinexq_client.core.hco.action_with_parameters_hco import ActionWithParametersHco
+
+
+class UploadParameters(BaseModel):
+    # arbitrary_types_allowed
+    model_config = ConfigDict(extra='forbid', arbitrary_types_allowed=True)
+    filename: str
+    mediatype: str = MediaTypes.OCTET_STREAM
+
+    file: IOBase | None = None
+    binary: str | bytes | Iterable[bytes] | AsyncIterable[bytes] | None = None
+    json_: Any | None = Field(None, alias='json')
+
+    @model_validator(mode='after')
+    def check_only_one_input_method(self) -> Self:
+        list_of_vars = [self.file, self.binary, self.json_]
+        initialized_vars_count = [v is not None for v in list_of_vars].count(True)
+
+        if initialized_vars_count == 0:
+            raise ValueError(f'Please provide a upload content: file, json, binary')
+        if initialized_vars_count > 1:
+            raise ValueError(f'Please provide only one upload content: file, json, binary')
+
+        return self
+
+
+class UploadAction(ActionWithParametersHco[UploadParameters]):
+    accept: str | None = None
+    max_filesize_bytes: int | None = None
+    allow_multiple: bool | None = None
+
+    @classmethod
+    def from_action_optional(cls, client: httpx.Client, action: Action | None) -> Self | None:
+        instance = super(UploadAction, cls).from_action_optional(client, action)
+
+        if instance:
+            cls.validate_file_upload_field(instance)
+            cls.assign_upload_constraints(instance)
+        return instance
+
+    @classmethod
+    def from_entity_optional(cls, client: httpx.Client, entity: Entity, name: str) -> Self | None:
+        instance = super(UploadAction, cls).from_entity_optional(client, entity, name)
+
+        if instance:
+            cls.validate_file_upload_field(instance)
+            cls.assign_upload_constraints(instance)
+        return instance
+
+    @classmethod
+    def from_action(cls, client: httpx.Client, action: Action) -> Self:
+        instance = super(UploadAction, cls).from_action(client, action)
+        cls.validate_file_upload_field(instance)
+        cls.assign_upload_constraints(instance)
+        return instance
+
+    @classmethod
+    def from_entity(cls, client: httpx.Client, entity: Entity, name: str) -> Self:
+        instance = super(UploadAction, cls).from_entity(client, entity, name)
+        cls.validate_file_upload_field(instance)
+        cls.assign_upload_constraints(instance)
+        return instance
+
+    def assign_upload_constraints(self):
+        upload_fields = self._action.fields[0]
+
+        self.accept = upload_fields.accept
+        self.max_filesize_bytes = upload_fields.maxFileSizeBytes
+        self.allow_multiple = upload_fields.allowMultiple
+
+    def validate_file_upload_field(self):
+        action = self._action
+        if SirenClasses.FileUploadAction not in action.class_:
+            raise SirenException(
+                f"Upload action does not have expected class: {str(SirenClasses.FileUploadAction)}. Got: {action.class_}")
+
+        if action.type != MediaTypes.MULTIPART_FORM_DATA.value:
+            raise SirenException(
+                f"Upload action does not have expected type: {str(MediaTypes.MULTIPART_FORM_DATA)}. Got: {action.type}")
+
+        upload_fields = self._action.fields[0]
+
+        if upload_fields.type != "file":
+            raise SirenException(
+                f"Upload action does not have expected field type: 'file'. Got: {upload_fields.type}")
+
+    def _upload(self, parameters: UploadParameters) -> URL:
+
+        result = None
+        if parameters.file is not None:
+            result = upload_file(self._client, self._action, parameters.file, parameters.filename, parameters.mediatype)
+
+        elif parameters.binary is not None:
+            result = upload_binary(self._client, self._action, parameters.binary, parameters.filename,
+                                   parameters.mediatype)
+
+        elif parameters.json_ is not None:
+            result = upload_json(self._client, self._action, parameters.json_, parameters.filename)
+        else:
+            raise SirenException("Did not execute upload, none selected")
+
+        if not isinstance(result, URL):
+            raise SirenException("Upload did not respond with location")
+        return result

pinexq_client/core/http_headers.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+
+class Headers(StrEnum):
+    API_KEY = "x-api-key"
+    CONTENT_TYPE = "Content-Type"
+    CONTENT_LENGTH = "Content-Length"
+    LOCATION_HEADER = "Location"
+

pinexq_client/core/media_types.py

@@ -0,0 +1,24 @@
+from enum import StrEnum
+
+
+class MediaTypes(StrEnum):
+    APPLICATION_JSON = "application/json"
+    SIREN = "application/vnd.siren+json"
+    PROBLEM_DETAILS = "application/problem+json"
+    MULTIPART_FORM_DATA = "multipart/form-data"
+    OCTET_STREAM = "application/octet-stream"
+
+    XML = "application/xml"
+    ZIP = "application/zip"
+    PDF = "application/pdf"
+    TEXT = "text/plain"
+    HTML = "text/html"
+    CSV = "text/csv"
+    SVG = "image/svg+xml"
+    PNG = "image/png"
+    JPEG = "image/jpeg"
+    BMP = "image/bmp"
+
+
+class SirenClasses(StrEnum):
+    FileUploadAction = "FileUploadAction"

pinexq_client/core/model/error.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+
+
+class ProblemDetails(BaseModel):
+    type: str | None = None
+    title: str | None = None
+    status: int | None = None
+    detail: str | None = None
+    instance: str | None = None