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

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

apytizer/media_types.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/media_types.py
+"""Media types (previously MIME types) and subtypes.
+
+.. _IANA:
+    https://www.iana.org/assignments/media-types/media-types.xhtml
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import enum
+import mimetypes
+import re
+from typing import Optional
+
+
+@enum.unique
+class MediaType(str, enum.Enum):
+    """Implements media types."""
+
+    @property
+    def type(self) -> Optional[str]:
+        """Content type."""
+        match = re.match(r"[a-z]+(?=/)", self._value_)
+        result = match.group(0) if match else None
+        return result
+
+    @property
+    def subtype(self) -> Optional[str]:
+        """Content subtype."""
+        match = re.search(r"(?<=/)[a-z+-]+", self._value_)
+        result = match.group(0) if match else None
+        return result
+
+    @property
+    def extension(self) -> Optional[str]:
+        """File extension."""
+        result = mimetypes.guess_extension(self._value_)
+        return result
+
+    # application
+    APPLICATION_JAVASCRIPT = "application/javascript"
+    APPLICATION_JSON = "application/json"
+    APPLICATION_MANIFEST = "application/manifest+json"
+    APPLICATION_MSWORD = "application/msword"
+    APPLICATION_OCTET_STREAM = "application/octet-stream"
+    APPLICATION_ODA = "application/oda"
+    APPLICATION_PDF = "application/pdf"
+    APPLICATION_PKCS7_MIME = "application/pkcs7-mime"
+    APPLICATION_POSTSCRIPT = "application/postscript"
+    APPLICATION_RTF = "application/rtf"
+    APPLICATION_RTX = "application/rtx"
+    APPLICATION_SQL = "application/sql"
+    APPLICATION_TAR = "application/x-tar"
+    APPLICATION_XML = "application/xml"
+    APPLICATION_ZIP = "application/zip"
+
+    # audio
+    AUDIO_AIFF = "audio/x-aiff"
+    AUDIO_BASIC = "audio/basic"
+    AUDIO_MP4 = "audio/mp4"
+    AUDIO_MPEG = "audio/mpeg"
+    AUDIO_MIDI = "audio/midi"
+    AUDIO_REALAUDIO = "audio/x-pn-realaudio"
+    AUDIO_WAV = "audio/x-wav"
+
+    # image
+    IMAGE_BMP = "image/bmp"
+    IMAGE_GIF = "image/gif"
+    IMAGE_ICON = "image/vnd.microsoft.icon"
+    IMAGE_IEF = "image/ief"
+    IMAGE_JPEG = "image/jpeg"
+    IMAGE_PICT = "image/pict"
+    IMAGE_PNG = "image/png"
+    IMAGE_RGB = "image/x-rgb"
+    IMAGE_SVG = "image/svg+xml"
+    IMAGE_TIFF = "image/tiff"
+
+    # message
+    MESSAGE_PARTIAL = "message/partial"
+    MESSAGE_RFC822 = "message/rfc822"
+
+    # multipart
+    MULTIPART_BYTERANGES = "multipart/byteranges"
+    MULTIPART_ENCRYPTED = "multipart/encrypted"
+    MULTIPART_FORM_DATA = "multipart/form-data"
+    MULTIPART_HEADER_SET = "multipart/header-set"
+    MULTIPART_MULTILINGUAL = "multipart/multilingual"
+    MULTIPART_SIGNED = "multipart/signed"
+
+    # text
+    TEXT_CSS = "text/css"
+    TEXT_CSV = "text/csv"
+    TEXT_DNS = "text/dns"
+    TEXT_HTML = "text/html"
+    TEXT_JAVASCRIPT = "text/javascript"
+    TEXT_MARKDOWN = "text/markdown"
+    TEXT_PLAIN = "text/plain"
+    TEXT_PYTHON = "text/x-python"
+    TEXT_RTF = "text/rtf"
+    TEXT_RTX = "text/rtx"
+    TEXT_SETEXT = "text/x-setext"
+    TEXT_SGML = "text/x-sgml"
+    TEXT_STRINGS = "text/strings"
+    TEXT_TSV = "text/tab-separated-values"
+    TEXT_VCARD = "text/x-vcard"
+    TEXT_XML = "text/xml"
+
+    # video
+    VIDEO_H264 = "video/H264"
+    VIDEO_MP4 = "video/mp4"
+    VIDEO_MPEG = "video/mpeg"
+    VIDEO_MSVIDEO = "video/x-msvideo"
+    VIDEO_QUICKTIME = "video/quicktime"
+    VIDEO_RAW = "video/raw"
+    VIDEO_SGI_MOVIE = "video/x-sgi-movie"
+    VIDEO_WEBM = "video/webm"

apytizer/models/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/models/__init__.py
+
+# Local Imports
+from .abstract_model import *
+from .base_model import *

apytizer/models/abstract_model.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/models/abstract_model.py
+"""Abstract model class interface.
+
+This module defines an abstract model class which provides an interface
+for subclasses to implement.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import abc
+from typing import Any
+from typing import Mapping
+from typing import TYPE_CHECKING
+
+# Local Imports
+if TYPE_CHECKING:
+    from ..managers import AbstractManager
+    from ..states import AbstractState
+
+__all__ = ["AbstractModel"]
+
+
+class AbstractModel(abc.ABC):
+    """Represents an abstract model."""
+
+    @property
+    def manager(self) -> AbstractManager:
+        """Manager for model."""
+        return getattr(self, "__manager__")
+
+    @manager.setter
+    def manager(self, manager: AbstractManager, /) -> None:
+        setattr(self, "__manager__", manager)
+
+    @manager.deleter
+    def manager(self) -> None:
+        delattr(self, "__manager__")
+
+    @abc.abstractmethod
+    def __eq__(self, other: object) -> bool:
+        """Abstract method for determining whether model is equal to another.
+
+        Returns:
+            Whether models are equal.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __hash__(self) -> int:
+        """Abstract method for returning the hash value of a model.
+
+        Returns:
+            Hash value.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __repr__(self) -> str:
+        """Abstract method for returning string representation of model."""
+        raise NotImplementedError
+
+
+class AbstractStatefulModel(AbstractModel):
+    """Class represents an abstract stateful model."""
+
+    @property
+    @abc.abstractmethod
+    def state(self) -> AbstractState:
+        """State."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __contains__(self, other: object) -> bool:
+        """Abstract method for determining whether object in state.
+
+        Returns:
+            Whether object in state.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __getattr__(self, name: str) -> Any:
+        """Abstract method for getting an attribute from state.
+
+        Returns:
+            Value of attribute.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __getitem__(self, name: str) -> Any:
+        """Abstract method for getting an item from state.
+
+        Returns:
+            Value of item.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def update(self, __m: Mapping[str, Any], **kwargs: Any) -> None:
+        """Abstract method for updating state of model."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def rollback(self) -> None:
+        """Abstract method for rolling back changes to state of model."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def save(self) -> None:
+        """Abstract method for saving changes to state of model."""
+        raise NotImplementedError