decaf-api-client 0.0.12__py3-none-any.whl

decaf/api/client/__init__.py

@@ -0,0 +1,2 @@
+#: Defines the name of the :mod:`decaf.api.client` package.
+__version__ = "0.0.12"  # x-release-please-version

decaf/api/client/_internal.py

@@ -0,0 +1,13 @@
+"""
+This module provides internal definitions and functionality.
+"""
+
+__all__ = ["ProgrammingError"]
+
+
+class ProgrammingError(Exception):
+    """
+    Provides an exception class for internal programming errors.
+    """
+
+    pass

decaf/api/client/machinery.py

@@ -0,0 +1,820 @@
+"""
+This module provides the essential machinery to perform remote API requests and define endpoint client implementations.
+"""
+
+__all__ = [
+    "APIClientError",
+    "APIHeaderAuthorization",
+    "APIKeyAuthorization",
+    "APIServerError",
+    "APIServerErrorBadAuthorization",
+    "APIServerErrorBadRequest",
+    "APIServerErrorBlowup",
+    "APIServerErrorNotFound",
+    "APITokenAuthorization",
+    "Authorization",
+    "BaseCreateForm",
+    "BasePatchForm",
+    "BaseResource",
+    "BaseUpdateForm",
+    "Client",
+    "DeleteEndpoint",
+    "Endpoint",
+    "Error",
+    "Missing",
+    "RFiles",
+    "RHeaders",
+    "RMethod",
+    "RParams",
+    "RPath",
+    "RTimeout",
+    "Request",
+    "ResourceCreateEndpoint",
+    "ResourceEndpoint",
+    "ResourceListEndpoint",
+    "ResourcePatchEndpoint",
+    "ResourceRetrieveEndpoint",
+    "ResourceUpdateEndpoint",
+    "StandardResourceEndpoint",
+    "command",
+    "query",
+]
+
+import re
+import time
+from abc import abstractmethod
+from dataclasses import dataclass, field
+from json import load as loadjson
+from pathlib import Path
+from typing import (
+    Any,
+    BinaryIO,
+    Callable,
+    ClassVar,
+    Dict,
+    Generator,
+    Generic,
+    Iterable,
+    List,
+    Literal,
+    Optional,
+    Set,
+    TextIO,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+)
+from urllib.parse import urljoin
+
+import requests
+from pydantic import BaseModel, Field
+from requests.auth import AuthBase
+
+
+@dataclass(frozen=True)
+class Error(Exception):
+    """
+    Provides a base exception model for the DECAF client library.
+
+    .. note:: You should probably catch sub-classes of this exception class.
+    """
+
+    #: Error message.
+    message: str
+
+
+@dataclass(frozen=True)
+class APIClientError(Error):
+    """
+    Provides an exception model for errors generated during request-response cycle (not by the API server).
+    """
+
+    #: Underlying exception.
+    underlying: Exception
+
+
+@dataclass(frozen=True)
+class APIServerError(Error):
+    """
+    Provides an exception for API server generated errors.
+    """
+
+    #: HTTP status code of the error response received from the API server.
+    status: int
+
+    #: Payload of the error response received from the API server.
+    payload: Union[str, bytes, None]
+
+
+@dataclass(frozen=True)
+class APIServerErrorBadRequest(APIServerError):
+    """
+    Provides an exception for API server generated HTTP 400 errors.
+    """
+
+    #: Error definition.
+    feedback: Dict[str, List[str]]
+
+
+@dataclass(frozen=True)
+class APIServerErrorBadAuthorization(APIServerError):
+    """
+    Provides an exception for API server generated HTTP 401, 403 and 405 errors.
+    """
+
+    pass
+
+
+@dataclass(frozen=True)
+class APIServerErrorNotFound(APIServerError):
+    """
+    Provides an exception for API server generated HTTP 404 errors.
+    """
+
+    pass
+
+
+@dataclass(frozen=True)
+class APIServerErrorBlowup(APIServerError):
+    """
+    Provides an exception for API server generated HTTP 5XX errors.
+    """
+
+    pass
+
+
+#: Defines a type alias for HTTP verbs.
+RMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+
+#: Defines a type alias for relative path or path segments of the remote API endpoint.
+RPath = Union[str, List[Union[str, int]]]
+
+#: Defines a type alias for query-string parameters.
+RParams = Dict[str, Union[str, int, List[str], List[int]]]
+
+#: Defines a type alias for HTTP request headers.
+RHeaders = Dict[str, str]
+
+#: Defines a type alias for file objects.
+_FileObject = Union[str, bytes, bytearray, TextIO, BinaryIO]
+
+#: Defines a type alias for file object maps to be passed for multi-part uploads.
+RFiles = Dict[str, Union[_FileObject, Tuple[_FileObject, str], Tuple[_FileObject, str, Dict[str, str]]]]
+
+#: Defines a type alias for HTTP request timeouts.
+RTimeout = Tuple[float, float]
+
+
+@dataclass(frozen=True)
+class Request:
+    """
+    Defines a high(ish)-level client request model.
+    """
+
+    #: Request method.
+    method: RMethod
+
+    #: Relative path or path segments for the remote API endpoint URL.
+    path: RPath
+
+    #: Request parameters, if any.
+    params: Optional[RParams] = None
+
+    #: Request data payload, if any.
+    data: Any = None
+
+    #: Request data payload in JSON, if any (convenience for sending ``application/json`` payloads).
+    json: Any = None
+
+    #: Request data payload files, if any (convenience for uploading multipart payloads).
+    files: Optional[RFiles] = None
+
+    #: Request headers.
+    headers: Optional[RHeaders] = None
+
+    #: Defines the timeout, if any:
+    timeout: Optional[RTimeout] = None
+
+
+class Authorization:
+    """
+    Provides a base class for client authorization.
+    """
+
+    @abstractmethod
+    def headers(self) -> Dict[str, str]:
+        """
+        Provides the client authorization header for HTTP requests.
+        """
+        pass
+
+
+@dataclass(frozen=True)
+class APIKeyAuthorization(Authorization):
+    """
+    Provides API key authorization method.
+    """
+
+    #: Defines the API key.
+    key: str = field(repr=False)
+
+    #: Defines the API secret.
+    scr: str = field(repr=False)
+
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Key {self.key}:{self.scr}"}
+
+
+@dataclass(frozen=True)
+class APITokenAuthorization(Authorization):
+    """
+    Provides API token authorization method.
+    """
+
+    #: API token.
+    token: str = field(repr=False)
+
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Token {self.token}"}
+
+
+@dataclass(frozen=True)
+class APIHeaderAuthorization(Authorization):
+    """
+    Provides authorization method directly from authentication headers.
+    """
+
+    #: HTTP headers
+    buffer: RHeaders
+
+    def headers(self) -> Dict[str, str]:
+        return self.buffer
+
+
+@dataclass(frozen=True)
+class Client:
+    """
+    Provides a high-level client implementation for DECAF API.
+    """
+
+    #: Base API URI.
+    url: str
+
+    #: API authorization.
+    auth: Authorization
+
+    class _NullAuth(AuthBase):
+        """
+        Provides the no-op authentication provider implementation.
+        """
+
+        def __call__(self, r: Any) -> Any:
+            return r
+
+    #: Defines the no-op authentication provider.
+    _noop_auth: ClassVar[_NullAuth] = _NullAuth()
+
+    #: Defines success status codes for each HTTP method.
+    _successmap: ClassVar[Dict[RMethod, Set[int]]] = {
+        "GET": {200},
+        "POST": {200, 201, 202},
+        "PUT": {200, 201, 202},
+        "PATCH": {200, 201, 202},
+        "DELETE": {200, 201, 202, 204},
+    }
+
+    def __post_init__(self) -> None:
+        """
+        Sanitizes the base API URL.
+
+        >>> client = Client("http://example.com///", Authorization())
+        >>> client.url
+        'http://example.com'
+        >>> client = Client("http://example.com/api//", Authorization())
+        >>> client.url
+        'http://example.com/api'
+        """
+        object.__setattr__(self, "url", re.sub(r"[/]+$", "", self.url))
+
+    def urlize(self, path: RPath) -> str:
+        """
+        Builds the full URL for the given relative path or path segments.
+
+        :param path: Relative path or path segments of the remote API endpoint.
+        :return: Remote endpoint URL.
+
+        >>> client = Client("http://example.com///", Authorization())
+        >>> client.urlize("test")
+        'http://example.com/test/'
+        >>> client.urlize("test/")
+        'http://example.com/test/'
+        >>> client.urlize("/test")
+        'http://example.com/test/'
+        >>> client.urlize("/test/")
+        'http://example.com/test/'
+        >>> client.urlize("test//")
+        'http://example.com/test/'
+        >>> client.urlize("//test")
+        'http://example.com/test/'
+        >>> client.urlize("//test//")
+        'http://example.com/test/'
+        >>> client.urlize(["test"])
+        'http://example.com/test/'
+        >>> client.urlize(["test/"])
+        'http://example.com/test/'
+        >>> client.urlize(["/test"])
+        'http://example.com/test/'
+        >>> client.urlize(["/test/"])
+        'http://example.com/test/'
+        >>> client.urlize(["test//"])
+        'http://example.com/test/'
+        >>> client.urlize(["//test"])
+        'http://example.com/test/'
+        >>> client.urlize(["//test//"])
+        'http://example.com/test/'
+        >>> client.urlize(["//test//", "//test2//", "//test3/4/5//"])
+        'http://example.com/test/test2/test3/4/5/'
+        """
+        if isinstance(path, list):
+            path = "/".join(str(i).strip("/") for i in path)
+        return urljoin(self.url + "/", re.sub(r"[/]*$", "/", re.sub(r"^[/]*", "", path)))
+
+    def run(self, request: Request) -> requests.Response:
+        """
+        Runs the given request and returns the raw response.
+
+        :param request: :py:class:`Request` instance to run.
+        :return: Raw :py:class:`requests.Response` instance.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        """
+        try:
+            return requests.request(
+                method=request.method,
+                url=self.urlize(request.path),
+                params=request.params,
+                data=request.data,
+                json=request.json,
+                files=request.files,  # type: ignore
+                headers={**(request.headers or {}), **self.auth.headers()},
+                timeout=request.timeout,
+                auth=self._noop_auth,
+            )
+        except requests.exceptions.HTTPError as err:
+            raise APIClientError("HTTP Error", err)
+        except requests.exceptions.Timeout as err:
+            raise APIClientError("Timeout Error", err)
+        except requests.exceptions.ConnectionError as err:
+            raise APIClientError("Connection Error", err)
+        except requests.exceptions.RequestException as err:
+            raise APIClientError("Request Error", err)
+
+    def request(
+        self,
+        method: RMethod,
+        path: RPath,
+        params: Optional[RParams] = None,
+        data: Any = None,
+        json: Any = None,
+        files: Optional[RFiles] = None,
+        headers: Optional[RHeaders] = None,
+        timeout: Optional[RTimeout] = None,
+        asis: bool = False,
+    ) -> Any:
+        """
+        Provides a high-level interface to run HTTP request to the remote API server.
+
+        :param method: Request method.
+        :param path: Relative path or path segments for the remote API endpoint URL.
+        :param params: Request parameters, if any.
+        :param data: Request data payload, if any.
+        :param json: Request data payload in JSON, if any (convenience for sending ``application/json`` payloads).
+        :param files: Request data payload files, if any (convenience for uploading multipart payloads).
+        :param headers: Request headers.
+        :param timeout: Defines the timeout, if any.
+        :param asis: Whether to return response content as is or marshall it to Python object (default is ``False``).
+        :return: Raw response content or Python object as per ``asis`` parameter.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        :raises APIServerError: In case that there is a server generated error reported via HTTP status codes.
+        """
+        ## Build the request, attempt to run it and get a response:
+        response = self.run(
+            Request(
+                method=method,
+                path=path,
+                params=params,
+                data=data,
+                json=json,
+                files=files,
+                headers=headers,
+                timeout=timeout,
+            )
+        )
+
+        ## Check the status code and return if successful:
+        if response.status_code in self._successmap[method]:
+            if not response.content:
+                return None
+            return response.content if asis else response.json()
+
+        ## We have a remote error. Encode it into an exception and raise it:
+        if response.status_code >= 500:
+            raise APIServerErrorBlowup("Server error", response.status_code, response.content)
+        elif response.status_code == 404:
+            raise APIServerErrorNotFound("Resource not found", response.status_code, response.content)
+        elif response.status_code == 400:
+            raise APIServerErrorBadRequest("Bad request", response.status_code, response.content, response.json())
+        elif response.status_code in {401, 403, 405}:
+            raise APIServerErrorBadAuthorization("Bad authorization", response.status_code, response.content)
+        else:
+            raise APIServerError("Unknown error", response.status_code, response.content)
+
+    @property
+    def version(self) -> str:
+        """
+        Returns the remote API version.
+        """
+        return self.request("GET", "version")["version"]  # type: ignore
+
+    @property
+    def healthcheck(self) -> str:
+        """
+        Performs an async healthcheck.
+        """
+        ## Create a healthcheck job and get its ID:
+        jobid = self.request("GET", ["jobs", "healthcheck", "status"])["id"]
+
+        ## Get job result:
+        finished, result = self.get_job_result(jobid)
+
+        ## Check:
+        while not finished:
+            ## Sleep a while:
+            time.sleep(1)
+
+            ## Get job result:
+            finished, result = self.get_job_result(jobid)
+
+        ## Done, return:
+        return result  # type: ignore
+
+    def get_job_result(self, jobid: str) -> Tuple[bool, Optional[Any]]:
+        """
+        Returns if the job is finished and associated data if so.
+
+        :param jobid: Job identifier.
+        :return: A tuple of status (``False`` meaning "pending", ``True`` meaning "finished") and optional content.
+        :raises APIServerError: In case that the status is unknown.
+        """
+        ## Get the job status:
+        content = self.request("GET", ["jobs", jobid])
+
+        ## Get the state:
+        state = content["state"]
+
+        ## Check:
+        if state == "PENDING":
+            return False, None
+        elif state == "SUCCESS":
+            return True, content["result"]
+        else:
+            raise APIServerError("Unknown response from Job status endpoint", -1, content)
+
+    @classmethod
+    def from_profile(cls, name: str, path: Optional[Path] = None) -> "Client":
+        """
+        Attempts the create a :py:class:`Client` instance for the given profile name.
+
+        :param name: Profile name.
+        :param path: Optional path to the configuration file (default is ``~/.decaf.json``).
+        :return: A :py:class:`Client` instance.
+        :raises FileNotFoundError: In case that the configuration file is not found.
+        :raises KeyError: In case that the profile is not found.
+        """
+        ## If we don't have a configuration path, use the default:
+        if path is None:
+            path = Path.home() / ".decaf.json"
+
+        ## Attempt to read in the configuration:
+        with path.open() as ifile:
+            profile = {p["name"]: p for p in loadjson(ifile)["profiles"]}[name]
+
+        ## Build the client and return:
+        return Client(profile["url"], APIKeyAuthorization(key=profile["key"], scr=profile["secret"]))
+
+    @classmethod
+    def from_apikey(cls, url: str, key: str, secret: str) -> "Client":
+        """
+        Attempts the create a :py:class:`Client` instance for the given API key/secret.
+
+        :param url: Base API url.
+        :param key: API key.
+        :param secret: API secret.
+        :return: A :py:class:`Client` instance.
+        """
+        return Client(url, APIKeyAuthorization(key, secret))
+
+    @classmethod
+    def from_apitoken(cls, url: str, token: str) -> "Client":
+        """
+        Attempts the create a :py:class:`Client` instance for the given API token.
+
+        Note that API tokens have shorter expiry than API keys. You may wish to choose API keys for clients with
+        longer life time.
+
+        :param url: Base API url.
+        :param token: API token.
+        :return: A :py:class:`Client` instance.
+        """
+        return Client(url, APITokenAuthorization(token))
+
+    @classmethod
+    def from_headers(cls, url: str, headers: RHeaders) -> "Client":
+        """
+        Attempts the create a :py:class:`Client` instance for the given HTTP headers.
+
+        :param url: Base API url.
+        :param headers: HTTP authentication headers.
+        :return: A :py:class:`Client` instance.
+        """
+        return Client(url, APIHeaderAuthorization(headers))
+
+
+#: Defines a generic type alias.
+_T = TypeVar("_T")
+
+
+def query(func: Callable[..., _T]) -> Callable[..., _T]:
+    """
+    Decorates a query method of an endpoint.
+
+    :param func: method to be decorated.
+    :return: Decorated method.
+    """
+    setattr(func, "__decaf_endpoint_method_query__", True)
+    return func
+
+
+def command(func: Callable[..., _T]) -> Callable[..., _T]:
+    """
+    Decorates a command method of an endpoint.
+
+    :param func: method to be decorated.
+    :return: Decorated method.
+    """
+    setattr(func, "__decaf_endpoint_method_command__", True)
+    return func
+
+
+class BaseResource(BaseModel):
+    """
+    Provides a base class for standard DECAF resource models.
+    """
+
+    pass
+
+
+class BaseCreateForm(BaseModel):
+    """
+    Provides a base class for standard DECAF form models for resource creation.
+    """
+
+    pass
+
+
+class BaseUpdateForm(BaseModel):
+    """
+    Provides a base class for standard DECAF form models for resource updation.
+    """
+
+    pass
+
+
+class BasePatchForm(BaseModel):
+    """
+    Provides a base class for standard DECAF form models for resource patching.
+    """
+
+    pass
+
+
+#: Defines a type variable for :py:class:`BaseResource` implementations.
+_R = TypeVar("_R", bound=BaseResource)
+
+#: Defines a type variable for :py:class:`BaseCreateForm` implementations.
+_C = TypeVar("_C", bound=BaseCreateForm)
+
+#: Defines a type variable for :py:class:`BaseUpdateForm` implementations.
+_U = TypeVar("_U", bound=BaseUpdateForm)
+
+#: Defines a type variable for :py:class:`BasePatchForm` implementations.
+_P = TypeVar("_P", bound=BasePatchForm)
+
+#: Defines a type variable for resource identifiers.
+_I = TypeVar("_I", bound=Union[str, int])
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    """
+    Provides a base endpoint class.
+    """
+
+    __slots__ = ["client"]
+
+    #: Underlying client.
+    client: Client
+
+    #: Base path segment for the remote resource URI.
+    endpoint: ClassVar[str]
+
+
+class ResourceEndpoint(Generic[_R], Endpoint):
+    """
+    Provides a base class for resource endpoints.
+    """
+
+    #: Resource model type.
+    resource: ClassVar[Type[_R]]  # type: ignore
+
+
+class ResourceListEndpoint(ResourceEndpoint[_R]):
+    """
+    Provides a base class for resource endpoints with ``list`` query method.
+    """
+
+    @query
+    def list(self, params: Optional[RParams] = None) -> Iterable[_R]:
+        """
+        Lists resources.
+
+        :param params: Query parameters.
+        :return: An iterable of resources.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        :raises APIServerError: In case that there is a server generated error reported via HTTP status codes.
+        """
+        return (
+            self.resource(**i)
+            for i in self.client.request("GET", self.endpoint, params={**(params or {}), "page_size": "-1"})
+        )
+
+
+class ResourceRetrieveEndpoint(Generic[_I, _R], ResourceEndpoint[_R]):
+    """
+    Provides a base class for resource endpoints with ``retrieve`` query method.
+    """
+
+    @query
+    def retrieve(self, ident: _I) -> Optional[_R]:
+        """
+        Attempts to retrieve the resource identified by the given identifier.
+
+        :param ident: Resource identifier.
+        :return: Resource if found, ``None`` otherwise.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        :raises APIServerError: In case that there is a server generated error reported via HTTP status codes.
+        """
+        try:
+            return self.resource(**self.client.request("GET", [self.endpoint, ident]))
+        except APIServerErrorNotFound:
+            return None
+
+
+class ResourceCreateEndpoint(Generic[_C, _R], ResourceEndpoint[_R]):
+    """
+    Provides a base class for resource endpoints with ``create`` command method.
+    """
+
+    @command
+    def create(self, form: _C) -> _R:
+        """
+        Attempts to create a new resource with the given form data.
+
+        :param form: Resource create form instance.
+        :return: Resource if successfully created.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        :raises APIServerError: In case that there is a server generated error reported via HTTP status codes.
+        """
+        return self.resource(**self.client.request("POST", self.endpoint, json=_form_payload(form)))
+
+
+class ResourceUpdateEndpoint(Generic[_I, _U, _R], ResourceEndpoint[_R]):
+    """
+    Provides a base class for resource endpoints with ``update`` command method.
+    """
+
+    @command
+    def update(self, ident: _I, form: _U) -> _R:
+        """
+        Attempts to update an existing resource with the given form data.
+
+        :param ident: Identifier of the resource to update.
+        :param form: Resource update form instance.
+        :return: Resource if successfully updated.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        :raises APIServerError: In case that there is a server generated error reported via HTTP status codes.
+        """
+        return self.resource(**self.client.request("PUT", [self.endpoint, ident], json=_form_payload(form)))
+
+
+class ResourcePatchEndpoint(Generic[_I, _P, _R], ResourceEndpoint[_R]):
+    """
+    Provides a base class for resource endpoints with ``patch`` command method.
+    """
+
+    @command
+    def patch(self, ident: _I, form: _P) -> _R:
+        """
+        Attempts to patch an existing resource with the given form data.
+
+        :param ident: Identifier of the resource to patch.
+        :param form: Resource patch form instance.
+        :return: Resource if successfully patched.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        :raises APIServerError: In case that there is a server generated error reported via HTTP status codes.
+        """
+        return self.resource(**self.client.request("PATCH", [self.endpoint, ident], json=_form_payload(form)))
+
+
+class DeleteEndpoint(Generic[_I], Endpoint):
+    """
+    Provides a base class for resource endpoints with ``delete`` command method.
+    """
+
+    @command
+    def delete(self, ident: _I) -> None:
+        """
+        Attempts to delete the resource identified by the given identifier.
+
+        :param ident: Identifier of the resource to delete.
+        :raises APIClientError: In case that there is a problem with client-server communication.
+        :raises APIServerError: In case that there is a server generated error reported via HTTP status codes.
+        """
+        self.client.request("DELETE", [self.endpoint, ident])
+
+
+class StandardResourceEndpoint(
+    Generic[_I, _C, _U, _P, _R],
+    ResourceListEndpoint[_R],
+    ResourceRetrieveEndpoint[_I, _R],
+    ResourceCreateEndpoint[_C, _R],
+    ResourceUpdateEndpoint[_I, _U, _R],
+    ResourcePatchEndpoint[_I, _P, _R],
+    DeleteEndpoint[_I],
+    ResourceEndpoint[_R],
+):
+    """
+    Provides a generic base endpoint class definition for standard resources with listing, retrieval, creation,
+    updation, patching and deletion queries/commands.
+    """
+
+    pass
+
+
+def _form_payload(form: Union[BaseCreateForm, BaseUpdateForm, BasePatchForm]) -> Dict[str, Any]:
+    """
+    Compiles HTTP payload from the given form instance.
+
+    This function omits missing values.
+
+    :param form: Form instance.
+    :return: A dictionary of form field name and corresponding value.
+    """
+    return {k: v for k, v in form if not isinstance(v, Missing)}
+
+
+class Missing:
+    """
+    Provides a placeholder value for missing field values.
+    """
+
+    @classmethod
+    def field(cls) -> Any:
+        """
+        Provides a convenience method for creating a ``pydantic`` field for fields defaulting to missing value.
+
+        :return: :py:class:`Field` with missing value as default.
+        """
+        return Field(cls())
+
+    @classmethod
+    def __get_validators__(cls) -> Generator[Any, None, None]:
+        """
+        Makes this class a first class ``pydantic`` field value class.
+
+        :return: Validators.
+        """
+        yield cls.validate
+
+    @staticmethod
+    def validate(v: Any) -> "Missing":
+        """
+        Checks if the given value is a :py:class:`Missing` instance and returns it as is if so.
+
+        :param v: Value to be checked.
+        :return: Value.
+        :raises TypeError: In case that the given value is not a :py:class:`Missing` instance.
+        """
+        if isinstance(v, Missing):
+            return v
+        raise TypeError("'Missing' instance required")

