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

apytizer/routes/base_route.py

@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/routes/base_route.py
+
+# Standard Library Imports
+from typing import List
+
+# Local Imports
+from .abstract_route import AbstractRoute
+
+__all__ = ["Route"]
+
+
+class Route(AbstractRoute):
+    """Implements a route.
+
+    Args:
+        __value: Value.
+
+    """
+
+    def __init__(self, __value: str = "/", /) -> None:
+        if not isinstance(__value, (AbstractRoute, str)):  # type: ignore
+            message = f"expected type 'str', got {type(__value)} instead"
+            raise TypeError(message)
+
+        self._value = str(__value).strip("/") + "/"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, (AbstractRoute, str)):
+            return False
+
+        other_segments = get_segments(str(other))
+        self_segments = get_segments(self._value)
+        result = segments_are_equal(other_segments, self_segments)
+        return result
+
+    def __hash__(self) -> int:
+        return hash(self._value.lower())
+
+    def __len__(self) -> int:
+        return len(get_segments(self._value))
+
+    def __str__(self) -> str:
+        return self._value
+
+    def __gt__(self, other: object) -> bool:
+        if not isinstance(other, (AbstractRoute, str)):
+            return False
+
+        self_segments = get_segments(self._value)
+        other_segments = get_segments(str(other))
+        result = tuple(self_segments) > tuple(other_segments)
+        return result
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, (AbstractRoute, str)):
+            return False
+
+        self_segments = get_segments(self._value)
+        other_segments = get_segments(str(other))
+        result = tuple(self_segments) < tuple(other_segments)
+        return result
+
+    def __add__(self, other: object) -> AbstractRoute:
+        if not isinstance(other, str):
+            message = f"expected type 'str', got {type(other)} instead"
+            raise TypeError(message)
+
+        result = Route(self._value + other.strip("/"))
+        return result
+
+    def __truediv__(self, other: object) -> AbstractRoute:
+        if not isinstance(other, str):
+            message = f"expected type 'str', got {type(other)} instead"
+            raise TypeError(message)
+
+        result = Route(self._value + other.strip("/"))
+        return result
+
+
+# ----------------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------------
+def count_segments(__value: str, /) -> int:
+    """Get number of segments.
+
+    Args:
+        __value: Value for which to get number of segments.
+
+    Returns:
+        Number of segments.
+
+    """
+    result = len(get_segments(__value))
+    return result
+
+
+def get_segments(__value: str, /) -> List[str]:
+    """Get segments of string seperated by slashes.
+
+    Args:
+        __value: Value for which to get segments.
+
+    Returns:
+        Segments.
+
+    """
+    if not isinstance(__value, str):  # type: ignore
+        message = f"expected type 'str', got {type(__value)} instead"
+        raise TypeError(message)
+
+    result = __value.strip("/").split("/")
+    return result
+
+
+def segments_are_equal(
+    first: List[str], second: List[str], placeholder: str = r"{}"
+) -> bool:
+    """Check whether segments are equal.
+
+    Args:
+        first: First list of segments.
+        second: Second list of segments.
+        placeholder: Placeholder. Default ``{}``.
+
+    Returns:
+        Whether segments are equal.
+
+    """
+    if len(first) != len(second):
+        return False
+
+    result = all(
+        left.lower() == right.lower()
+        for left, right in zip(first, second)
+        if right != placeholder
+    )
+    return result

apytizer/sessions/__init__.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/sessions/__init__.py
+
+# Standard Library Imports
+from typing import Type
+from typing import TYPE_CHECKING
+
+# Local Imports
+from .abstract_session import *
+from .requests_session import *
+
+if TYPE_CHECKING:
+    from ..engines import AbstractEngine
+
+
+class sessionmaker:
+    """Implements a sessionmaker."""
+
+    def __init__(
+        self, class_: Type[RequestsSession] = RequestsSession
+    ) -> None:
+        self._session_type = class_
+
+    def __call__(self, __engine: "AbstractEngine", /) -> RequestsSession:
+        result = self._session_type(
+            adapters=getattr(__engine, "adapters", None),
+            auth=getattr(__engine, "auth", None),
+            cert=getattr(__engine, "cert", None),
+            proxies=getattr(__engine, "proxies", None),
+            stream=getattr(__engine, "stream", False),
+            verify=getattr(__engine, "verify", True),
+        )
+        return result

