http-dynamix 1.0.0__py3-none-any.whl

http_dynamix/__init__.py

@@ -0,0 +1,38 @@
+"""Copyright (c) 2024, Aydin A.
+
+This module is the entry point for the http_dynamix package. It imports the
+version number and the logger from the log module. It also imports the
+HttpClientFactory class from the client_factory module.
+"""
+from http_dynamix.factory import ClientFactory
+from http_dynamix.enums import SegmentFormat, ClientType
+from http_dynamix._version import version
+from http_dynamix.auth import BearerAuth, ApiKeyAuth
+from http_dynamix.log import log as logger, LogMaster
+from http_dynamix.core import SegmentFormatter
+from http_dynamix.clients import SyncClient, AsyncClient, AsyncDynamicClient, SyncDynamicClient
+
+
+__all__ = [
+    "ClientFactory",
+    "ClientType",
+    "SegmentFormat",
+    "logger",
+    "LogMaster",
+    "version",
+    "BearerAuth",
+    "ApiKeyAuth"
+    "SegmentFormatter",
+    "BaseClient",
+    "BaseDynamicClient",
+    "SyncClient",
+    "AsyncClient",
+    "AsyncDynamicClient",
+    "SyncDynamicClient"
+]
+
+
+__author__ = "Aydin Abdi"
+__version__ = version
+__license__ = "MIT"
+

http_dynamix/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)

http_dynamix/auth.py

@@ -0,0 +1,194 @@
+"""Authentication classes for dynamic HTTP client.
+
+This module provides various authentication methods compatible with HTTPX client.
+All authentication classes inherit from httpx.Auth and implement the required auth_flow
+method for proper request authentication.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from http_dynamix.log import log as logger
+
+
+@dataclass(frozen=True, slots=True)
+class BearerAuth(httpx.Auth):
+    """Bearer token authentication method.
+
+    Implements Bearer token authentication as defined in RFC 6750.
+
+    Args:
+        token: The bearer token for authentication.
+        auth_header: Custom authorization header name (default: "Authorization").
+    """
+
+    token: str
+    auth_header: str = "Authorization"
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        """Yields authenticated requests using Bearer auth scheme.
+
+        Args:
+            request: The HTTP request object to authenticate.
+
+        Yields:
+            httpx.Request: The authenticated HTTP request.
+        """
+        request.headers[self.auth_header] = self._build_auth_header()
+        logger.debug("Applied Bearer token auth")
+        yield request
+
+    def _build_auth_header(self) -> str:
+        """Builds the Authorization header with Bearer token.
+
+        Returns:
+            str: The formatted Authorization header.
+        """
+        return f"Bearer {self.token}"
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyAuth(httpx.Auth):
+    """API key authentication method.
+
+    Implements API key authentication using custom header.
+
+    Args:
+        api_key: The API key for authentication.
+        header_name: The header name for the API key (default: "X-API-Key").
+    """
+
+    api_key: str
+    header_name: str = "X-API-Key"
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        """Yields authenticated requests using API key.
+
+        Args:
+            request: The HTTP request object to authenticate.
+
+        Yields:
+            httpx.Request: The authenticated HTTP request.
+        """
+        request.headers[self.header_name] = self.api_key
+        logger.debug(f"Applied API key auth with header: {self.header_name}")
+        yield request
+
+
+@dataclass(slots=True)
+class MultiAuth(httpx.Auth):
+    """Multi-authentication method that combines multiple auth schemes.
+
+    Allows chaining multiple authentication methods to be applied in sequence.
+
+    Args:
+        auth_methods: List of authentication methods implementing httpx.Auth.
+    """
+
+    auth_methods: list[httpx.Auth] = field(default_factory=list)
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        """Yields authenticated requests applying multiple auth methods.
+
+        Applies each authentication method in sequence to the request.
+
+        Args:
+            request: The HTTP request object to authenticate.
+
+        Yields:
+            httpx.Request: The authenticated HTTP request.
+        """
+        current_request = request
+        for auth in self.auth_methods:
+            auth_flow = auth.auth_flow(current_request)
+            try:
+                while True:
+                    current_request = next(auth_flow)
+                    response = yield current_request
+                    auth_flow.send(response)
+            except StopIteration:
+                pass
+        logger.debug(f"Applied {len(self.auth_methods)} authentication methods")
+
+
+# Auth-related configuration keys
+AUTH_KEYS = frozenset(
+    ["token", "api_key", "username", "password", "auth_header", "api_key_header"]
+)
+
+
+def filter_auth_kwargs(kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Filter kwargs to only include auth-related arguments.
+
+    Args:
+        kwargs: Original kwargs dictionary
+
+    Returns:
+        Dictionary containing only auth-related arguments
+    """
+    return {k: v for k, v in kwargs.items() if k in AUTH_KEYS}
+
+
+def create_auth(
+    token: str | None = None,
+    api_key: str | None = None,
+    username: str | bytes | None = None,
+    password: str | bytes | None = None,
+    auth_header: str = "Authorization",
+    api_key_header: str = "X-API-Key",
+) -> MultiAuth | None:
+    """Factory function to create authentication method based on provided credentials.
+
+    Args:
+        token: Bearer token for authentication.
+        api_key: API key for authentication.
+        username: Username for basic authentication.
+        password: Password for basic authentication.
+        auth_header: Custom authorization header name (default: "Authorization").
+        api_key_header: Custom API key header name (default: "X-API-Key").
+
+    Returns:
+        An instance of appropriate Auth class or None if no credentials provided.
+    """
+    auth_methods: list[httpx.Auth] = []
+
+    if not any([token, api_key, username, password]):
+        return None
+
+    if token:
+        auth_methods.append(BearerAuth(token=token, auth_header=auth_header))
+
+    if api_key:
+        auth_methods.append(ApiKeyAuth(api_key=api_key, header_name=api_key_header))
+
+    if username and password:
+        auth_methods.append(httpx.BasicAuth(username=username, password=password))
+
+    return MultiAuth(auth_methods) if auth_methods else None
+
+
+def prepare_auth(**kwargs: Any) -> httpx.Auth | None:
+    """Prepares the authentication method for use in HTTPX client.
+
+    Args:
+        **kwargs: Keyword arguments containing authentication credentials.
+
+    Returns:
+        An instance of appropriate Auth class or None if no credentials provided.
+    """
+    auth_kwargs = filter_auth_kwargs(kwargs)
+    auth = create_auth(**auth_kwargs)
+    if auth:
+        logger.debug(f"Prepared authentication: {type(auth).__name__}")
+    return auth

