apytizer 0.0.1a0__py3-none-any.whl → 0.0.1b2__py3-none-any.whl

apytizer/engines/http_engine.py

@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/engines/http_engine.py
+"""HTTP Engine Class.
+
+This module defines the HTTP engine class implementation.
+
+"""
+
+# Standard Library Imports
+from collections import ChainMap
+from typing import Any
+from typing import MutableMapping
+from typing import Optional
+from typing import Tuple
+from typing import Type
+from typing import TypeVar
+from typing import Union
+
+# Third-Party Imports
+from requests.auth import AuthBase
+from requests.adapters import HTTPAdapter
+
+# Local Imports
+from .abstract_engine import AbstractEngine
+from ..connections import HttpConnection
+from ..protocols import Protocol
+from ..protocols import get_protocol
+
+__all__ = ["HTTPEngine"]
+
+
+# Custom types:
+T = TypeVar("T")
+
+
+class HTTPEngine(AbstractEngine):
+    """Implements an HTTP engine.
+
+    Args:
+        url: Base URL.
+        adapters (optional): Connection adapters. Default ``None``.
+        auth (optional): Authentication header. default ``None``.
+        cert (optional): Client certificate. Default ``None``.
+        headers (optional): Headers to set globally. Default ``None``.
+        params (optional): Parameters to set globally. Default ``None``.
+        proxies (optional): Protocols mapped to proxy URLs. Default ``None``.
+        stream (optional): Whether to stream response content. Default ``False``.
+        timeout (optional): How long to wait before timing out. Default ``None``.
+        verify (optional): Whether to verify certificate. Default ``True``.
+
+    Raises:
+        TypeError: when URL of type other than `str`.
+
+    """
+
+    _connection_cls: Type[HttpConnection] = HttpConnection
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        adapters: Optional[MutableMapping[Protocol, HTTPAdapter]] = None,
+        auth: Optional[Union[AuthBase, Tuple[str, str]]] = None,
+        cert: Optional[Union[str, Tuple[str, str]]] = None,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        proxies: Optional[MutableMapping[str, str]] = None,
+        stream: Optional[bool] = False,
+        timeout: Optional[Union[float, Tuple[float, float]]] = None,
+        verify: Optional[bool] = True,
+    ) -> None:
+        self._url = standardize_url(url)
+        self._adapters = ChainMap(adapters or {})
+        self._auth = auth
+        self._cert = cert
+        self._headers = ChainMap(headers or {})
+        self._params = ChainMap(params or {})
+        self._proxies = ChainMap(proxies or {})
+        self._stream = stream or False
+        self._timeout = timeout
+        self._verify = verify
+
+    @property
+    def protocol(self) -> Optional[Protocol]:
+        """Protocol."""
+        result = get_protocol(self.url)
+        return result
+
+    @property
+    def url(self) -> str:
+        """Base URL."""
+        return self._url
+
+    @property
+    def adapters(self) -> ChainMap[Protocol, HTTPAdapter]:
+        """Connection adapters."""
+        return self._adapters
+
+    @property
+    def auth(self) -> Optional[Union[AuthBase, Tuple[str, str]]]:
+        """Authentication header."""
+        return self._auth
+
+    @property
+    def cert(self) -> Optional[Union[str, Tuple[str, str]]]:
+        """Certificate."""
+        return self._cert
+
+    @property
+    def headers(self) -> ChainMap[str, str]:
+        """Headers."""
+        return self._headers
+
+    @property
+    def params(self) -> ChainMap[str, Any]:
+        """Parameters."""
+        return self._params
+
+    @property
+    def proxies(self) -> ChainMap[str, str]:
+        """Proxies."""
+        return self._proxies
+
+    @property
+    def stream(self) -> bool:
+        """Whether response content will be streamed."""
+        return self._stream
+
+    @property
+    def timeout(self) -> Optional[Union[float, Tuple[float, float]]]:
+        """How long before request times out."""
+        return self._timeout
+
+    @property
+    def verify(self) -> Optional[Union[float, Tuple[float, float]]]:
+        """Whether certificate is verified."""
+        return self._verify
+
+    def __repr__(self) -> str:
+        return f"Engine({self.url!r})"
+
+    def connect(self) -> HttpConnection:
+        """Establish connection.
+
+        Returns:
+            Connection instance.
+
+        """
+        result = self._connection_cls(self)
+        return result
+
+
+# ----------------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------------
+def standardize_url(__url: Any, /) -> str:
+    """Standardize URL.
+
+    Args:
+        __url: URL.
+
+    Returns:
+        URL.
+
+    """
+    if not isinstance(__url, str):
+        message = f"expected type 'str', got {type(__url)} instead"
+        raise TypeError(message)
+
+    result = __url if __url.endswith("/") else __url + "/"
+    return result