apytizer/sessions/abstract_session.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/sessions/abstract_session.py
+"""Abstract Session Class.
+
+This module defines an abstract session class which provides an interface
+for subclasses to implement.
+
+"""
+
+# Standard Library Imports
+import abc
+from typing import Any
+from typing import TYPE_CHECKING
+
+# Third-Party Imports
+import requests
+from requests.adapters import HTTPAdapter
+
+if TYPE_CHECKING:
+    from ..protocols import Protocol
+
+__all__ = ["AbstractSession"]
+
+
+class AbstractSession(abc.ABC):
+    """Represents an abstract session."""
+
+    @abc.abstractmethod
+    def start(self) -> None:
+        """Starts session."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Destroys session."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def mount(self, protocol: "Protocol", adapter: HTTPAdapter) -> None:
+        """Registers a connection adapter to a protocol prefix.
+
+        Args:
+            protocol: Protocol prefix on which to mount adapter.
+            adapter: HTTP adapter to apply to connection.
+
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def send(
+        self, __request: requests.Request, /, **kwargs: Any
+    ) -> requests.Response:
+        """Send an HTTP request.
+
+        Args:
+            __request: Request to send.
+            **kwargs: Keyword arguments.
+
+        Returns:
+            Response.
+
+        """
+        raise NotImplementedError

apytizer/sessions/requests_session.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/sessions/requests_session.py
+"""Requests Session Class.
+
+This module defines the requests session class implementation.
+
+"""
+
+# Standard Library Imports
+import logging
+from typing import Any
+from typing import Dict
+from typing import MutableMapping
+from typing import Optional
+from typing import Tuple
+from typing import Union
+from typing import final
+
+# Third-Party Imports
+import requests
+from requests.auth import AuthBase
+from requests.adapters import HTTPAdapter
+
+# Local Imports
+from .abstract_session import AbstractSession
+from ..protocols import Protocol
+
+__all__ = ["RequestsSession"]
+
+
+log = logging.getLogger("apytizer")
+
+
+class RequestsSession(AbstractSession):
+    """Implements a requests session.
+
+    The `RequestsSession` class provides `start` and `close` methods for manual
+    control of the session.
+
+    A session instance can also be used as a context manager.
+
+    Args:
+        adapters (optional): Connection adapters. Default ``None``.
+        auth (optional): Authentication header. default ``None``.
+        cert (optional): Client certificate. Default ``None``.
+        proxies (optional): Protocols mapped to proxy URLs. Default ``None``.
+        stream (optional): Whether to stream response content. Default ``False``.
+        verify (optional): Whether to verify certificate. Default ``True``.
+
+    .. Requests Documentation:
+        https://docs.python-requests.org/en/latest/api/#request-sessions
+
+    """
+
+    def __init__(
+        self,
+        *,
+        adapters: Optional[Dict[Protocol, HTTPAdapter]] = None,
+        auth: Optional[Union[AuthBase, Tuple[str, str]]] = None,
+        cert: Optional[Union[str, Tuple[str, str]]] = None,
+        proxies: Optional[MutableMapping[str, str]] = None,
+        stream: Optional[bool] = False,
+        verify: Optional[bool] = True,
+    ) -> None:
+        self._session = requests.Session()
+        self._session.auth = auth
+        self._session.cert = cert
+        self._session.proxies = proxies  # type: ignore
+        self._session.stream = stream  # type: ignore
+        self._session.verify = verify  # type: ignore
+
+        if adapters is not None:
+            for protocol, adapter in adapters.items():
+                self._session.mount(protocol, adapter)
+
+    @final
+    def __enter__(self) -> AbstractSession:
+        """Starts session as context manager."""
+        self.start()
+        return self
+
+    @final
+    def __exit__(self, *_) -> None:
+        """Stops session as context manager."""
+        self.close()
+
+    def start(self) -> None:
+        """Starts session."""
+        log.debug("Starting session...")
+
+    def close(self, *_: Any) -> None:
+        """Destroys session."""
+        self._session.close()
+        log.debug("Session closed")
+
+    def mount(self, protocol: Protocol, adapter: HTTPAdapter) -> None:
+        """Registers connection adapter to protocol prefix.
+
+        Args:
+            protocol: Protocol on which to mount adapter.
+            adapter: HTTP adapter to apply to connection.
+
+        """
+        self._session.mount(f"{protocol.value!s}://", adapter)
+        log.debug(
+            "Mounted %(adapter)s adapter to %(protocol)s protocol",
+            {"adapter": adapter, "protocol": protocol.value},
+        )
+
+    def send(
+        self, __request: requests.Request, /, **kwargs: Any
+    ) -> requests.Response:
+        """Send an HTTP request.
+
+        Args:
+            __request: Request to send.
+            **kwargs (optional): Keyword arguments.
+
+        Returns:
+            Response object.
+
+        """
+        request = self._session.prepare_request(__request)
+        response = self._session.send(request, **kwargs)
+        return response