decaf/api/client/types.py

@@ -0,0 +1,150 @@
+"""
+This module provides common type definitions along with a comprehensive resource identifier catalogue.
+"""
+
+__all__ = [
+    "AccountId",
+    "AccountMngtFeeSchemeId",
+    "AccrualScheduleId",
+    "ActionId",
+    "ActionTypeId",
+    "AgentId",
+    "AnalyticalTypeId",
+    "ArtifactId",
+    "ArtifactTypeId",
+    "AssetClassId",
+    "ContainerType",
+    "CountryId",
+    "Currency",
+    "Date",
+    "DateTime",
+    "DateType",
+    "GUID",
+    "GroupId",
+    "InstitutionId",
+    "OHLCId",
+    "PortfolioGroupId",
+    "PortfolioId",
+    "QuantId",
+    "RiskProfileId",
+    "ShareClassId",
+    "SharingId",
+    "StrategyId",
+    "Tags",
+    "TeamId",
+    "TimeDelta",
+    "UserId",
+    "_LaterI",
+    "_LaterS",
+]
+
+from datetime import date as Date
+from datetime import datetime as DateTime
+from datetime import timedelta as TimeDelta
+from enum import Enum
+from typing import NewType, Set
+
+#: Defines a type alias for globally unique resource identifiers.
+GUID = NewType("GUID", str)
+
+#: Defines a new-type for currency codes.
+Currency = NewType("Currency", str)
+
+#: Defines a type alias for standard set of tags.
+Tags = Set[str]
+
+#: Defines a new-type for DECAF quant resource identifier.
+QuantId = NewType("QuantId", int)
+
+#: Defines a new-type for DECAF artifact resource identifier.
+ArtifactId = NewType("ArtifactId", int)
+
+#: Defines a new-type for DECAF artifact type resource identifier.
+ArtifactTypeId = NewType("ArtifactTypeId", str)
+
+#: Defines a new-type for DECAF action resource identifier.
+ActionId = NewType("ActionId", int)
+
+#: Defines a new-type for DECAF action type resource identifier.
+ActionTypeId = NewType("ActionTypeId", int)
+
+#: Defines a new-type for DECAF account resource identifier.
+AccountId = NewType("AccountId", int)
+
+#: Defines a new-type for DECAF agent resource identifier.
+AgentId = NewType("AgentId", int)
+
+#: Defines a new-type for DECAF institution resource identifier.
+InstitutionId = NewType("InstitutionId", int)
+
+#: Defines a new-type for DECAF strategy resource identifier.
+StrategyId = NewType("StrategyId", int)
+
+#: Defines a new-type for DECAF risk profile resource identifier.
+RiskProfileId = NewType("RiskProfileId", int)
+
+#: Defines a new-type for DECAF asset class resource identifier.
+AssetClassId = NewType("AssetClassId", int)
+
+#: Defines a new-type for DECAF portfolio resource identifier.
+PortfolioId = NewType("PortfolioId", int)
+
+#: Defines a new-type for DECAF account management fee scheme resource identifier.
+AccountMngtFeeSchemeId = NewType("AccountMngtFeeSchemeId", int)
+
+#: Defines a new-type for DECAF analytical type resource identifier.
+AnalyticalTypeId = NewType("AnalyticalTypeId", int)
+
+#: Defines a new-type for DECAF institution sharing resource identifier.
+SharingId = NewType("SharingId", int)
+
+#: Defines a new-type for DECAF user resource identifier.
+UserId = NewType("UserId", int)
+
+#: Defines a new-type for DECAF team resource identifier.
+TeamId = NewType("TeamId", int)
+
+#: Defines a new-type for DECAF group resource identifier.
+GroupId = NewType("GroupId", int)
+
+#: Defines a new-type for DECAF portfolio group resource identifier.
+PortfolioGroupId = NewType("PortfolioGroupId", int)
+
+#: Defines a new-type for DECAF country resource identifier.
+CountryId = NewType("CountryId", str)
+
+#: Defines a new-type for DECAF OHLC series resource identifier.
+OHLCId = NewType("OHLCId", int)
+
+#: Defines a new-type for DECAF share class resource identifier.
+ShareClassId = NewType("ShareClassId", int)
+
+#: Defines a new-type for DECAF accrual schedule resource identifier.
+AccrualScheduleId = NewType("AccrualScheduleId", int)
+
+#: Defines a new-type for DECAF resource identifiers which are yet to be declared (of :py:class:`int` type).
+_LaterI = NewType("_LaterI", int)
+
+#: Defines a new-type for DECAF resource identifiers which are yet to be declared (of :py:class:`str` type).
+_LaterS = NewType("_LaterS", str)
+
+
+class ContainerType(Enum):
+    """
+    Provides container types.
+    """
+
+    Account = "account"
+    Portfolio = "portfolio"
+    Institution = "institution"
+    Team = "team"
+    PortfolioGroup = "portfoliogroup"
+
+
+class DateType(Enum):
+    """
+    Provides date types.
+    """
+
+    Commitment = "commitment"
+    Settlement = "settlement"

