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

apytizer/__init__.py

@@ -1,14 +1,4 @@
 # -*- coding: utf-8 -*-
+# src/apytizer/__init__.py
 
-from .adapters import TransportAdapter
-from .base import BasicAPI as API
-from .base import SessionAPI as Session
-from .base import BasicEndpoint as Endpoint
-from .base import BasicModel as Model
-
-
-VERSION = (0, 0, 1, 'alpha', 0)
-
-__version__ = '.'.join(str(v) for v in VERSION[:2])
-
-__release__ = '.'.join(str(v) for v in VERSION)
+__version__ = "0.0.1"

apytizer/adapters/__init__.py

@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
 
-# pylint: skip-file
-
-from .transport import TransportAdapter
+# Local Imports
+from .transport_adapter import *

apytizer/adapters/transport_adapter.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/adapters/transport_adapter.py
+"""Transport Adapter.
+
+This module defines a transport adapter class: an implementation of an
+HTTPAdapter which handles exponential backoff for retrying requests and
+provides default values for rate limiting and timeout.
+
+"""
+
+# Standard Library Imports
+from http import HTTPStatus
+from typing import Any
+from urllib3.util import Retry
+
+# Third-Party Imports
+from requests import PreparedRequest
+from requests import Response
+from requests.adapters import HTTPAdapter
+
+# Local Import
+from ..http_methods import HTTPMethod
+
+__all__ = ["TransportAdapter"]
+
+
+# Constants
+DEFAULT_RATE_LIMIT = 1
+DEFAULT_TIMEOUT = 5
+NUMBER_OF_RETRIES = 10
+
+
+class TransportAdapter(HTTPAdapter):
+    """Implementation of a transport adaptor.
+
+    Transport adapters define methods for interacting with HTTP services,
+    enabling the use of per-service configurations.
+
+    Args:
+        *args: Positional arguments.
+        rate_limit (optional): Rate limit.
+        timeout (optional): Timeout.
+        **kwargs: Keyword arguments.
+
+    """
+
+    def __init__(
+        self,
+        *args: Any,
+        rate_limit: int = DEFAULT_RATE_LIMIT,
+        timeout: int = DEFAULT_TIMEOUT,
+        **kwargs: Any,
+    ) -> None:
+        kwargs.setdefault("max_retries", make_retry(rate_limit))
+        super().__init__(*args, **kwargs)
+        self.timeout = timeout
+
+    def send(
+        self,
+        request: PreparedRequest,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Response:
+        kwargs.setdefault("timeout", self.timeout)
+        return super().send(request, *args, **kwargs)
+
+
+def make_retry(rate_limit: int) -> Retry:
+    """Make retry configuration.
+
+    Args:
+        rate_limit: Rate limit for backoff factor.
+
+    Returns:
+        Retry configuration.
+
+    """
+    result = Retry(
+        total=NUMBER_OF_RETRIES,
+        status_forcelist=[
+            HTTPStatus.REQUEST_ENTITY_TOO_LARGE,
+            HTTPStatus.TOO_MANY_REQUESTS,
+            HTTPStatus.INTERNAL_SERVER_ERROR,
+            HTTPStatus.BAD_GATEWAY,
+            HTTPStatus.SERVICE_UNAVAILABLE,
+            HTTPStatus.GATEWAY_TIMEOUT,
+        ],
+        allowed_methods=[method.name for method in HTTPMethod],
+        backoff_factor=rate_limit,
+    )
+    return result

apytizer/apis/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/apis/__init__.py
+
+# Local Imports
+from .abstract_api import *
+from .web_api import *

apytizer/apis/abstract_api.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/apis/abstract_api.py
+"""Abstract API Class.
+
+This module defines an abstract API class which provides an interface
+for subclasses to implement.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import abc
+from typing import Optional
+
+# Local Imports
+from ..connections import AbstractConnection
+
+__all__ = ["AbstractAPI"]
+
+
+class AbstractAPI(abc.ABC):
+    """Represents an abstract API."""
+
+    @property
+    @abc.abstractmethod
+    def connection(self) -> Optional[AbstractConnection]:
+        """Connection with which to make requests."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __eq__(self, other: object) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __hash__(self) -> int:
+        raise NotImplementedError

apytizer/apis/web_api.py

@@ -0,0 +1,460 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/apis/web_api.py
+"""Web API class.
+
+This module defines the web API class implementation.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+from typing import Any
+from typing import Dict
+from typing import final
+from typing import Optional
+from typing import Type
+
+# Third-Party Imports
+from requests import Response
+
+# Local Imports
+from .abstract_api import AbstractAPI
+from ..connections import HttpConnection
+from ..endpoints import WebEndpoint
+from ..engines import AbstractEngine
+from ..routes import AbstractRoute
+from .. import errors
+
+__all__ = ["WebAPI"]
+
+
+class WebAPI(AbstractAPI):
+    """Implements a web API.
+
+    Args:
+        engine: Engine.
+        endpoints (optional): Endpoints. Default ``None``.
+        locked (optional): Whether to lock endpoints. Default ``False``.
+
+    Raises:
+        TypeError: when `engine` argument is not type ``Engine``.
+        TypeError: when `endpoints` argument is not type ``dict``.
+        TypeError: when `locked` argument is not type ``bool``.
+
+    """
+
+    def __init__(
+        self,
+        engine: AbstractEngine,
+        /,
+        endpoints: Optional[Dict[AbstractRoute, Type[WebEndpoint]]] = None,
+        *,
+        locked: bool = False,
+    ) -> None:
+        if not isinstance(engine, AbstractEngine):  # type: ignore
+            message = f"expected type 'Engine', got {type(engine)} instead"
+            raise TypeError(message)
+
+        if endpoints and not isinstance(endpoints, dict):  # type: ignore
+            message = f"expected type 'dict', got {type(endpoints)} instead"
+            raise TypeError(message)
+
+        if not isinstance(locked, bool):  # type: ignore
+            message = f"expected type 'bool', got {type(locked)} instead"
+            raise TypeError(message)
+
+        self._engine = engine
+        self._endpoints = endpoints.copy() if endpoints else {}
+        self._locked = locked
+
+    @property
+    def connection(self) -> Optional[HttpConnection]:
+        """Connection with which to make requests."""
+        result = getattr(self, "_connection", None)
+        return result
+
+    @property
+    def url(self) -> str:
+        """Base URL."""
+        return self._engine.url
+
+    @final
+    def __enter__(self) -> AbstractAPI:
+        """Starts API as context manager."""
+        self.connect()
+        return self
+
+    @final
+    def __exit__(self, *_) -> None:
+        """Ends API as context manager."""
+        self.close()
+
+    def __eq__(self, other: object) -> bool:
+        result = (
+            other.url.lower() == self.url.lower()
+            if isinstance(other, WebAPI)
+            else False
+        )
+        return result
+
+    def __hash__(self) -> int:
+        result = hash(self.url)
+        return result
+
+    def __repr__(self) -> str:
+        result = f"<{self.__class__.__name__!s} url={self.url!s}>"
+        return result
+
+    def __getitem__(self, path: str) -> WebEndpoint:
+        """Get endpoint.
+
+        Args:
+            path: Relative path of endpoint.
+
+        Returns:
+            Endpoint.
+
+        """
+        result = self.get_endpoint(path)
+        return result
+
+    def __truediv__(self, path: str) -> WebEndpoint:
+        """Get endpoint.
+
+        Args:
+            path: Relative path of endpoint.
+
+        Returns:
+            Endpoint.
+
+        """
+        result = self.get_endpoint(path)
+        return result
+
+    def get_endpoint(self, path: str) -> WebEndpoint:
+        """Get endpoint.
+
+        Arhs:
+            path: Relative path of endpoint.
+
+        Returns:
+            Endpoint.
+
+        """
+        try:
+            matches = sorted(
+                (route, endpoint)
+                for route, endpoint in self._endpoints.items()
+                if route == path
+            )
+            _, endpoint = next(iter(matches))
+
+        except StopIteration:
+            if self._locked is True:
+                message = f"endpoint not found: {path}"
+                raise errors.EndpointNotFound(message)
+
+            endpoint = WebEndpoint
+
+        result = endpoint(self, path)
+        return result
+
+    def connect(self) -> None:
+        """Start connection to web API."""
+        connection = self._engine.connect()
+        setattr(self, "_connection", connection)
+        connection.start()
+
+    def close(self) -> None:
+        """Close connection to web API."""
+        if self.connection is not None:
+            self.connection.close()
+            delattr(self, "_connection")
+
+    @final
+    def head(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP HEAD request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+
+        """
+        if self.connection is None:
+            message = "connection not started before making HEAD request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.head(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    @final
+    def get(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP GET request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET
+
+        """
+        if self.connection is None:
+            message = "connection not started before making GET request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.get(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    @final
+    def post(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP POST request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
+
+        """
+        if self.connection is None:
+            message = "connection not started before making POST request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.post(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    @final
+    def put(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP PUT request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT
+
+        """
+        if self.connection is None:
+            message = "connection not started before making PUT request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.put(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    @final
+    def patch(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP PATCH request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH
+
+        """
+        if self.connection is None:
+            message = "connection not started before making PATCH request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.patch(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    @final
+    def delete(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP DELETE request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE
+
+        """
+        if self.connection is None:
+            message = "connection not started before making DELETE request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.delete(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    @final
+    def options(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP OPTIONS request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS
+
+        """
+        if self.connection is None:
+            message = "connection not started before making OPTIONS request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.options(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    @final
+    def trace(
+        self,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP TRACE request to the API.
+
+        Args:
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Keyword arguments to include in request.
+
+        Returns:
+            Response object.
+
+        Raises:
+            ConnectionNotStarted: when connection not started.
+
+        .. _MDN Web Docs:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE
+
+        """
+        if self.connection is None:
+            message = "connection not started before making TRACE request"
+            raise errors.ConnectionNotStarted(message)
+
+        response = self.connection.trace(
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response

apytizer/connections/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/connections/__init__.py
+
+# Local Imports
+from .abstract_connection import *
+from .http_connection import *

apytizer/connections/abstract_connection.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/connections/abstract_connection.py
+"""Abstract Connection Class.
+
+This module defines an abstract connection class which provides an
+interface for subclasses to implement.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import abc
+
+__all__ = ["AbstractConnection"]
+
+
+class AbstractConnection(abc.ABC):
+    """Represents an abstract connection."""
+
+    @abc.abstractmethod
+    def start(self) -> None:
+        """Start connection."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Close connection."""
+        raise NotImplementedError