http_dynamix/clients/__init__.py

@@ -0,0 +1,9 @@
+from http_dynamix.clients.async_client import AsyncClient, AsyncDynamicClient
+from http_dynamix.clients.sync_client import SyncClient, SyncDynamicClient
+
+__all__ = [
+    "SyncClient",
+    "SyncDynamicClient",
+    "AsyncClient",
+    "AsyncDynamicClient",
+]

http_dynamix/clients/async_client.py

@@ -0,0 +1,313 @@
+"""Async HTTP client with dynamic path creation."""
+
+from __future__ import annotations
+
+from collections.abc import Coroutine
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+import httpx
+from httpx import Response
+
+from http_dynamix.core import PathSegment, SegmentFormatter
+from http_dynamix.enums import HTTPMethod, SegmentFormat
+from http_dynamix.httpx_logger import loggix
+from http_dynamix.log import log as logger
+from http_dynamix.protocols import AsyncClientProtocol
+
+
+@dataclass
+class AsyncDynamicClient(AsyncClientProtocol):
+    """Asynchronous dynamic HTTP client.
+
+    This class allows for dynamic path creation and HTTP requests.
+
+    Example:
+        .. code-block:: python
+
+            async with AsyncClient("https://api.example.com") as client:
+                response = await client.users.john.get()
+                print(response.json())
+    """
+
+    client: AsyncClient
+    segments: list[PathSegment] = field(default_factory=list)
+    segment_format: SegmentFormat = SegmentFormat.DEFAULT
+    known_paths: dict[str, str] = field(default_factory=dict)
+
+    def _transform_path(self) -> str:
+        transformed_segments = []
+
+        for segment in self.segments:
+            if segment.value is not None:
+                transformed_segments.append(str(segment.value))
+            else:
+                segment_name = segment.name
+                transformed = SegmentFormatter(
+                    self.segment_format, self.known_paths
+                ).transform(segment_name)
+                transformed_segments.append(transformed)
+
+        return "/".join(transformed_segments)
+
+    def __getattr__(self, name: str) -> AsyncDynamicClient:
+        """Handle attribute access for dynamic path creation.
+
+        Args:
+            name: The name of the attribute.
+
+        Returns:
+            The dynamic client.
+        """
+        new_segments = self.segments.copy()
+        new_segments.append(PathSegment(name=name, format=self.segment_format))
+
+        return self.__class__(
+            client=self.client,
+            segments=new_segments,
+            segment_format=self.segment_format,
+            known_paths=self.known_paths,
+        )
+
+    def __getitem__(self, key: str | int | SegmentFormat) -> AsyncDynamicClient:
+        """Handle item access for dynamic path creation.
+
+        Args:
+            key: The key to access.
+
+        Returns:
+            The dynamic client.
+        """
+        if not self.segments:
+            raise ValueError("Cannot use [] operator without a path segment")
+
+        new_segments = self.segments.copy()
+
+        # If the key is a SegmentFormat, update the last segment with the format
+        if isinstance(key, SegmentFormat):
+            last_segment = new_segments.pop()
+            new_segments.append(last_segment.with_format(key))
+        else:
+            # Otherwise treat the key as a parameter value
+            last_segment = new_segments.pop()
+            new_segments.append(
+                PathSegment(
+                    name=last_segment.name, format=last_segment.format, value=key
+                )
+            )
+
+        return self.__class__(
+            client=self.client,
+            segments=new_segments,
+            segment_format=self.segment_format,
+            known_paths=self.known_paths,
+        )
+
+    def with_format(self, format: SegmentFormat) -> AsyncDynamicClient:
+        """Set the segment format.
+
+        Args:
+            format: The segment format.
+
+        Returns:
+            The dynamic client.
+        """
+        return self.__class__(
+            client=self.client,
+            segments=self.segments,
+            segment_format=format,
+            known_paths=self.known_paths,
+        )
+
+    def _get_url(self) -> str:
+        url = f"{self.client.base_url}/{self._transform_path()}".strip("/")
+        logger.debug(f"Constructed URL: {url}")
+        return str(httpx.URL(url))
+
+    async def request(
+        self,
+        method: HTTPMethod,
+        **kwargs: Any,
+    ) -> Coroutine[Any, Any, Response]:
+        """Make an HTTP request.
+
+        Args:
+            method: The HTTP method to use.
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        url = self._get_url()
+
+        # Remove None values
+        request_kwargs = {k: v for k, v in kwargs.items() if v is not None}
+
+        logger.debug(f"{method.value} request to {url} with {request_kwargs!r}")
+        response = await self.client._client.request(
+            method.value, url, **request_kwargs
+        )
+        response.raise_for_status()
+        loggix(response)
+        return cast(Coroutine[Any, Any, Response], response)
+
+    async def aclose(self) -> None:
+        """Close the client."""
+        await self.client.aclose()  # pragma: no cover
+
+    async def get(self, **kwargs: Any) -> Any:
+        """Make a GET request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.GET, **kwargs)
+
+    async def post(self, **kwargs: Any) -> Any:
+        """Make a POST request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.POST, **kwargs)
+
+    async def put(self, **kwargs: Any) -> Any:
+        """Make a PUT request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.PUT, **kwargs)
+
+    async def delete(self, **kwargs: Any) -> Any:
+        """Make a DELETE request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.DELETE, **kwargs)
+
+    async def patch(self, **kwargs: Any) -> Any:
+        """Make a PATCH request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.PATCH, **kwargs)
+
+    async def head(self, **kwargs: Any) -> Any:
+        """Make a HEAD request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.HEAD, **kwargs)
+
+    async def options(self, **kwargs: Any) -> Any:
+        """Make an OPTIONS request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.OPTIONS, **kwargs)
+
+    async def trace(self, **kwargs: Any) -> Any:
+        """Make a TRACE request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.TRACE, **kwargs)
+
+    async def connect(self, **kwargs: Any) -> Any:
+        """Make a CONNECT request.
+
+        Args:
+            **kwargs: Additional keyword arguments to pass to the request.
+
+        Returns:
+            The response from the request.
+        """
+        return await self.request(HTTPMethod.CONNECT, **kwargs)
+
+
+@dataclass
+class AsyncClient:
+    """Asynchronous HTTP client.
+
+    This class allows for making HTTP requests.
+
+    Args:
+        base_url: The base URL for the client.
+        segment_format: The segment format to use.
+        known_paths: A dictionary of known paths.
+        client_kwargs: Additional keyword arguments to pass to the HTTP client.
+    """
+
+    base_url: str
+    segment_format: SegmentFormat = SegmentFormat.DEFAULT
+    known_paths: dict[str, str] = field(default_factory=dict)
+    client_kwargs: dict[str, Any] = field(default_factory=dict)
+
+    _client: httpx.AsyncClient = field(init=False)
+
+    def __post_init__(self) -> None:
+        """Initialize the HTTP client."""
+        self.client_kwargs["base_url"] = self.base_url
+        self._client = httpx.AsyncClient(**self.client_kwargs)
+
+    async def aclose(self) -> None:
+        """Close the client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        """Enter the client.
+
+        Returns:
+            The client.
+        """
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Exit the client."""
+        await self.aclose()
+
+    def __getattr__(self, name: str) -> AsyncDynamicClient:
+        """Get an attribute.
+
+        Args:
+            name: The name of the attribute.
+
+        Returns:
+            The dynamic client.
+        """
+        return AsyncDynamicClient(
+            client=self,
+            segments=[PathSegment(name=name, format=self.segment_format)],
+            segment_format=self.segment_format,
+            known_paths=self.known_paths,
+        )