axios-python 0.1.0__py3-none-any.whl

axios_python/__init__.py

@@ -0,0 +1,148 @@
+"""axios_python - A developer-experience-first HTTP client for Python.
+
+Provides an Axios-inspired interface with interceptors, middleware,
+retry, cancellation tokens, and a plugin system on top of httpx.
+
+Quick start::
+
+    import axios_python
+
+    api = axios_python.create({"base_url": "https://api.example.com"})
+    response = api.get("/users")
+    print(response.data)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from axios_python.cancel.token import CancelToken
+from axios_python.client import AxiosPython
+from axios_python.config import RequestConfig, merge_config
+from axios_python.exceptions import (
+    CancelError,
+    InterceptorError,
+    NetworkError,
+    AxiosPythonError,
+    RetryError,
+    TimeoutError,
+    HTTPStatusError,
+)
+from axios_python.plugins.auth import AuthPlugin
+from axios_python.plugins.base import Plugin
+from axios_python.plugins.cache import CachePlugin
+from axios_python.plugins.logger import LoggerPlugin
+from axios_python.request import PreparedRequest
+from axios_python.response import Response
+from axios_python.retry.strategy import (
+    ExponentialBackoff,
+    FixedDelay,
+    LinearBackoff,
+    RetryStrategy,
+)
+from axios_python.transport.base import BaseTransport
+from axios_python.transport.httpx_adapter import HttpxTransport
+
+__all__ = [
+    "create",
+    "AxiosPython",
+    "CancelToken",
+    "Response",
+    "PreparedRequest",
+    "RequestConfig",
+    "merge_config",
+    "AxiosPythonError",
+    "TimeoutError",
+    "NetworkError",
+    "CancelError",
+    "RetryError",
+    "InterceptorError",
+    "HTTPStatusError",
+    "Plugin",
+    "LoggerPlugin",
+    "CachePlugin",
+    "AuthPlugin",
+    "BaseTransport",
+    "HttpxTransport",
+    "RetryStrategy",
+    "FixedDelay",
+    "ExponentialBackoff",
+    "LinearBackoff",
+    "request",
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "async_request",
+    "async_get",
+    "async_post",
+    "async_put",
+    "async_patch",
+    "async_delete",
+]
+
+
+def create(config: dict[str, Any] | None = None, **kwargs: Any) -> AxiosPython:
+    """Create a new axios_python client instance.
+
+    This is the primary entry point for the library.
+
+    Args:
+        config: A configuration dict with keys like ``base_url``,
+            ``timeout``, ``headers``, ``params``, ``max_retries``, etc.
+        **kwargs: Additional config keys merged into *config*.
+
+    Returns:
+        A configured :class:`AxiosPython` client instance.
+
+    Example::
+
+        api = axios_python.create({
+            "base_url": "https://api.example.com",
+            "timeout": 10,
+        })
+        response = api.get("/users")
+    """
+    merged = dict(config or {})
+    merged.update(kwargs)
+    return AxiosPython(config=merged)
+
+
+_default_instance = create()
+
+def request(method: str, url: str, **kwargs: Any) -> Response:
+    return _default_instance.request(method, url, **kwargs)
+
+def get(url: str, **kwargs: Any) -> Response:
+    return _default_instance.get(url, **kwargs)
+
+def post(url: str, **kwargs: Any) -> Response:
+    return _default_instance.post(url, **kwargs)
+
+def put(url: str, **kwargs: Any) -> Response:
+    return _default_instance.put(url, **kwargs)
+
+def patch(url: str, **kwargs: Any) -> Response:
+    return _default_instance.patch(url, **kwargs)
+
+def delete(url: str, **kwargs: Any) -> Response:
+    return _default_instance.delete(url, **kwargs)
+
+async def async_request(method: str, url: str, **kwargs: Any) -> Response:
+    return await _default_instance.async_request(method, url, **kwargs)
+
+async def async_get(url: str, **kwargs: Any) -> Response:
+    return await _default_instance.async_get(url, **kwargs)
+
+async def async_post(url: str, **kwargs: Any) -> Response:
+    return await _default_instance.async_post(url, **kwargs)
+
+async def async_put(url: str, **kwargs: Any) -> Response:
+    return await _default_instance.async_put(url, **kwargs)
+
+async def async_patch(url: str, **kwargs: Any) -> Response:
+    return await _default_instance.async_patch(url, **kwargs)
+
+async def async_delete(url: str, **kwargs: Any) -> Response:
+    return await _default_instance.async_delete(url, **kwargs)

axios_python/cancel/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

axios_python/cancel/exceptions.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from axios_python.exceptions import CancelError
+
+__all__ = [
+    "CancelledError",
+]
+
+CancelledError = CancelError

axios_python/cancel/token.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Callable
+
+from axios_python.exceptions import CancelError
+
+__all__ = [
+    "CancelToken",
+]
+
+
+class CancelToken:
+    """A token used to signal request cancellation.
+
+    Create a token and pass it to a request via the ``cancel_token``
+    config key.  Call :meth:`cancel` at any time to abort the associated
+    request.
+
+    Example::
+
+        token = CancelToken()
+        api.get("/slow", cancel_token=token)
+        token.cancel()
+    """
+
+    def __init__(self) -> None:
+        self._cancelled: bool = False
+        self._reason: str = "Request cancelled"
+        self._callbacks: list[Callable[[], None]] = []
+
+    @property
+    def is_cancelled(self) -> bool:
+        """Return True if the token has been cancelled."""
+        return self._cancelled
+
+    @property
+    def reason(self) -> str:
+        """Return the cancellation reason string."""
+        return self._reason
+
+    def cancel(self, reason: str = "Request cancelled") -> None:
+        """Cancel the token, firing all registered callbacks.
+
+        Args:
+            reason: A human-readable reason for the cancellation.
+        """
+        if self._cancelled:
+            return
+        self._cancelled = True
+        self._reason = reason
+        for cb in self._callbacks:
+            cb()
+
+    def on_cancel(self, callback: Callable[[], None]) -> None:
+        """Register a callback to fire when the token is cancelled.
+
+        If the token is already cancelled, the callback fires immediately.
+
+        Args:
+            callback: A zero-argument callable.
+        """
+        if self._cancelled:
+            callback()
+            return
+        self._callbacks.append(callback)
+
+    def raise_if_cancelled(self) -> None:
+        """Raise ``CancelError`` if the token has been cancelled.
+
+        Raises:
+            CancelError: If the token was previously cancelled.
+        """
+        if self._cancelled:
+            raise CancelError(self._reason)

axios_python/client.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from axios_python.cancel.token import CancelToken
+from axios_python.config import merge_config
+from axios_python.interceptors.manager import InterceptorManager
+from axios_python.middleware.manager import MiddlewareManager
+from axios_python.plugins.base import Plugin
+from axios_python.request import PreparedRequest
+from axios_python.response import Response
+from axios_python.retry.engine import RetryEngine
+from axios_python.retry.strategy import RetryStrategy
+from axios_python.transport.base import BaseTransport
+from axios_python.transport.httpx_adapter import HttpxTransport
+from axios_python.utils.async_utils import run_sync
+
+__all__ = [
+    "AxiosPython",
+]
+
+MiddlewareFn = Callable[[dict[str, Any], Callable[..., Awaitable[Any]]], Awaitable[Any]]
+
+
+class AxiosPython:
+    """The main axios_python HTTP client.
+
+    Each instance maintains its own configuration, interceptors, middleware
+    stack, and transport.  Create instances via :func:`axios_python.create`.
+
+    Args:
+        config: Base configuration dict applied to every request made
+            through this instance.
+        transport: An optional custom transport adapter.  Defaults to
+            :class:`~axios_python.transport.httpx_adapter.HttpxTransport`.
+    """
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        transport: BaseTransport | None = None,
+    ) -> None:
+        self._config: dict[str, Any] = config or {}
+        self._transport: BaseTransport = transport or HttpxTransport()
+        self._interceptors: InterceptorManager = InterceptorManager()
+        self._middleware: MiddlewareManager = MiddlewareManager()
+        self._plugins: list[Plugin] = []
+
+    @property
+    def interceptors(self) -> InterceptorManager:
+        """Access request and response interceptor chains."""
+        return self._interceptors
+
+    @property
+    def defaults(self) -> dict[str, Any]:
+        """The base configuration for this client instance."""
+        return self._config
+
+    def use(self, middleware: MiddlewareFn) -> AxiosPython:
+        """Register a middleware function.
+
+        Args:
+            middleware: An async callable with signature
+                ``(ctx, next) -> Any``.
+
+        Returns:
+            This client instance for chaining.
+        """
+        self._middleware.use(middleware)
+        return self
+
+    def plugin(self, p: Plugin) -> AxiosPython:
+        """Install a plugin onto this client.
+
+        Args:
+            p: A plugin implementing the :class:`~axios_python.plugins.base.Plugin`
+                protocol.
+
+        Returns:
+            This client instance for chaining.
+        """
+        p.install(self)
+        self._plugins.append(p)
+        return self
+
+    def _build_request_config(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        per_request: dict[str, Any] = {"method": method, "url": url}
+        per_request.update(kwargs)
+        return merge_config(self._config, per_request)
+
+    def _resolve_url(self, config: dict[str, Any]) -> str:
+        base = config.get("base_url", "").rstrip("/")
+        path = config.get("url", "")
+        if path.startswith(("http://", "https://")):
+            return path
+        return f"{base}/{path.lstrip('/')}" if base else path
+
+    def _prepare_request(self, config: dict[str, Any]) -> PreparedRequest:
+        return PreparedRequest(
+            method=config.get("method", "GET").upper(),
+            url=self._resolve_url(config),
+            headers=dict(config.get("headers", {})),
+            params=dict(config.get("params", {})),
+            data=config.get("data"),
+            json=config.get("json"),
+            files=config.get("files"),
+            stream=config.get("stream", False),
+            timeout=config.get("timeout", 30),
+        )
+
+    def _build_retry_engine(self, config: dict[str, Any]) -> RetryEngine:
+        return RetryEngine(
+            max_retries=config.get("max_retries", 0),
+            strategy=config.get("retry_strategy"),
+            retry_on=config.get("retry_on"),
+        )
+
+    def _execute_sync(self, config: dict[str, Any]) -> Response:
+        cancel_token: CancelToken | None = config.get("cancel_token")
+
+        if cancel_token is not None:
+            cancel_token.raise_if_cancelled()
+
+        config = self._interceptors.request.run(config)
+
+        prepared = self._prepare_request(config)
+        retry = self._build_retry_engine(config)
+
+        def transport_call() -> Response:
+            if cancel_token is not None:
+                cancel_token.raise_if_cancelled()
+            return self._transport.send(prepared)
+
+        response = retry.execute(transport_call)
+        response = self._interceptors.response.run(response)
+        return response
+
+    async def _execute_async(self, config: dict[str, Any]) -> Response:
+        cancel_token: CancelToken | None = config.get("cancel_token")
+
+        if cancel_token is not None:
+            cancel_token.raise_if_cancelled()
+
+        config = await self._interceptors.request.run_async(config)
+
+        prepared = self._prepare_request(config)
+        retry = self._build_retry_engine(config)
+
+        async def transport_call() -> Response:
+            if cancel_token is not None:
+                cancel_token.raise_if_cancelled()
+            return await self._transport.send_async(prepared)
+
+        response = await retry.execute_async(transport_call)
+        response = await self._interceptors.response.run_async(response)
+        return response
+
+    async def _dispatch_async(self, config: dict[str, Any]) -> Response:
+        if len(self._middleware) > 0:
+            async def final(ctx: dict[str, Any]) -> Response:
+                return await self._execute_async(ctx)
+            return await self._middleware.execute(config, final)
+        return await self._execute_async(config)
+
+    def _dispatch_sync(self, config: dict[str, Any]) -> Response:
+        if config.get("stream"):
+            if len(self._middleware) > 0:
+                raise RuntimeError("Async middleware cannot be used with synchronous stream=True requests. Use async_get() instead.")
+            return self._execute_sync(config)
+        return run_sync(self._dispatch_async(config))
+
+    def request(self, method: str, url: str, **kwargs: Any) -> Response:
+        """Send a synchronous HTTP request.
+
+        Args:
+            method: The HTTP method (GET, POST, PUT, etc.).
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides (headers, params, data,
+                json, timeout, cancel_token, etc.).
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        config = self._build_request_config(method, url, **kwargs)
+        return self._dispatch_sync(config)
+
+    async def async_request(self, method: str, url: str, **kwargs: Any) -> Response:
+        """Send an asynchronous HTTP request.
+
+        Args:
+            method: The HTTP method (GET, POST, PUT, etc.).
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides (headers, params, data,
+                json, timeout, cancel_token, etc.).
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        config = self._build_request_config(method, url, **kwargs)
+        return await self._dispatch_async(config)
+
+    def get(self, url: str, **kwargs: Any) -> Response:
+        """Send a synchronous GET request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return self.request("GET", url, **kwargs)
+
+    async def async_get(self, url: str, **kwargs: Any) -> Response:
+        """Send an asynchronous GET request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return await self.async_request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> Response:
+        """Send a synchronous POST request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return self.request("POST", url, **kwargs)
+
+    async def async_post(self, url: str, **kwargs: Any) -> Response:
+        """Send an asynchronous POST request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return await self.async_request("POST", url, **kwargs)
+
+    def put(self, url: str, **kwargs: Any) -> Response:
+        """Send a synchronous PUT request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return self.request("PUT", url, **kwargs)
+
+    async def async_put(self, url: str, **kwargs: Any) -> Response:
+        """Send an asynchronous PUT request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return await self.async_request("PUT", url, **kwargs)
+
+    def patch(self, url: str, **kwargs: Any) -> Response:
+        """Send a synchronous PATCH request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return self.request("PATCH", url, **kwargs)
+
+    async def async_patch(self, url: str, **kwargs: Any) -> Response:
+        """Send an asynchronous PATCH request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return await self.async_request("PATCH", url, **kwargs)
+
+    def delete(self, url: str, **kwargs: Any) -> Response:
+        """Send a synchronous DELETE request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return self.request("DELETE", url, **kwargs)
+
+    async def async_delete(self, url: str, **kwargs: Any) -> Response:
+        """Send an asynchronous DELETE request.
+
+        Args:
+            url: The URL path or full URL.
+            **kwargs: Additional config overrides.
+
+        Returns:
+            A :class:`~axios_python.response.Response` object.
+        """
+        return await self.async_request("DELETE", url, **kwargs)
+
+    def close(self) -> None:
+        """Release all resources held by this client."""
+        self._transport.close()
+
+    async def aclose(self) -> None:
+        """Release all resources held by this client asynchronously."""
+        await self._transport.aclose()
+
+    def __repr__(self) -> str:
+        base = self._config.get("base_url", "")
+        return f"<AxiosPython base_url={base!r}>"
+
+    def __enter__(self) -> AxiosPython:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> AxiosPython:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

