RESTFly 2.0.3__py3-none-any.whl

restfly/_base.py

@@ -0,0 +1,340 @@
+from __future__ import annotations
+
+import logging
+import platform
+from collections import defaultdict
+from collections.abc import Callable
+from ssl import SSLContext
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic_xml import BaseXmlModel
+
+from ._errors import APIError, ErrorStatus, build_error_map
+from ._utils import assign_annotations
+from ._version import version as RESTFLY_VERSION
+from .types import (
+    DEFAULT_LIMITS,
+    DEFAULT_MAX_REDIRECTS,
+    DEFAULT_TIMEOUT_CONFIG,
+    HTTPX_VERSION,
+    USE_CLIENT_DEFAULT,
+    AsyncBaseTransport,
+    AsyncClient,
+    AuthTypes,
+    BaseTransport,
+    CertTypes,
+    Client,
+    CookieTypes,
+    EventHook,
+    HeaderTypes,
+    HTTPMethods,
+    Limits,
+    Model,
+    ProxyTypes,
+    QueryParamTypes,
+    RequestContent,
+    RequestData,
+    RequestExtensions,
+    RequestFiles,
+    TimeoutTypes,
+    UseClientDefault,
+    XMLModel,
+)
+
+
+class APIClientBase:
+    __client_class__: type[Client | AsyncClient]
+    __endpoint_class__: type[APIBaseEndpoint]
+
+    _base_url: str = ""
+    """ The base URL fragment to prefix all API calls with. """
+
+    _client: Client | AsyncClient
+    """ HTTPX Client Session object """
+
+    _json_load_kwargs: dict[str, Any]
+    """ Client-level Pydantic BaseModel.model_validate kwargs """
+
+    _json_dump_kwargs: dict[str, Any]
+    """ Client-level Pydantic BaseModel.model_dump kwargs """
+
+    _xml_load_kwargs: dict[str, Any]
+    """ Client-level Pydantic-XML BaseXmlModel.from_xml kwargs """
+
+    _xml_dump_kwargs: dict[str, Any]
+    """ Client-level Pydantic-XML BaseXmlModel.to_xml kwargs """
+
+    _lib_name: str = "RESTFly"
+    """ Library name """
+
+    _lib_version: str = "2"
+    """ Library version """
+
+    _retry_max: int = 5
+    """ Maximum number of retries to attempt before giving up. """
+
+    _logger: logging.Logger
+    """ Logger for the client """
+
+    _error_class: type[APIError] = APIError
+    """ API Exception Class to use for all API Errors/Exceptions """
+
+    __error_map__: dict[int, ErrorStatus] | None = None
+    """ The default built-in error map. If None the library default is used. """
+
+    _error_map: defaultdict[int, ErrorStatus]
+    """
+    The error map determining how to handle non-OK status codes. Represented by the
+    integer status code along with an ErrorStatus data-class object detailing how to
+    handle the response. Any overloads to the base error map should be provided here
+    and this attribute will be then be replaced at initialization with the merging of
+    the default map, this attribute, and anything passed to the constructor. The
+    resulting error map will be used during operation of the APIClass object.
+    """
+
+    def __init__(
+        self,
+        *,
+        auth: AuthTypes | None = None,
+        params: QueryParamTypes | None = None,
+        headers: HeaderTypes | None = None,
+        cookies: CookieTypes | None = None,
+        verify: SSLContext | str | bool = True,
+        cert: CertTypes | None = None,
+        http1: bool = True,
+        http2: bool = False,
+        proxy: ProxyTypes | None = None,
+        mounts: (dict[str, Any]) | None = None,
+        timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG,
+        follow_redirects: bool = False,
+        limits: Limits = DEFAULT_LIMITS,
+        max_redirects: int = DEFAULT_MAX_REDIRECTS,
+        event_hooks: (dict[str, list[EventHook]]) | None = None,
+        base_url: str | None = None,
+        transport: AsyncBaseTransport | BaseTransport | None = None,
+        trust_env: bool = True,
+        default_encoding: str | Callable[[bytes], str] = "utf-8",
+        vendor: str = "unknown",
+        product: str = "unknown",
+        build: str = "unknown",
+        retry_max: int = 5,
+        json_load_kwargs: dict[str, Any] | None = None,
+        json_dump_kwargs: dict[str, Any] | None = None,
+        xml_load_kwargs: dict[str, Any] | None = None,
+        xml_dump_kwargs: dict[str, Any] | None = None,
+        error_map: dict[int, ErrorStatus] | None = None,
+        error_class: type[APIError] | None = None,
+    ) -> None:
+        # Initialize mutables.
+        headers = {} if headers is None else headers
+        error_map = {} if error_map is None else error_map
+        error_class = self._error_class if error_class is None else error_class
+
+        # Initialize the private attributes for the client object.
+        self._base_url = base_url if base_url else self._base_url
+        self._logger = logging.getLogger(__name__)
+        self._retry_max = retry_max if retry_max else self._retry_max
+        self._json_load_kwargs = (
+            json_load_kwargs
+            if json_load_kwargs
+            else getattr(self, "_json_load_kwargs", {})
+        )
+        self._json_dump_kwargs = (
+            json_dump_kwargs
+            if json_dump_kwargs
+            else getattr(self, "_json_dump_kwargs", {})
+        )
+        self._xml_load_kwargs = (
+            xml_load_kwargs
+            if xml_load_kwargs
+            else getattr(self, "_xml_load_kwargs", {})
+        )
+        self._xml_dump_kwargs = (
+            xml_dump_kwargs
+            if xml_dump_kwargs
+            else getattr(self, "_xml_dump_kwargs", {})
+        )
+
+        # Construct the error map default dict using the built-in error_map as well as
+        # the over loadable _error_map extension and then lastly update with any
+        # error_map provided at initialization.  Lastly store the resulting defaultdict
+        # over the _error_map private attribute.
+        self._error_map = build_error_map(
+            base_map=self.__error_map__, overloads=error_map, error_class=error_class
+        )
+
+        # If we had received a pydantic model for the client params, then we will first
+        # coerce them into a python dictionary.
+        if isinstance(params, BaseModel):
+            params = params.model_dump(mode="json", exclude_none=True)
+
+        # Instantiate the HTTPX Client with the arguments we have.
+        self._client = self.__client_class__(
+            auth=auth,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            verify=verify,
+            cert=cert,
+            http1=http1,
+            http2=http2,
+            proxy=proxy,
+            mounts=mounts,
+            timeout=timeout,
+            follow_redirects=follow_redirects,
+            limits=limits,
+            max_redirects=max_redirects,
+            event_hooks=event_hooks,
+            base_url=self._base_url,
+            transport=transport,  # type: ignore[arg-type] #ty: ignore[invalid-argument-type]
+            trust_env=trust_env,
+            default_encoding=default_encoding,
+        )
+
+        # Update the client with the User-Agent header.
+        user_agent = (
+            f"Integration/1.0 ({vendor}; {product}; Build/{build}) "
+            f"{self._lib_name}/{self._lib_version} "
+            f"(RESTFly/{RESTFLY_VERSION}; "
+            f"HTTPX/{self.__client_class__.__name__}-{HTTPX_VERSION}; "
+            f"Python/{platform.python_version()}; "
+            f"{platform.system()}/{platform.machine()})"
+        )
+        self._client.headers.update({"User-Agent": user_agent})
+
+        # Lastly, we will run the annotation assignment build-in to make sure that the
+        # public endpoints are properly grafted to the client class.
+        self.__assign_annotations__()
+
+    def _request_pre_process(
+        self,
+        method: HTTPMethods,
+        url: str,
+        params: QueryParamTypes | None = None,
+        content: RequestContent | None = None,
+        data: RequestData | None = None,
+        files: RequestFiles | None = None,
+        json: Model | object | None = None,
+        xml: XMLModel | str | bytes | None = None,
+        headers: dict[str, str] | None = None,
+        request_model_kwargs: dict[str, Any] | None = None,
+        cookies: CookieTypes | None = None,
+        timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+        extensions: RequestExtensions | None = None,
+    ) -> dict[str, Any]:
+        """
+        Performs preflight pre-processing of the request in preparation to be sent to
+        HTTPX. Most notably this method is what handles any potential model marshalling
+        into the request format.  The output is passed as the kwargs into HTTPXs
+        request builder.
+
+        Args:
+            method: The HTTP Method.
+            url: The HTTP url (this can be either a partial or a full URL).
+            params: Query parameters.
+            content: Raw request content.
+            data: The HTTP request body.
+            files: Any files to upload with the request.
+            json: Overrides the content and data attributes with JSON-formatted data.
+            xml: Overrides the content and data attributes with XML-formatted data.
+            headers: Any additional headers to pass into the request.
+            request_model_kwargs:
+                The pydantic/pydantic-xml kwargs to be passed to the model as part of
+                marshalling the data into the expected format.
+            cookies: The cookies to pass to the request.
+            timeout: The HTTP request timeout.
+            extensions: Any request extensions passed as part of the request.
+
+        Returns:
+            The kwargs dictionary to be passed to the request builder.
+        """
+        # Initialize mutables
+        headers = {} if headers is None else headers
+        request_model_kwargs = (
+            {} if request_model_kwargs is None else request_model_kwargs
+        )
+
+        # The query parameters must always be transformed into a dictionary to be
+        # properly passed to HTTPX
+        if isinstance(params, BaseModel):
+            params = params.model_dump(mode="json", **self._json_dump_kwargs)
+
+        # If the XML model actually is Pydantic-XML model, then we will want to marshal
+        # it into bytes and set the content type to XML.
+        if isinstance(xml, BaseXmlModel):
+            xml_kwargs: dict[str, Any] = {}
+            for updates in (
+                getattr(self, "_xml_dump_kwargs", {}),
+                request_model_kwargs,
+            ):
+                xml_kwargs.update(updates)
+            content = xml.to_xml(**xml_kwargs)
+            headers["Content-Type"] = "application/xml"
+
+        # If the xml attribute is already a string or bytes object, then simply set
+        # the content type to XML.
+        elif isinstance(xml, (str, bytes)):
+            content = xml
+            headers["Content-Type"] = "application/xml"
+
+        # If the json attribute is actually a Pydantic model, then we will want to
+        # marshal the data using Pydantics model dump and set the content type to JSON
+        elif isinstance(json, BaseModel):
+            pydantic_kwargs: dict[str, Any] = {}
+            for updates in (
+                getattr(self, "_json_dump_kwargs", {}),
+                request_model_kwargs,
+            ):
+                pydantic_kwargs.update(updates)
+            content = json.model_dump_json(**pydantic_kwargs)
+            headers["Content-Type"] = "application/json"
+            json = None
+
+        # Return the kwargs to the caller.
+        return {
+            "method": method,
+            "url": url,
+            "params": params,
+            "content": content,
+            "data": data,
+            "files": files,
+            "json": json,
+            "headers": headers,
+            "cookies": cookies,
+            "timeout": timeout,
+            "extensions": extensions,
+        }
+
+    def __assign_annotations__(self) -> None:
+        """
+        Handles Annotation assignment for API Endpoints.
+        """
+        assign_annotations(self, self.__endpoint_class__)
+
+
+class APIBaseEndpoint:
+    _path: str | None = None
+    """ Path fragment to append to the base url already stored within the client. """
+
+    _logger: logging.Logger
+    """
+    The same logging handler that the client has, it also exists here for convenience.
+    """
+
+    _client: APIClientBase
+    """
+    The client object that this endpoint is associated with. Provided here in order to
+    interact with other endpoints that may be grafted to the client.
+    """
+
+    def __init__(self, client: APIClientBase | APIBaseEndpoint) -> None:
+        match client:
+            case APIClientBase():
+                self._client = client
+            case APIBaseEndpoint():
+                self._client = client._client
+            case _:
+                raise TypeError(f"Client {client} is not a valid client type.")
+        self._logger = client._logger
+        assign_annotations(self, self._client.__endpoint_class__)

