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

apytizer/decorators/connection.py

@@ -1,20 +1,28 @@
 # -*- coding: utf-8 -*-
+# src/apytizer/decorators/connection.py
 
 # Standard Library Imports
 import functools
 import logging
+from typing import Any
 from typing import Callable
+from typing import Optional
 
 # Third-Party Imports
-import requests
+from requests import Response
+from requests.exceptions import ConnectionError
+from requests.exceptions import Timeout
 
+__all__ = ["confirm_connection"]
 
-log = logging.getLogger(__name__)
 
+log = logging.getLogger("apytizer")
 
-def confirm_connection(func) -> Callable:
-    """
-    Confirms successful connection to API.
+
+def confirm_connection(
+    func: Callable[..., Optional[Response]],
+) -> Callable[..., Optional[Response]]:
+    """Confirms successful connection to API.
 
     Args:
         func: Function to decorate.
@@ -23,26 +31,53 @@ def confirm_connection(func) -> Callable:
         Wrapped function.
 
     """
+
     @functools.wraps(func)
-    def wrapper(self, *args, **kwargs):
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Optional[Response]:
+        """Wrapper applied to decorated function.
+
+        Args:
+            *args: Positional arguments to pass to wrapped function.
+            **kwargs: Keyword arguments to pass to wrapped function.
+
+        Returns:
+            Response.
+
+        """
         try:
             response = func(self, *args, **kwargs)
 
-        except requests.exceptions.ConnectionError as error:
-            log.critical("Failed to establish a connection")
-            log.debug(f"Error message: {error}")
-            return error
+        except ConnectionError as error:
+            handle_connection_error(error)
+            return error.response
 
-        except requests.exceptions.Timeout as error:
-            log.critical("request timed out")
-            log.debug(f"Error message: {error}")
-            return error
+        except Timeout as error:
+            handle_timeout_error(error)
+            return error.response
 
-        else:
-            log.debug(
-                "Response received with status code %(status)",
-                {'status': response.status_code}
-            )
-            return response
+        return response
 
+    functools.update_wrapper(wrapper, func)
     return wrapper
+
+
+def handle_connection_error(error: ConnectionError) -> None:
+    """Handle connection errors.
+
+    Args:
+        error: Connection error.
+
+    """
+    log.critical("failed to establish a connection")
+    log.error(error)
+
+
+def handle_timeout_error(error: Timeout) -> None:
+    """Handle timeout errors.
+
+    Args:
+        error: Timeout error.
+
+    """
+    log.critical("request timed out")
+    log.error(error)

apytizer/decorators/json_response.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/decorators/json.py
+
+# Standard Library Imports
+import functools
+from http import HTTPStatus
+import json
+import logging
+from typing import Any
+from typing import Callable
+
+# Third-Party Imports
+from requests import Response
+
+# Local Imports
+from ..media_types import MediaType
+
+__all__ = ["json_response"]
+
+
+log = logging.getLogger("apytizer")
+
+# Constants
+CONTENT_TYPE = "Content-Type"
+
+
+def json_response(func: Callable[..., Response]) -> Callable[..., Any]:
+    """Automatically parses a JSON response.
+
+    Args:
+        func: Function to decorate.
+
+    Returns:
+        Wrapped function.
+
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        """Wrapper applied to decorated function.
+
+        Args:
+            *args: Positional arguments to pass to wrapped function.
+            **kwargs: Keyword arguments to pass to wrapped function.
+
+        Returns:
+            Parsed JSON or Response.
+
+        """
+        response: Response = func(*args, **kwargs)
+        if response.status_code == HTTPStatus.NO_CONTENT:
+            return response
+
+        content_type = response.headers.get(CONTENT_TYPE)
+        if not content_type or MediaType.APPLICATION_JSON not in content_type:
+            return response
+
+        result = parse_json_response(response)
+        return result
+
+    functools.update_wrapper(wrapper, func)
+    return wrapper
+
+
+def parse_json_response(response: Response) -> Any:
+    """Parse JSON response.
+
+    Args:
+        response: JSON response.
+
+    Returns:
+        Parsed data.
+
+    """
+    try:
+        log.debug("Parsing JSON response...")
+        result = response.json()
+
+    except json.JSONDecodeError as error:
+        handle_decode_error(error)
+        return response
+
+    return result
+
+
+def handle_decode_error(error: json.JSONDecodeError) -> None:
+    """Handle decode errors.
+
+    Args:
+        error: JSONDecodeError error.
+
+    """
+    log.error(error)