decaf/api/client/utils.py

@@ -0,0 +1,201 @@
+"""
+This module provides data, type and function definitions which could be useful on import-side. Some of there are used
+internally in this library, too.
+"""
+
+__all__ = [
+    "WithId",
+    "identity",
+    "make_lookup_table",
+    "parse_isodate",
+    "percentify",
+    "remove_microseconds",
+    "skipnone",
+    "sort_and_group_by",
+]
+
+from decimal import Decimal
+from itertools import groupby
+from typing import Callable, Dict, Iterable, Optional, Protocol, Tuple, TypeVar, Union
+
+from .types import Date, DateTime
+
+#: Defines a generic type alias.
+_T = TypeVar("_T")
+
+
+def identity(x: _T) -> _T:
+    """
+    Provides an identity function.
+
+    Return value type is inferred the same as the parameter type.
+
+    :param x: Value.
+    :return: Value.
+
+    >>> identity(1)
+    1
+    >>> identity("value")
+    'value'
+    """
+    return x
+
+
+def skipnone(func: Callable[[_T], _T]) -> Callable[[Optional[_T]], Optional[_T]]:
+    """
+    Provides a function decorator for avoiding function application if the value is ``None``.
+
+    :param func: Function to decorate.
+    :return: Decorated function
+
+    >>> add1: Callable[[int], int] = lambda x: x + 1
+    >>> add1(1)
+    2
+    >>> add1(None)
+    Traceback (most recent call last):
+    ...
+    TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'
+    >>> skipnone(add1)(1)
+    2
+    >>> skipnone(add1)(None)
+    >>>
+
+    You can define a new function using the decorator (note the function signature):
+
+    >>> safe_add1: Callable[[Optional[int]], Optional[int]] = skipnone(add1)
+    >>> safe_add1(1)
+    2
+    >>> safe_add1(None)
+    >>>
+
+    ... or decorate functions as such:
+
+    >>> @skipnone
+    ... def double(x: int) -> int:
+    ...     return x * 2
+    >>> double(1)
+    2
+    >>> double(None)
+    >>>
+    """
+    return lambda x: x if x is None else func(x)
+
+
+def remove_microseconds(x: DateTime) -> DateTime:
+    """
+    Removes microseconds from the given :py:class:`datetime.datetime` instance.
+
+    :param x: :py:class:`datetime.datetime` instance
+    :return: A new :py:class:`datetime.datetime` instance with microseconds set to ``0``.
+
+    >>> DateTime(2019, 1, 2, 3, 4, 5, 6789)
+    datetime.datetime(2019, 1, 2, 3, 4, 5, 6789)
+    >>> remove_microseconds(DateTime(2019, 1, 2, 3, 4, 5, 6789))
+    datetime.datetime(2019, 1, 2, 3, 4, 5)
+    """
+    return x.replace(microsecond=0)
+
+
+def percentify(x: Union[float, int, str, Decimal]) -> Decimal:
+    """
+    Consumes a value representing a number and returns its percentage points as a :py:class:`Decimal` instance.
+
+    :param x: A value representing a number.
+    :return: Percentage points as a :py:class:`Decimal` instance.
+    :raises decimal.InvalidOperation: In case that parameter can not be converted to valid :py:class:`Decimal` instance.
+
+    >>> percentify(0.01)
+    Decimal('1.00')
+    >>> percentify(0)
+    Decimal('0')
+    >>> percentify("0.01")
+    Decimal('1.00')
+    >>> percentify(Decimal("0.01"))
+    Decimal('1.00')
+    >>> percentify(1.0)
+    Decimal('100.0')
+    >>> percentify(1)
+    Decimal('100')
+    >>> percentify("1")
+    Decimal('100')
+    >>> percentify(Decimal(1))
+    Decimal('100')
+    >>> percentify("xyz")
+    Traceback (most recent call last):
+    ...
+    decimal.InvalidOperation: [<class 'decimal.ConversionSyntax'>]
+    """
+    return Decimal(str(x)) * Decimal(100)
+
+
+def parse_isodate(x: str) -> Date:
+    """
+    Attempts to parse an ISO formatted date string and returns it as a :py:class:`datetime.date` instance.
+
+    :param x: ISO formatted date string
+    :return: A :py:class:`datetime.date` instance, if parsing is successful.
+    :raises ValueError: If the parameter does not represent a valid date or is not formatted as a valid ISO date string.
+
+    >>> parse_isodate("2019-01-02")
+    datetime.date(2019, 1, 2)
+    >>> parse_isodate("2019-02-29")
+    Traceback (most recent call last):
+    ...
+    ValueError: day is out of range for month
+    >>> parse_isodate("20190228")
+    Traceback (most recent call last):
+    ...
+    ValueError: time data '20190228' does not match format '%Y-%m-%d'
+    """
+    return DateTime.strptime(x, "%Y-%m-%d").date()
+
+
+class WithId(Protocol[_T]):
+    """
+    Provides a generic protocol for models with ``id`` attribute.
+    """
+
+    #: Unique identifier of the instance.
+    id: _T
+
+
+def make_lookup_table(records: Iterable[WithId[_T]]) -> Dict[_T, WithId[_T]]:
+    """
+    Creates a lookup table from a iterable of records following :py:class:`WithId` protocol.
+
+    :param records: Iterable of records.
+    :return: A lookup table of record id to record.
+
+    >>> make_lookup_table([])
+    {}
+    >>> from dataclasses import dataclass
+    >>> @dataclass
+    ... class A:
+    ...     id: int
+    ...     value: bool
+    >>> records = [A(1, True), A(2, False)]
+    >>> table = make_lookup_table(records)
+    >>> table[1].value
+    True
+    >>> table[2].value
+    False
+    """
+    return {r.id: r for r in records}
+
+
+#: Defines a generic type alias.
+_K = TypeVar("_K")
+
+#: Defines a generic type alias.
+_V = TypeVar("_V")
+
+
+def sort_and_group_by(x: Iterable[_V], key: Callable[[_V], _K]) -> Iterable[Tuple[_K, Iterable[_V]]]:
+    """
+    Sorts and groups an iterable of values by the same key.
+
+    :param x: Iterable of values.
+    :param key: Function to compute the key from a given value.
+    :return: An iterable of tuples of key and iterable of values for the key.
+    """
+    return groupby(sorted(x, key=key), key=key)  # type: ignore