axios_python/config.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+from axios_python.defaults import DEFAULT_CONFIG
+from axios_python.utils.merge import deep_merge
+
+__all__ = [
+    "RequestConfig",
+    "merge_config",
+]
+
+
+class RequestConfig(TypedDict, total=False):
+    """Configuration options for a single request."""
+
+    method: str
+    url: str
+    base_url: str
+    headers: dict[str, str]
+    params: dict[str, Any]
+    data: Any
+    json: Any
+    files: Any
+    stream: bool
+    timeout: int | float
+    max_retries: int
+    retry_strategy: Any
+    retry_on: Any
+    cancel_token: Any
+
+
+def merge_config(*configs: dict[str, Any]) -> dict[str, Any]:
+    """Merge multiple configuration dicts with later values taking precedence.
+
+    Args:
+        *configs: Configuration dictionaries to merge, ordered from lowest
+            to highest priority.
+
+    Returns:
+        A new merged configuration dictionary.
+    """
+    result: dict[str, Any] = deep_merge({}, DEFAULT_CONFIG)
+    for cfg in configs:
+        if cfg:
+            result = deep_merge(result, cfg)
+    return result

axios_python/defaults.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_HEADERS",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_CONFIG",
+]
+
+DEFAULT_TIMEOUT: int | float = 30
+
+DEFAULT_HEADERS: dict[str, str] = {
+    "Accept": "application/json, text/plain, */*",
+}
+
+DEFAULT_MAX_RETRIES: int = 0
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "base_url": "",
+    "timeout": DEFAULT_TIMEOUT,
+    "headers": dict(DEFAULT_HEADERS),
+    "params": {},
+    "max_retries": DEFAULT_MAX_RETRIES,
+}

axios_python/exceptions.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+__all__ = [
+    "AxiosPythonError",
+    "TimeoutError",
+    "NetworkError",
+    "CancelError",
+    "RetryError",
+    "InterceptorError",
+    "HTTPStatusError",
+]
+
+
+class AxiosPythonError(Exception):
+    """Base exception for all axios_python errors."""
+
+
+class TimeoutError(AxiosPythonError):
+    """Raised when a request exceeds the configured timeout."""
+
+
+class NetworkError(AxiosPythonError):
+    """Raised when a network-level failure occurs."""
+
+
+class CancelError(AxiosPythonError):
+    """Raised when a request is cancelled via a CancelToken."""
+
+
+class RetryError(AxiosPythonError):
+    """Raised when all retry attempts have been exhausted."""
+
+    def __init__(self, message: str, last_exception: Exception | None = None) -> None:
+        super().__init__(message)
+        self.last_exception = last_exception
+
+
+class InterceptorError(AxiosPythonError):
+    """Raised when an interceptor fails during execution."""
+
+
+class HTTPStatusError(AxiosPythonError):
+    """Raised when a response indicates an HTTP error (4xx or 5xx)."""
+
+    def __init__(self, message: str, response: Any) -> None:
+        super().__init__(message)
+        self.response = response