restfly/_errors.py

@@ -0,0 +1,213 @@
+"""
+Error handling classes and data-classes.
+"""
+
+import logging
+from collections import defaultdict
+from dataclasses import dataclass, replace
+
+from httpx import Response
+from pydantic import BaseModel
+
+
+class RetryError(Exception):
+    """
+    RetryError is thrown when too many retries have been made to the endpoint and we
+    have been forced to stop attempting to call the API endpoint.
+    """
+
+    def __init__(self, url: str, method: str, attempts: int):
+        super().__init__(f"Too many attempts ({attempts}) to {method} {url}")
+
+
+class APIError(Exception):
+    """
+    The Base API Error class to be thrown in the event that a non-OK status code is
+    returned.
+    """
+
+    status_code: int
+    """ Status code of the HTTP Response """
+
+    response: Response
+    """ HTTPX Response object of the exception """
+
+    obj: BaseModel | None
+    """ Coerced data obj of the response (if any) """
+
+    def __init__(
+        self,
+        response: Response,
+        template: str,
+        obj: BaseModel | None = None,
+    ):
+        self.status_code = response.status_code
+        self.obj = obj
+        self.response = response
+        msg = template.format(response=response, request=response.request)
+        logger = logging.getLogger(__name__)
+        logger.warning(msg)
+        super().__init__(msg)
+
+
+@dataclass
+class ErrorStatus:
+    """
+    Defines the attributes associated to each non-OK status code.
+
+    Parameters:
+        retry:
+            Should the request be retried?
+        template:
+            The log/exception to be sent. This string template will accept both the
+            request and response objects.
+        model:
+            The Pydantic model (if any) to coerce the response body into.
+        exception:
+            The Exception class to throw.
+        backoff:
+            How many seconds to wait before retrying? This field will be overloaded
+            if the client detects a Retry-After header and will use the response
+            value instead of this if it exists.
+        jitter:
+            If this value is set to a non-zero value, then when calculating the amount
+            of time to wait, the client will randomly select a value between 0 and this
+            value and append it to the wait before retying. Normally we will want this
+            set to something in order to ensure that we stagger retries to the API to
+            prevent overwhelming it.
+    """
+
+    retry: bool = False
+    template: str = (
+        r"[{response.status_code}] Response from {request.method} {request.url}"
+    )
+    model: type[BaseModel] | None = None
+    exception: type[APIError] = APIError
+    backoff: float = 1.0
+    jitter: float = 0.5
+
+
+def build_error_map(
+    base_map: dict[int, ErrorStatus] | None = None,
+    overloads: dict[int, ErrorStatus] | None = None,
+    error_class: type[APIError] | None = None,
+) -> defaultdict[int, ErrorStatus]:
+    """
+    Error map builder.
+    """
+    if base_map is None:
+        base_map = ERROR_MAP
+    if overloads is None:
+        overloads = {}
+    if error_class is None:
+        error_class = APIError
+
+    def error_status() -> ErrorStatus:
+        return ErrorStatus(exception=error_class if error_class else APIError)
+
+    error_map = defaultdict(
+        error_status,
+        {k: replace(v, exception=error_class) for k, v in base_map.items()},
+    )
+    error_map.update(
+        {k: replace(v, exception=error_class) for k, v in overloads.items()}
+    )
+    return error_map
+
+
+ERROR_MAP = {
+    400: ErrorStatus(template=r"[400] Bad Request {request.method} {request.url}"),
+    401: ErrorStatus(template=r"[401] Unauthorized {request.method} {request.url}"),
+    402: ErrorStatus(template=r"[402] Payment Required {request.method} {request.url}"),
+    403: ErrorStatus(template=r"[403] Access Forbidden {request.method} {request.url}"),
+    404: ErrorStatus(template=r"[404] Not Found {request.method} {request.url}"),
+    405: ErrorStatus(
+        template=r"[405] Method Not Allowed {request.method} {request.url}"
+    ),
+    406: ErrorStatus(template=r"[406] Not Acceptable {request.method} {request.url}"),
+    407: ErrorStatus(
+        template=r"[407] Proxy Auth Required {request.method} {request.url}"
+    ),
+    408: ErrorStatus(
+        template=r"[408] Request Timed Out {request.method} {request.url}"
+    ),
+    409: ErrorStatus(template=r"[409] Request Conflict {request.method} {request.url}"),
+    410: ErrorStatus(template=r"[410] Gone {request.method} {request.url}"),
+    411: ErrorStatus(template=r"[411] Length Required {request.method} {request.url}"),
+    412: ErrorStatus(
+        template=r"[412] Precondition Failed {request.method} {request.url}"
+    ),
+    413: ErrorStatus(
+        template=r"[413] Content Too Large {request.method} {request.url}"
+    ),
+    414: ErrorStatus(template=r"[414] URI Too Long {request.method} {request.url}"),
+    415: ErrorStatus(
+        template=r"[415] Unsupported Media Type {request.method} {request.url}"
+    ),
+    416: ErrorStatus(
+        template=r"[416] Range Not Satisfiable {request.method} {request.url}"
+    ),
+    417: ErrorStatus(
+        template=r"[417] Expectation Failed {request.method} {request.url}"
+    ),
+    418: ErrorStatus(template=r"[418] I'm a Teapot {request.method} {request.url}"),
+    421: ErrorStatus(
+        template=r"[421] Misdirected Request {request.method} {request.url}"
+    ),
+    422: ErrorStatus(
+        template=r"[422] Unprocessable Content {request.method} {request.url}"
+    ),
+    423: ErrorStatus(template=r"[423] Locked {request.method} {request.url}"),
+    424: ErrorStatus(
+        template=r"[424] Failed Dependency {request.method} {request.url}"
+    ),
+    425: ErrorStatus(template=r"[425] Too Early {request.method} {request.url}"),
+    426: ErrorStatus(template=r"[426] Upgrade Required {request.method} {request.url}"),
+    428: ErrorStatus(
+        template=r"[428] Precondition Required {request.method} {request.url}"
+    ),
+    429: ErrorStatus(
+        retry=True,
+        template=r"[429] Too Many Requests to {request.method} {request.url}",
+        backoff=30,
+    ),
+    431: ErrorStatus(
+        template=r"[431] Request Header Fields Too Large {request.method} {request.url}"
+    ),
+    451: ErrorStatus(
+        template=r"[451] Unavailable For Legal Reasons {request.method} {request.url}"
+    ),
+    500: ErrorStatus(
+        template=r"[500] Internal Server Error {request.method} {request.url}"
+    ),
+    501: ErrorStatus(template=r"[501] Not Implemented {request.method} {request.url}"),
+    502: ErrorStatus(
+        retry=True,
+        template=r"[502] Bad Gateway Response {request.method} {request.url}",
+        backoff=10,
+    ),
+    503: ErrorStatus(
+        retry=True,
+        template=r"[503] Service Unavailable {request.method} {request.url}",
+        backoff=10,
+    ),
+    504: ErrorStatus(
+        retry=True,
+        template=r"[504] Gateway Timeout {request.method} {request.url}",
+        backoff=10,
+    ),
+    505: ErrorStatus(
+        template=r"[505] HTTP Version Not Supported {request.method} {request.url}"
+    ),
+    506: ErrorStatus(
+        template=r"[506] Variant Also Negotiates {request.method} {request.url}"
+    ),
+    507: ErrorStatus(
+        template=r"[507] Insufficient Storage {request.method} {request.url}"
+    ),
+    508: ErrorStatus(template=r"[508] Loop Detected {request.method} {request.url}"),
+    510: ErrorStatus(template=r"[510] Not Extended {request.method} {request.url}"),
+    511: ErrorStatus(
+        template=r"[511] Network Authentication Required {request.method} {request.url}"
+    ),
+}