decaf_api_client-0.0.12.dist-info/LICENSE

@@ -0,0 +1,29 @@
+Copyright (2017-2019) Vehbi Sinan Tunalioglu.
+Copyright (2019-2024) Teloscube Pte Ltd.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

decaf_api_client-0.0.12.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.1
+Name: decaf-api-client
+Version: 0.0.12
+Summary: DECAF API Client
+Author-email: Vehbi Sinan Tunalioglu <vst@vsthost.com>
+Maintainer-email: Vehbi Sinan Tunalioglu <vst@vsthost.com>
+License: Copyright (2017-2019) Vehbi Sinan Tunalioglu.
+        Copyright (2019-2024) Teloscube Pte Ltd.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are
+        met:
+        
+        1. Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright
+        notice, this list of conditions and the following disclaimer in the
+        documentation and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+        contributors may be used to endorse or promote products derived from
+        this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+        A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+        HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+        LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+        THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: homepage, https://github.com/telostat/decaf-api-client-python
+Project-URL: documentation, https://github.com/telostat/decaf-api-client-python
+Project-URL: repository, https://github.com/telostat/decaf-api-client-python
+Project-URL: changelog, https://github.com/teloscube/decaf-client-python/blob/main/CHANGELOG.md
+Keywords: decaf,api,client,finance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic <3,>=2
+Requires-Dist: requests <3,>=2
+Provides-Extra: dev
+Requires-Dist: build ; extra == 'dev'
+Requires-Dist: ipython ; extra == 'dev'
+Requires-Dist: pip ; extra == 'dev'
+Requires-Dist: pyls-flake8 ; extra == 'dev'
+Requires-Dist: pyls-isort ; extra == 'dev'
+Requires-Dist: pylsp-mypy ; extra == 'dev'
+Requires-Dist: pylsp-rope ; extra == 'dev'
+Requires-Dist: python-lsp-black ; extra == 'dev'
+Requires-Dist: python-lsp-server ; extra == 'dev'
+Requires-Dist: rope ; extra == 'dev'
+Requires-Dist: twine ; extra == 'dev'
+Requires-Dist: wheel ; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: black ; extra == 'test'
+Requires-Dist: flake8 ; extra == 'test'
+Requires-Dist: isort ; extra == 'test'
+Requires-Dist: mypy ; extra == 'test'
+Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: types-requests ; extra == 'test'
+
+# DECAF API Client (Python)
+
+[![Test](https://github.com/teloscube/decaf-client-python/actions/workflows/test.yml/badge.svg)](https://github.com/teloscube/decaf-client-python/actions/workflows/test.yml)
+
+> **TODO:** Provide a complete README file.
+
+## Development
+
+A Nix shell is provided for development:
+
+```sh
+nix develop
+```
+
+Build to run tests:
+
+```sh
+nix build
+```
+
+## Build and Publish
+
+Build the source distribution:
+
+```sh
+python -m build --sdist --wheel
+```
+
+Check the distribution(s):
+
+```sh
+twine check dist/*
+```
+
+Upload the distribution:
+
+```sh
+twine upload -s dist/*
+```
+
+## License and Copyrights
+
+This software is licensed under [The 3-Clause BSD License].
+
+<!-- REFERENCES -->
+
+[The 3-Clause BSD License]: https://opensource.org/licenses/BSD-3-Clause

decaf_api_client-0.0.12.dist-info/RECORD

@@ -0,0 +1,11 @@
+decaf/api/client/__init__.py,sha256=WnlLgUAn6tUogLJNIlC1S2OVOLRJEEUFi5ZjJIKYxsA,111
+decaf/api/client/_internal.py,sha256=p6m7MXUCr8SCZK_Lhc1BqO_mK3I7-Mlk0sGFTsPD_Dw,229
+decaf/api/client/machinery.py,sha256=tNIS3bXqrjIAVDiLqC0zMwA4VZFAPYXtdHeGcJjx9iE,25068
+decaf/api/client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+decaf/api/client/types.py,sha256=uur23IO8tNm09m1H6jblMhZk4g7OPHzn7bwnIlhmq6k,4231
+decaf/api/client/utils.py,sha256=DmyuXOMo4wKpigklVjY8vPEXjoErcxjhROI3jfVLmE8,5458
+decaf_api_client-0.0.12.dist-info/LICENSE,sha256=Xs-bwjHHT2CraHEgXAz_amdE2z9nZK-f3YozmxtztEY,1516
+decaf_api_client-0.0.12.dist-info/METADATA,sha256=kvi-zkxOqFAJSu9iuRbXV1NOA9Oucp3LoHe3AW50CDw,4364
+decaf_api_client-0.0.12.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+decaf_api_client-0.0.12.dist-info/top_level.txt,sha256=jBvLsYzSXodl4Brh1J9a99Rp7xluwM7Nelyml6gzdXU,6
+decaf_api_client-0.0.12.dist-info/RECORD,,

decaf_api_client-0.0.12.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

decaf_api_client-0.0.12.dist-info/top_level.txt

@@ -0,0 +1 @@
+decaf