apytizer/decorators/pagination.py

@@ -1,53 +1,71 @@
 # -*- coding: utf-8 -*-
+# src/apytizer/decorators/pagination.py
 
 # Standard Library Imports
 import functools
-import logging
+from typing import Any
 from typing import Callable
+from typing import Dict
+from typing import Generator
+from typing import TypeVar
 
+__all__ = ["pagination"]
 
-log = logging.getLogger(__name__)
 
+# Custom types
+T = TypeVar("T")
 
-def pagination(func) -> Callable:
-    """
-    Args:
-        func: Decorated function.
 
-    Returns:
-        Function wrapper.
+class pagination:
+    """Implements pagination for requests to an API endpoint.
+
+    Args:
+        reducer (Callable): Function to update state from response.
+        callback (Callable): Function which returns 'True' when request is
+            complete, otherwise returns 'False'. Stop condition must depend
+            on either state or response.
 
     """
-    @functools.wraps(func)
-    def wrapper(*args, reducer: Callable, callback: Callable, **kwargs):
-        """
-        Wrapper applied to decorated function.
+
+    def __init__(
+        self,
+        reducer: Callable[[Dict[str, Any], Any], Dict[str, Any]],
+        callback: Callable[[Dict[str, Any], Any], bool],
+    ) -> None:
+        self._reducer = reducer
+        self._callback = callback
+
+    def __call__(
+        self, func: Callable[..., T]
+    ) -> Callable[..., Generator[T, None, None]]:
+        """Wrap function to handle paginated results.
 
         Args:
-            reducer (Callable): Function to update state with pagination metadata.
-            callback (Callable): Function which returns True once request is completed.
-                Stop condition must depend on state or pagination metadata.
-            *args
-            **kwargs
+            func: Decorated function.
+
+        Returns:
+            Function wrapper.
 
         """
-        completed = False
-        state = {
-            'params': kwargs.pop('params', None),
-            'data': kwargs.pop('data', None)
-        }
 
-        while not completed:
-            if state.get('params'):
-                kwargs.update({'params': state.get('params')})
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Generator[T, None, None]:
+            """Wrapper applied to decorated function.
+
+            Args:
+                *args: Positional arguments to pass to wrapped function.
+                **kwargs: Keyword arguments to pass to wrapped function.
 
-            if state.get('data'):
-                kwargs.update({'data': state.get('data')})
+            """
+            completed = False
+            state: Dict[str, Any] = {"args": args, "kwargs": kwargs}
 
-            response = func(*args, **kwargs)
-            yield response
+            while not completed:
+                response = func(*state["args"], **state["kwargs"])
+                yield response
 
-            state = reducer(state, response)
-            completed = callback(state, response)
+                state = self._reducer(state, response)
+                completed = self._callback(state, response)
 
-    return wrapper
+        functools.update_wrapper(wrapper, func)
+        return wrapper

apytizer/endpoints/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/endpoints/__init__.py
+
+# Local Imports
+from .abstract_endpoint import *
+from .web_endpoint import *

apytizer/endpoints/abstract_endpoint.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/endpoints/abstract_endpoint.py
+"""Abstract endpoint class.
+
+This module defines an abstract endpoint class which provides an interface
+for subclasses to implement. Each of the abstract methods represents
+a standard HTTP request method.
+
+"""
+
+# Standard Library Imports
+import abc
+from typing import Optional
+from typing import TYPE_CHECKING
+
+# Local Imports
+from ..connections import AbstractConnection
+
+if TYPE_CHECKING:
+    from ..apis import AbstractAPI
+
+__all__ = ["AbstractEndpoint"]
+
+
+class AbstractEndpoint(abc.ABC):
+    """Represents an abstract endpoint."""
+
+    @property
+    @abc.abstractmethod
+    def api(self) -> "AbstractAPI":
+        """API."""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def connection(self) -> Optional[AbstractConnection]:
+        """Connection with which to make requests."""
+        raise NotImplementedError