apytizer/errors.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/errors.py
+
+
+class ConnectionError(Exception):
+    """Base class for connection errors."""
+
+
+class ConnectionNotStarted(ConnectionError):
+    """Error raised when connection not started."""
+
+
+class EndpointError(Exception):
+    """Base class for endpoint errors."""
+
+
+class EndpointNotFound(Exception):
+    """Error raised when endpoint not found."""
+
+
+class RequestError(Exception):
+    """Base class for request errors."""
+
+
+class MethodNotAllowed(RequestError):
+    """Error raised when request method not allowed."""
+
+
+class SessionError(Exception):
+    """Base class for session errors."""
+
+
+class SessionNotStarted(SessionError):
+    """Error raised when session not started."""

apytizer/factories/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/factories/__init__.py
+
+# Local Imports
+from .abstract_factory import *

apytizer/factories/abstract_factory.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/factories/abstract_factory.py
+"""Abstract factory class interface.
+
+This module defines an abstract factory class which provides an interface for
+subclasses to implement.
+
+"""
+
+# Standard Library Imports
+import abc
+
+__all__ = ["AbstractFactory"]
+
+
+class AbstractFactory(abc.ABC):
+    """Represents an abstract factory."""

apytizer/http_methods.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/http_methods.py
+
+# Standard Library Imports
+import enum
+from typing import Optional
+
+
+@enum.unique
+class HTTPMethod(str, enum.Enum):
+    """Implements standard HTTP methods."""
+
+    @classmethod
+    def _missing_(cls, value: object) -> Optional[enum.Enum]:
+        result = (
+            HTTPMethod(value.upper())
+            if (
+                isinstance(value, str)
+                and not value.isupper()
+                and value.upper() in HTTPMethod
+            )
+            else None
+        )
+        return result
+
+    CONNECT = "CONNECT"
+    HEAD = "HEAD"
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    PATCH = "PATCH"
+    DELETE = "DELETE"
+    OPTIONS = "OPTIONS"
+    TRACE = "TRACE"

apytizer/managers/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/managers/__init__.py
+"""Managers.
+
+Managers are abstractions around endpoints. Managers act as a bridge between
+their respective endpoints and the repositories and models that rely on them.
+
+"""
+
+# Local Imports
+from .abstract_manager import *
+from .base_manager import *

apytizer/managers/abstract_manager.py

@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/managers/abstract_manager.py
+"""Abstract manager class interface.
+
+This module defines an abstract manager class which provides an interface for
+subclasses to implement. Each of the abstract methods represents a standard
+create, read, update or delete (CRUD) operation.
+
+"""
+
+# Standard Library Imports
+import abc
+from typing import Any
+from typing import TYPE_CHECKING
+
+# Local Imports
+if TYPE_CHECKING:
+    from ..models import AbstractModel
+
+__all__ = ["AbstractManager"]
+
+
+class AbstractManager(abc.ABC):
+    """Represents an abstract model manager."""
+
+    @abc.abstractmethod
+    def create(self, obj: AbstractModel, /) -> None:
+        """Abstract method to create an object.
+
+        This method must call the `post` method on an associated endpoint to
+        create the object.
+
+        Args:
+            obj: Instance of an abstract model subclass.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def read(self, ref: Any, /) -> AbstractModel:
+        """Abstract method to 'read' an object.
+
+        This method must call the `get` method on an associated endpoint to
+        retrieve object data. The response is used to instantiate an instance
+        of the managed object class.
+
+        Args:
+            ref: Reference to object on endpoint.
+
+        Returns:
+            Instance of an abstract model subclass.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def update(self, obj: AbstractModel, /) -> None:
+        """Abstract method to update an object.
+
+        This method must call the `put` method on an associated endpoint to
+        update object data.
+
+        Args:
+            obj: Instance of an abstract model subclass.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def delete(self, obj: AbstractModel, /) -> None:
+        """Abstract method to delete an object.
+
+        This method must call the `delete` method on an associated endpoint
+        to delete the object.
+
+        Args:
+            obj: Instance of an abstract model subclass.
+
+        """
+        raise NotImplementedError

apytizer/managers/base_manager.py

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/managers/base_manager.py
+"""Base manager class.
+
+This module defines a base implementation of a manager class.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import logging
+from typing import Any
+from typing import Type
+from typing import TYPE_CHECKING
+
+# Local Imports
+from .abstract_manager import AbstractManager
+from ..apis import AbstractAPI
+from ..mappers import AbstractMapper
+
+if TYPE_CHECKING:
+    from ..models import AbstractModel
+
+__all__ = ["BaseManager"]
+
+
+# Initialize logger.
+log = logging.getLogger(__name__)
+
+
+class BaseManager(AbstractManager):
+    """Base class from which all manager implementations are derived.
+
+    Args:
+        __api: API instance.
+
+    Raises:
+        TypeError: when argument is not type 'Endpoint'.
+
+    """
+
+    def __new__(
+        cls: Type[BaseManager],
+        __api: AbstractAPI,
+        __mapper: AbstractMapper,
+        /,
+    ) -> BaseManager:
+        if not isinstance(__api, AbstractAPI):  # type: ignore
+            message = f"expected type 'WebAPI', got {type(__api)} instead"
+            raise TypeError(message)
+
+        if not isinstance(__mapper, AbstractMapper):  # type: ignore
+            message = f"expected type 'Mapper', got {type(__mapper)} instead"
+            raise TypeError(message)
+
+        instance = super().__new__(cls)  # type: ignore
+        return instance
+
+    def __init__(
+        self,
+        __api: AbstractAPI,
+        __mapper: AbstractMapper,
+        /,
+    ) -> None:
+        self._api = __api
+        self._mapper = __mapper
+
+    def __repr__(self) -> str:
+        result = "<{cls!s}>".format(cls=self.__class__.__name__)
+        return result
+
+    def create(self, obj: "AbstractModel", /) -> None:
+        """Create an object.
+
+        Args:
+            obj: Object to create.
+
+        """
+        raise NotImplementedError
+
+    def read(self, ref: Any, /) -> "AbstractModel":
+        """Read an object.
+
+        Calls `get` method on associated endpoint to retrieve object data.
+        Uses response to instantiate an instance of the managed object class.
+
+        Args:
+            ref: Reference to object on endpoint.
+
+        Returns:
+            Object instance.
+
+        """
+        raise NotImplementedError
+
+    def update(self, obj: "AbstractModel", /) -> None:
+        """Update an object.
+
+        Calls `put` method on associated endpoint to update object data.
+
+        Args:
+            obj: Object to update.
+
+        """
+        raise NotImplementedError
+
+    def delete(self, obj: "AbstractModel", /) -> None:
+        """Delete an object.
+
+        Calls `delete` method on associated endpoint to delete the object.
+
+        Args:
+            obj: Object to delete.
+
+        """
+        raise NotImplementedError

