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

apytizer/endpoints/web_endpoint.py

@@ -0,0 +1,519 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/endpoints/web_endpoint.py
+"""Web Endpoint Class.
+
+This module defines the web endpoint class implementation.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+from collections import ChainMap
+import logging
+from typing import Any
+from typing import Collection
+from typing import Dict
+from typing import MutableMapping
+from typing import Optional
+from typing import Set
+from typing import Union
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin
+
+# Third-Party Imports
+from requests import Response
+
+# Local Imports
+from .abstract_endpoint import AbstractEndpoint
+from ..connections import HttpConnection
+from ..decorators import cache_response
+from ..http_methods import HTTPMethod
+from ..routes import Route
+from .. import errors
+
+if TYPE_CHECKING:
+    from ..apis import WebAPI
+
+__all__ = ["WebEndpoint"]
+
+
+log = logging.getLogger("apytizer")
+
+# Define constants.
+DEFAULT_METHODS = (
+    HTTPMethod.HEAD,
+    HTTPMethod.GET,
+    HTTPMethod.POST,
+    HTTPMethod.PUT,
+    HTTPMethod.PATCH,
+    HTTPMethod.DELETE,
+    HTTPMethod.OPTIONS,
+    HTTPMethod.TRACE,
+)
+
+
+class WebEndpoint(AbstractEndpoint):
+    """Implements an endpoint for web APIs.
+
+    Args:
+        __api: API instance.
+        path: Relative path to endpoint.
+        methods (optional): List of HTTP methods accepted by endpoint.
+        headers (optional): Headers to set globally for endpoint.
+        params (optional): Parameters to set globally for endpoint.
+        cache (optional): Mutable mapping for caching responses.
+
+    Attributes:
+        connection: Connection with which to make requests.
+
+    """
+
+    __slots__ = (
+        "_api",
+        "_path",
+        "_methods",
+        "_headers",
+        "_params",
+        "_cache",
+    )
+
+    def __init__(
+        self,
+        __api: "WebAPI",
+        /,
+        path: Union[int, Route, str],
+        *,
+        methods: Optional[Collection[HTTPMethod]] = DEFAULT_METHODS,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        cache: Optional[MutableMapping[str, Any]] = None,
+    ) -> None:
+        self._api = __api
+        self._path = str(path).strip("/")
+        self._methods: Set[HTTPMethod] = set(methods or [])
+        self._headers = ChainMap(headers or {})
+        self._params = ChainMap(params or {})
+        self._cache = cache
+
+    @property
+    def api(self) -> "WebAPI":
+        """API."""
+        return self._api
+
+    @property
+    def connection(self) -> Optional[HttpConnection]:
+        """Connection with which to make requests."""
+        return self._api.connection
+
+    @property
+    def path(self) -> str:
+        """Endpoint path."""
+        return self._path
+
+    @property
+    def url(self) -> str:
+        """Endpoint URL."""
+        result = urljoin(self.api.url, self.path)
+        return result
+
+    @property
+    def methods(self) -> Set[HTTPMethod]:
+        """Endpoint methods."""
+        return self._methods
+
+    @property
+    def headers(self) -> ChainMap[str, str]:
+        """Headers."""
+        return self._headers
+
+    @property
+    def params(self) -> ChainMap[str, Any]:
+        """Parameters."""
+        return self._params
+
+    @property
+    def cache(self) -> Optional[MutableMapping[str, Any]]:
+        """Cache."""
+        return self._cache
+
+    def __eq__(self, other: object) -> bool:
+        result = (
+            other.path.lower() == self.path.lower()
+            if isinstance(other, WebEndpoint)
+            else False
+        )
+        return result
+
+    def __hash__(self) -> int:
+        return hash(self.path)
+
+    def __repr__(self) -> str:
+        result = f"<{self.__class__.__name__!s} (path={self.path!s})>"
+        return result
+
+    def __str__(self) -> str:
+        return self.path
+
+    def __getitem__(self, path: str) -> WebEndpoint:
+        """Get endpoint.
+
+        Args:
+            path: Relative path of endpoint.
+
+        Returns:
+            Endpoint.
+
+        """
+        route = "/".join([self._path, path])
+        result = self._api[route]
+        return result
+
+    def __truediv__(self, path: str) -> WebEndpoint:
+        """Get endpoint.
+
+        Args:
+            path: Relative path of endpoint.
+
+        Returns:
+            Endpoint.
+
+        """
+        route = "/".join([self._path, path])
+        result = self._api[route]
+        return result
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.HEAD not in self.methods:
+            message = f"HEAD method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.head(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.GET not in self.methods:
+            message = f"GET method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.get(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.POST not in self.methods:
+            message = f"POST method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.post(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.PUT not in self.methods:
+            message = f"PUT method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.put(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.PATCH not in self.methods:
+            message = f"PATCH method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.patch(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.DELETE not in self.methods:
+            message = f"DELETE method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.delete(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.OPTIONS not in self.methods:
+            message = f"OPTIONS method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.options(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response
+
+    @cache_response
+    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 endpoint.
+
+        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.
+            MethodNotAllowed: when HTTP method not allowed on endpoint.
+
+        .. _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)
+
+        if HTTPMethod.TRACE not in self.methods:
+            message = f"TRACE method not allowed at {self.path!s} endpoint"
+            raise errors.MethodNotAllowed(message)
+
+        response = self.connection.trace(
+            self.path,
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        return response

apytizer/engines/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/engines/__init__.py
+
+# Local Imports
+from .abstract_engine import *
+from .http_engine import *

apytizer/engines/abstract_engine.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/engines/abstract_engine.py
+"""Abstract Engine Class.
+
+This module defines an abstract engine 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
+from ..protocols import Protocol
+
+__all__ = ["AbstractEngine"]
+
+
+class AbstractEngine(abc.ABC):
+    """Represents an abstract engine."""
+
+    @property
+    @abc.abstractmethod
+    def protocol(self) -> Optional[Protocol]:
+        """Protocol."""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def url(self) -> str:
+        """Base URL."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def connect(self) -> AbstractConnection:
+        """Establish connection.
+
+        Returns:
+            Connection.
+
+        """
+        raise NotImplementedError