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

apytizer/connections/http_connection.py

@@ -0,0 +1,431 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/connection/base_connection.py
+"""HTTP Connection Class.
+
+This module defines the base HTTP connection class implementation.
+
+"""
+
+# Standard Library Imports
+from collections import ChainMap
+import logging
+from typing import Any
+from typing import MutableMapping
+from typing import Optional
+from typing import Tuple
+from typing import Union
+from typing import final
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin
+
+# Third-Party Imports
+from requests import Request
+from requests import Response
+
+# Local Imports
+from .abstract_connection import AbstractConnection
+from ..decorators import confirm_connection
+from ..http_methods import HTTPMethod
+from ..sessions import AbstractSession
+from ..sessions import sessionmaker
+from .. import errors
+
+if TYPE_CHECKING:
+    from ..engines import HTTPEngine
+
+__all__ = ["HttpConnection"]
+
+
+log = logging.getLogger("apytizer")
+
+# Constants
+DEFAULT_SESSION_FACTORY = sessionmaker()
+
+
+class HttpConnection(AbstractConnection):
+    """Implements an HTTP connection.
+
+    The connection class provides an interface for interacting with an API.
+    It implements the standard HTTP methods (HEAD, GET, POST, PUT, PATCH,
+    DELETE, OPTIONS and TRACE) as well as a `request` method for sending
+    custom HTTP requests.
+
+    Args:
+        engine: Engine.
+        session_factory (optional): Function for creating sessions.
+
+    """
+
+    def __init__(
+        self,
+        engine: "HTTPEngine",
+        *,
+        session_factory: sessionmaker = DEFAULT_SESSION_FACTORY,
+    ) -> None:
+        self._engine = engine
+        self._session_factory = session_factory
+
+    @property
+    def headers(self) -> ChainMap[str, str]:
+        """Connection headers."""
+        return self._engine.headers
+
+    @property
+    def params(self) -> ChainMap[str, Any]:
+        """Connection parameters."""
+        return self._engine.params
+
+    @property
+    def session(self) -> Optional[AbstractSession]:
+        """Session."""
+        return getattr(self, "_session", None)
+
+    @property
+    def timeout(self) -> Optional[Union[float, Tuple[float, float]]]:
+        """Connection timeout."""
+        return self._engine.timeout
+
+    @property
+    def url(self) -> str:
+        """Connection URL."""
+        return self._engine.url
+
+    @final
+    def __enter__(self) -> AbstractConnection:
+        """Starts connection as context manager."""
+        self.start()
+        return self
+
+    @final
+    def __exit__(self, *_) -> None:
+        """Ends connection as context manager."""
+        self.close()
+
+    def start(self) -> None:
+        """Start connection."""
+        session = self._session_factory(self._engine)
+        setattr(self, "_session", session)
+        session.start()
+
+    def close(self) -> None:
+        """Close connection."""
+        if self.session is not None:
+            self.session.close()
+
+    def head(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP HEAD request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP HEAD Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+
+        """
+        response = self.request(
+            HTTPMethod.HEAD,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def get(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP GET request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP GET Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET
+
+        """
+        response = self.request(
+            HTTPMethod.GET,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def post(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP POST request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP POST Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
+
+        """
+        response = self.request(
+            HTTPMethod.POST,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def put(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP PUT request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP PUT Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT
+
+        """
+        response = self.request(
+            HTTPMethod.PUT,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def patch(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP PATCH request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP PATCH Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH
+
+        """
+        response = self.request(
+            HTTPMethod.PATCH,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def delete(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP DELETE request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP DELETE Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE
+
+        """
+        response = self.request(
+            HTTPMethod.DELETE,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def options(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP OPTIONS request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP OPTIONS Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS
+
+        """
+        response = self.request(
+            HTTPMethod.OPTIONS,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def trace(
+        self,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP TRACE request.
+
+        Args:
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _HTTP TRACE Method:
+            https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE
+
+        """
+        response = self.request(
+            HTTPMethod.TRACE,
+            route,
+            headers=headers,
+            params=params,
+            **kwargs,
+        )
+        return response
+
+    def request(
+        self,
+        method: HTTPMethod,
+        /,
+        route: Optional[str] = None,
+        *,
+        headers: Optional[MutableMapping[str, str]] = None,
+        params: Optional[MutableMapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Optional[Response]:
+        """Sends an HTTP request.
+
+        Args:
+            method: HTTP request method to use.
+            route (optional): Route to which to send request. Default ``None``.
+            headers (optional): Request headers (overrides global headers).
+            params (optional): Request parameters (overrides global parameters).
+            **kwargs: Additional arguments to pass to request.
+
+        Returns:
+            Response object.
+
+        .. _Requests Documentation:
+            https://docs.python-requests.org/en/latest/api/
+
+        """
+        request = Request(
+            method.name,
+            urljoin(self.url, route),
+            headers=self.headers.new_child(headers),
+            params=self.params.new_child(params),
+            **kwargs,
+        )
+        response = self.send(request)
+        return response
+
+    @confirm_connection
+    def send(self, request: Request) -> Optional[Response]:
+        """Sends an HTTP request.
+
+        Args:
+            request: Request to send.
+
+        Returns:
+            Response object.
+
+        """
+        if self.session is None:
+            message = "session not started before sending request"
+            raise errors.SessionNotStarted(message)
+
+        log.debug(
+            "Sending HTTP %(method)s request to %(url)s",
+            {"method": request.method, "url": request.url},
+        )
+        response = self.session.send(request, timeout=self.timeout)
+        log.debug(
+            "Received response with status code %(status)s",
+            {"status": response.status_code},
+        )
+        return response

apytizer/decorators/__init__.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
+# src/apytizer/decorators/__init__.py
 
-# pylint: skip-file
-
-from .connection import confirm_connection
-from .json import json_response
-from .pagination import pagination
+from .caching import *
+from .connection import *
+from .json import *
+from .pagination import *

apytizer/decorators/caching.py

@@ -1,24 +1,28 @@
 # -*- coding: utf-8 -*-
+# src/apytizer/decorators/caching.py
 
 # Standard Library Imports
 import functools
-import logging
 import operator
+from typing import Any
 from typing import Callable
+from typing import TypeVar
 
 # Third-Party Imports
 from cachetools import cachedmethod
 
 # Local Imports
-from ..utils import generate_key
+from ..utils.caching import generate_key
 
+__all__ = ["cache_response"]
 
-log = logging.getLogger(__name__)
 
+# Custom types
+T = TypeVar("T")
 
-def cache_response(func: Callable) -> Callable:
-    """
-    Decorator function for handling caching.
+
+def cache_response(func: Callable[..., T]) -> Callable[..., T]:
+    """Decorator function for handling caching.
 
     Args:
         func: Decorated function.
@@ -27,10 +31,57 @@ def cache_response(func: Callable) -> Callable:
         Wrapped function.
 
     """
+    cached_func = cachedmethod(
+        operator.attrgetter("cache"),
+        key=generate_key(func.__name__.upper()),
+    )(func)
+
     @functools.wraps(func)
-    @cachedmethod(operator.attrgetter('cache'), key=generate_key(func.__name__.upper()))
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Any, **kwargs: Any) -> T:
         """Wrapper applied to decorated function."""
-        return func(*args, **kwargs)
+        try:
+            result = cached_func(*args, **kwargs)
+
+        except TypeError as error:  # raised when cache is 'None'
+            if is_missing_cache(error):
+                result = func(*args, **kwargs)
+
+            else:
+                raise error
 
+        return result
+
+    functools.update_wrapper(wrapper, func)
     return wrapper
+
+
+# ----------------------------------------------------------------------------
+# Validators
+# ----------------------------------------------------------------------------
+def is_missing_cache(e: Exception) -> bool:
+    """Check whether exception was raised because of missing cache.
+
+    Args:
+        e: Exception.
+
+    Returns:
+        Whether exception was raised because of missing cache.
+
+    """
+    expected = "'NoneType' object is not subscriptable"
+    result = is_nonetype_error(e) and expected in str(e)
+    return result
+
+
+def is_nonetype_error(e: Exception) -> bool:
+    """Check whether exception is 'NoneType' error.
+
+    Args:
+        e: Exception.
+
+    Returns:
+        Whether exception wis 'NoneType' error.
+
+    """
+    result = isinstance(e, TypeError) and "NoneType" in str(e)
+    return result

apytizer/decorators/chunking.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/decorators/chunking.py
+
+# Standard Library Imports
+import functools
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import Iterable
+from typing import List
+from typing import Union
+
+# Third-Party Imports
+from requests import Response
+
+# Local Imports
+from .. import utils
+
+__all__ = ["chunked_request"]
+
+
+def chunked_request(
+    max_size: int,
+) -> Callable[..., Callable[..., Union[Dict[str, Any], Response]]]:
+    """Split request payload based on maximum request size.
+
+    Args:
+        max_size: Maximum size of request.
+
+    Returns:
+        Wrapped function.
+
+    """
+
+    def decorator(
+        func: Callable[[Any, List[Any]], Union[Dict[str, Any], Response]],
+    ) -> Callable[..., Union[Dict[str, Any], Response]]:
+        """Decorator function for handling chunking.
+
+        Args:
+            func: Decorated function.
+
+        Returns:
+            Wrapped function.
+
+        """
+
+        @functools.wraps(func)
+        def wrapper(
+            self: Any, data: List[Any], *args: Any, **kwargs: Any
+        ) -> Union[Dict[str, Any], Response]:
+            """Wrapper applied to decorated function.
+
+            Args:
+                data: Data to chunk into multiple requests.
+                *args: Positional arguments to pass to wrapped function.
+                **kwargs: Keyword arguments to pass to wrapped function.
+
+            Returns:
+                Results.
+
+            """
+            if not isinstance(data, Iterable):  # type: ignore
+                message = f"expected iterable object, got {type(data)} instead"
+                raise TypeError(message)
+
+            results = {}
+            for group in utils.split_list(data, max_size):
+                response = func(self, group, *args, **kwargs)
+                results = update_results(results, response)
+
+            return results
+
+        functools.update_wrapper(wrapper, func)
+        return wrapper
+
+    return decorator
+
+
+def update_results(
+    results: Dict[str, List[Any]],
+    response: Union[Dict[str, List[Any]], Response],
+) -> Dict[str, Any]:
+    """Update results with response data.
+
+    Args:
+        results: Results to update.
+        response: Response with which to update results.
+
+    Returns:
+        Updated results.
+
+    """
+    if isinstance(response, Response) and response.ok:
+        return results
+
+    if not isinstance(response, dict):  # type: ignore
+        message = f"expected type `dict`, got {type(response)} instead"
+        raise TypeError(message)
+
+    for key, value in response.items():
+        results.setdefault(key, [])
+        results[key].extend(value)
+
+    return results