apytizer/mappers/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/mappers/__init__.py
+"""Mappers."""
+
+# Local Imports
+from .abstract_mapper import *

apytizer/mappers/abstract_mapper.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/mappers/abstract_mapper.py
+"""Abstract mapper class interface.
+
+This module defines an abstract mapper class which provides an interface for
+subclasses to implement.
+
+"""
+
+# Standard Library Imports
+import abc
+from typing import Mapping
+from typing import Type
+from typing import TYPE_CHECKING
+
+# Local Imports
+if TYPE_CHECKING:
+    from ..models import AbstractModel
+    from ..routes import AbstractRoute
+
+__all__ = ["AbstractMapper"]
+
+
+class AbstractMapper(abc.ABC):
+    """Represents an abstract mapper.
+
+    Each mapper is an association between a Python class and an API endpoint,
+    which allows ORM operations against the class.
+
+    """
+
+    @property
+    @abc.abstractmethod
+    def model(self) -> Type["AbstractModel"]:
+        """Model class."""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def route(self) -> "AbstractRoute":
+        """Routes."""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def properties(self) -> Mapping[str, str]:
+        """Properties."""
+        raise NotImplementedError

apytizer/mappers/base_mapper.py

@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/mappers/base_mapper.py
+"""Base Mapper Class.
+
+This module defines the base mapper class implementation.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+from types import MappingProxyType
+from typing import Mapping
+from typing import Type
+
+# Local Imports
+from .abstract_mapper import AbstractMapper
+from ..models import AbstractModel
+from ..routes import AbstractRoute
+
+__all__ = ["Mapper"]
+
+
+class Mapper(AbstractMapper):
+    """Implements a mapper.
+
+    Each mapper is an association between a Python class and an API endpoint,
+    which allows ORM operations against the class.
+
+    """
+
+    def __new__(
+        cls: Type[Mapper],
+        __class: Type[AbstractModel],
+        __route: AbstractRoute,
+        __properties: Mapping[str, str],
+        /,
+    ) -> Mapper:
+        if not issubclass(__class, AbstractModel):  # type: ignore
+            message = f"{__class} is not a subclass of 'AbstractModel'"
+            raise TypeError(message)
+
+        if not isinstance(__route, AbstractRoute):  # type: ignore
+            message = f"expected type 'Route', got {type(__route)} instead"
+            raise TypeError(message)
+
+        if not isinstance(__properties, Mapping):  # type: ignore
+            expected = "expected type 'Mapping'"
+            actual = f"got {type(__properties)} instead"
+            message = ", ".join([expected, actual])
+            raise TypeError(message)
+
+        instance = super().__new__(cls)  # type: ignore
+        return instance
+
+    def __init__(
+        self,
+        __class: Type[AbstractModel],
+        __route: AbstractRoute,
+        __properties: Mapping[str, str],
+    ) -> None:
+        self._class = __class
+        self._route = __route
+        self._properties = MappingProxyType(__properties)
+
+    @property
+    def model(self) -> Type[AbstractModel]:
+        """Model."""
+        raise NotImplementedError
+
+    @property
+    def route(self) -> AbstractRoute:
+        """Route."""
+        raise NotImplementedError
+
+    @property
+    def properties(self) -> Mapping[str, str]:
+        """Properties."""
+        raise NotImplementedError