apytizer/states/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/states/__init__.py
+
+# Local Imports
+from .abstract_state import *
+from .local_state import *

apytizer/states/abstract_state.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/states/abstract_state.py
+"""Abstract State Class Interface.
+
+This module defines an abstract state 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 Generator
+from typing import Mapping
+from typing import Optional
+
+__all__ = ["AbstractState"]
+
+
+class AbstractState(abc.ABC):
+    """Represents an abstract state."""
+
+    @abc.abstractmethod
+    def __contains__(self, key: str) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __eq__(self, other: object) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __getitem__(self, key: str) -> Any:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __setitem__(self, key: str, value: Any) -> None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __iter__(self) -> Generator[Any, None, None]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get(self, key: str) -> Any:
+        """Abstract method for getting an item from state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def items(self) -> Any:
+        """Abstract method for getting items from state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def update(
+        self,
+        __m: Optional[Mapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Abstract method for updating state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def rollback(self) -> None:
+        """Abstract method for rolling back changes to state."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def save(self) -> None:
+        """Abstract method for saving changes to state."""
+        raise NotImplementedError

apytizer/states/local_state.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+# src/apytizer/states/base_state.py
+"""Base State Class.
+
+This module defines the implementation of a base state class.
+
+"""
+
+# Standard Library Imports
+from __future__ import annotations
+import collections
+from typing import Any
+from typing import Dict
+from typing import Generator
+from typing import Mapping
+from typing import Optional
+from typing import Tuple
+
+# Local Imports
+from . import AbstractState
+from .. import utils
+
+__all__ = ["LocalState"]
+
+
+class LocalState(AbstractState):
+    """Class implements a local state."""
+
+    def __init__(
+        self,
+        base: Optional[Dict[str, Any]] = None,
+        default: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self._state = collections.ChainMap(base or {}, default or {})
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._state
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            dict(other) == dict(self)
+            if isinstance(other, AbstractState)
+            else False
+        )
+
+    def __getitem__(self, key: str) -> Any:
+        result = self.get(key)
+        return result
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._state = utils.deep_set(self._state, key, value)
+
+    def __iter__(self) -> Generator[Tuple[str, Any], None, None]:
+        yield from self._state.items()
+
+    def get(self, key: str) -> Any:
+        """Get an item from state.
+
+        Args:
+            key: Key.
+
+        Returns:
+            Value of key in state.
+
+        """
+        if not isinstance(key, str):  # type: ignore
+            message = f"expected type 'str', got {type(key)} instead"
+            raise TypeError(message)
+
+        result = utils.deep_get(self._state, key)
+        return result
+
+    def items(self) -> Any:
+        """Get items from state."""
+        results = self._state.items()
+        return results
+
+    def update(
+        self,
+        __m: Optional[Mapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Update state.
+
+        Args:
+            __m (optional): Mapping. Default ``None``.
+            **kwargs: Keyword arguments.
+
+        """
+        self._state.update(__m or {}, **kwargs)
+
+    def rollback(self) -> None:
+        """Roll back changes to state."""
+        self._state.clear()
+
+    def save(self) -> None:
+        """Save changes to state."""
+        if self._state.maps[0]:  # type: ignore
+            self._state = self._state.new_child()  # type: ignore

apytizer/utils/__init__.py

@@ -1,6 +1,11 @@
 # -*- coding: utf-8 -*-
+# src/apytizer/utils/__init__.py
 
-# pylint: skip-file
-
-from .generate_key import generate_key
-from .merge import merge
+# Local Imports
+from .caching import *
+from .dictionaries import *
+from .errors import *
+from .iterables import *
+from .objects import *
+from .strings import *
+from .typing import *

apytizer/utils/caching.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+# Standard Library Import
+from typing import Any
+from typing import Callable
+from typing import Hashable
+from typing import Tuple
+
+# Third-Party Imports
+from cachetools.keys import hashkey
+
+__all__ = ["generate_key"]
+
+
+def generate_key(*tags: str) -> Callable[..., Tuple[Hashable, ...]]:
+    """Generates a hashable key for caching values.
+
+    Args:
+        *tags: Tags.
+
+    """
+
+    def hash_parameters(*args: Any, **kwargs: Any) -> Tuple[Hashable, ...]:
+        """Hashes function parameters.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments.
+
+        Return:
+            Cache Key.
+
+        """
+        result = hashkey(
+            *tags, *args, *[f"{k!s}={v!s}" for k, v in sorted(kwargs.items())]
+        )
+        return result
+
+    return hash_parameters