axios-python 0.1.0__py3-none-any.whl

axios_python/interceptors/__init__.py

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

axios_python/interceptors/chain.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from axios_python.exceptions import InterceptorError
+
+__all__ = [
+    "InterceptorChain",
+]
+
+HandlerFn = Callable[[Any], Any]
+ErrorHandlerFn = Callable[[Exception], Any]
+
+
+class InterceptorChain:
+    """An ordered sequence of interceptor handler pairs.
+
+    Each entry is a ``(fulfilled, rejected)`` tuple.  During execution the
+    chain pipes the value through each *fulfilled* handler in order.  If any
+    handler raises, the corresponding *rejected* handler (if provided) is
+    called, otherwise the exception propagates.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: list[tuple[int, HandlerFn, ErrorHandlerFn | None]] = []
+        self._next_id: int = 0
+
+    def use(
+        self,
+        fulfilled: HandlerFn,
+        rejected: ErrorHandlerFn | None = None,
+    ) -> int:
+        """Register a new interceptor handler pair.
+
+        Args:
+            fulfilled: Called with the current value when the chain succeeds.
+            rejected: Called with the exception when a prior handler raises.
+
+        Returns:
+            An integer id that can be passed to :meth:`eject`.
+        """
+        handler_id = self._next_id
+        self._next_id += 1
+        self._handlers.append((handler_id, fulfilled, rejected))
+        return handler_id
+
+    def eject(self, handler_id: int) -> None:
+        """Remove a previously registered interceptor by its id.
+
+        Args:
+            handler_id: The id returned by :meth:`use`.
+        """
+        self._handlers = [
+            h for h in self._handlers if h[0] != handler_id
+        ]
+
+    def run(self, initial: Any) -> Any:
+        """Execute the chain synchronously.
+
+        Args:
+            initial: The starting value passed to the first handler.
+
+        Returns:
+            The value produced by the final handler.
+
+        Raises:
+            InterceptorError: If a handler raises and no rejected handler
+                catches the error.
+        """
+        value = initial
+        for _, fulfilled, rejected in self._handlers:
+            try:
+                value = fulfilled(value)
+            except Exception as exc:
+                if rejected is not None:
+                    value = rejected(exc)
+                else:
+                    raise InterceptorError(str(exc)) from exc
+        return value
+
+    async def run_async(self, initial: Any) -> Any:
+        """Execute the chain asynchronously.
+
+        Await handlers that return coroutines.
+
+        Args:
+            initial: The starting value passed to the first handler.
+
+        Returns:
+            The value produced by the final handler.
+
+        Raises:
+            InterceptorError: If a handler raises and no rejected handler
+                catches the error.
+        """
+        import inspect
+
+        value = initial
+        for _, fulfilled, rejected in self._handlers:
+            try:
+                result = fulfilled(value)
+                if inspect.isawaitable(result):
+                    value = await result
+                else:
+                    value = result
+            except Exception as exc:
+                if rejected is not None:
+                    result = rejected(exc)
+                    if inspect.isawaitable(result):
+                        value = await result
+                    else:
+                        value = result
+                else:
+                    raise InterceptorError(str(exc)) from exc
+        return value
+
+    def __len__(self) -> int:
+        return len(self._handlers)

axios_python/interceptors/manager.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from axios_python.interceptors.chain import InterceptorChain
+
+__all__ = [
+    "InterceptorManager",
+]
+
+HandlerFn = Callable[[Any], Any]
+ErrorHandlerFn = Callable[[Exception], Any]
+
+
+class InterceptorManager:
+    """Manages request and response interceptor chains.
+
+    Access via ``client.interceptors.request`` and
+    ``client.interceptors.response``.
+
+    Example::
+
+        api.interceptors.request.use(lambda cfg: cfg)
+        api.interceptors.response.use(lambda res: res)
+    """
+
+    def __init__(self) -> None:
+        self.request: InterceptorChain = InterceptorChain()
+        self.response: InterceptorChain = InterceptorChain()

axios_python/middleware/__init__.py

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

axios_python/middleware/manager.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from axios_python.middleware.pipeline import Pipeline
+
+__all__ = [
+    "MiddlewareManager",
+]
+
+MiddlewareFn = Callable[[dict[str, Any], Callable[..., Awaitable[Any]]], Awaitable[Any]]
+FinalHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+
+
+class MiddlewareManager:
+    """Manages the middleware pipeline for a client instance.
+
+    Example::
+
+        async def timing(ctx, next):
+            import time
+            start = time.monotonic()
+            result = await next(ctx)
+            ctx["elapsed"] = time.monotonic() - start
+            return result
+
+        api.use(timing)
+    """
+
+    def __init__(self) -> None:
+        self._pipeline: Pipeline = Pipeline()
+
+    def use(self, fn: MiddlewareFn) -> None:
+        """Register a middleware function.
+
+        Args:
+            fn: An async callable with signature ``(ctx, next) -> Any``.
+        """
+        self._pipeline.use(fn)
+
+    async def execute(self, ctx: dict[str, Any], final: FinalHandler) -> Any:
+        """Execute the full middleware stack, terminating with *final*.
+
+        Args:
+            ctx: A mutable context dict.
+            final: The terminal handler.
+
+        Returns:
+            The result produced by the pipeline.
+        """
+        return await self._pipeline.execute(ctx, final)
+
+    def __len__(self) -> int:
+        return len(self._pipeline)

axios_python/middleware/pipeline.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+__all__ = [
+    "Pipeline",
+]
+
+MiddlewareFn = Callable[[dict[str, Any], Callable[..., Awaitable[Any]]], Awaitable[Any]]
+FinalHandler = Callable[[dict[str, Any]], Awaitable[Any]]
+
+
+class Pipeline:
+    """Express-style middleware pipeline.
+
+    Middleware functions have the signature::
+
+        async def my_middleware(ctx: dict, next: Callable) -> Any:
+            # pre-processing
+            result = await next(ctx)
+            # post-processing
+            return result
+
+    The pipeline composes all registered middleware into a single callable
+    that terminates in a *final handler*.
+    """
+
+    def __init__(self) -> None:
+        self._stack: list[MiddlewareFn] = []
+
+    def use(self, fn: MiddlewareFn) -> None:
+        """Add a middleware function to the pipeline.
+
+        Args:
+            fn: An async callable with signature ``(ctx, next) -> Any``.
+        """
+        self._stack.append(fn)
+
+    async def execute(self, ctx: dict[str, Any], final: FinalHandler) -> Any:
+        """Run the pipeline and terminate with *final*.
+
+        Args:
+            ctx: A mutable context dict shared across all middleware.
+            final: The terminal handler invoked after all middleware.
+
+        Returns:
+            The result produced by the pipeline.
+        """
+        index = -1
+
+        async def dispatch(i: int, c: dict[str, Any]) -> Any:
+            nonlocal index
+            if i <= index:
+                raise RuntimeError("next() called multiple times")
+            index = i
+            if i < len(self._stack):
+                mw = self._stack[i]
+
+                async def next_fn(updated_ctx: dict[str, Any] | None = None) -> Any:
+                    return await dispatch(i + 1, updated_ctx if updated_ctx is not None else c)
+
+                return await mw(c, next_fn)
+            return await final(c)
+
+        return await dispatch(0, ctx)
+
+    def __len__(self) -> int:
+        return len(self._stack)

axios_python/plugins/__init__.py

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

axios_python/plugins/auth.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from axios_python.client import AxiosPython
+
+__all__ = [
+    "AuthPlugin",
+]
+
+
+class AuthPlugin:
+    """Plugin that injects an Authorization header into every request.
+
+    Supports static tokens and dynamic token providers.
+
+    Args:
+        token: A static bearer token string.
+        token_provider: A callable that returns a token string at call
+            time (takes precedence over *token* if both are provided).
+        scheme: The authorization scheme (default: ``"Bearer"``).
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        token_provider: Callable[[], str] | None = None,
+        scheme: str = "Bearer",
+    ) -> None:
+        self._token = token
+        self._token_provider = token_provider
+        self._scheme = scheme
+
+    def install(self, client: AxiosPython) -> None:
+        """Register a request interceptor that sets the Authorization header.
+
+        Args:
+            client: The AxiosPython client to extend.
+        """
+        client.interceptors.request.use(self._inject_auth)
+
+    def _inject_auth(self, config: dict[str, Any]) -> dict[str, Any]:
+        token = self._token_provider() if self._token_provider else self._token
+        if token:
+            headers = dict(config.get("headers", {}))
+            headers["Authorization"] = f"{self._scheme} {token}"
+            config["headers"] = headers
+        return config

axios_python/plugins/base.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from axios_python.client import AxiosPython
+
+__all__ = [
+    "Plugin",
+]
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    """Protocol that all axios_python plugins must implement.
+
+    A plugin receives the client instance during installation and may
+    register interceptors, middleware, or perform other setup.
+    """
+
+    def install(self, client: AxiosPython) -> None:
+        """Install this plugin onto a client instance.
+
+        Args:
+            client: The AxiosPython client to extend.
+        """
+        ...

axios_python/plugins/cache.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+if TYPE_CHECKING:
+    from axios_python.client import AxiosPython
+
+__all__ = [
+    "CachePlugin",
+]
+
+
+class CachePlugin:
+    """In-memory TTL cache plugin for GET requests.
+
+    Caches responses in memory keyed by full URL.  Only GET requests
+    are cached.
+
+    Args:
+        ttl: Time-to-live in seconds for cached entries.
+        max_size: Maximum number of cached entries.
+    """
+
+    def __init__(self, ttl: float = 60.0, max_size: int = 128) -> None:
+        self._ttl = ttl
+        self._max_size = max_size
+        self._store: dict[str, tuple[float, Any]] = {}
+
+    def install(self, client: AxiosPython) -> None:
+        """Register a cache middleware on the client.
+
+        Args:
+            client: The AxiosPython client to extend.
+        """
+        plugin = self
+
+        async def cache_middleware(
+            ctx: dict[str, Any],
+            next_fn: Callable[..., Awaitable[Any]],
+        ) -> Any:
+            method = ctx.get("method", "GET").upper()
+            if method != "GET":
+                return await next_fn(ctx)
+
+            url = ctx.get("url", "")
+            cached = plugin._get(url)
+            if cached is not None:
+                return cached
+
+            result = await next_fn(ctx)
+            plugin._set(url, result)
+            return result
+
+        client.use(cache_middleware)
+
+    def _get(self, key: str) -> Any | None:
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        ts, value = entry
+        if time.monotonic() - ts > self._ttl:
+            del self._store[key]
+            return None
+        return value
+
+    def _set(self, key: str, value: Any) -> None:
+        if len(self._store) >= self._max_size:
+            oldest_key = next(iter(self._store))
+            del self._store[oldest_key]
+        self._store[key] = (time.monotonic(), value)
+
+    def clear(self) -> None:
+        """Remove all entries from the cache."""
+        self._store.clear()

axios_python/plugins/logger.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from axios_python.client import AxiosPython
+
+__all__ = [
+    "LoggerPlugin",
+]
+
+_logger = logging.getLogger("axios_python")
+
+
+class LoggerPlugin:
+    """Plugin that logs outgoing requests and incoming responses.
+
+    Args:
+        level: The logging level to use (default: ``logging.DEBUG``).
+        logger: An optional custom logger instance.
+    """
+
+    def __init__(
+        self,
+        level: int = logging.DEBUG,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._level = level
+        self._logger = logger or _logger
+
+    def install(self, client: AxiosPython) -> None:
+        """Register request and response interceptors for logging.
+
+        Args:
+            client: The AxiosPython client to extend.
+        """
+        client.interceptors.request.use(self._log_request)
+        client.interceptors.response.use(self._log_response)
+
+    def _log_request(self, config: dict[str, Any]) -> dict[str, Any]:
+        self._logger.log(
+            self._level,
+            "%s %s",
+            config.get("method", "GET").upper(),
+            config.get("url", ""),
+        )
+        return config
+
+    def _log_response(self, response: Any) -> Any:
+        self._logger.log(
+            self._level,
+            "Response %s %s",
+            getattr(response, "status_code", "?"),
+            getattr(response, "request", None),
+        )
+        return response

axios_python/request.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "PreparedRequest",
+]
+
+
+@dataclass
+class PreparedRequest:
+    """An immutable snapshot of a fully resolved HTTP request."""
+
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    params: dict[str, Any] = field(default_factory=dict)
+    data: Any = None
+    json: Any = None
+    files: Any = None
+    stream: bool = False
+    timeout: int | float = 30

axios_python/response.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Iterator
+
+from axios_python.request import PreparedRequest
+
+__all__ = [
+    "Response",
+]
+
+
+class Response:
+    """Wraps a raw HTTP response with a convenient interface.
+
+    Attributes:
+        status_code: The HTTP status code.
+        headers: Response headers as a dict.
+        data: The decoded response body.
+        request: The original PreparedRequest that produced this response.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        headers: dict[str, str],
+        data: Any,
+        request: PreparedRequest,
+        raw: Any = None,
+    ) -> None:
+        self.status_code = status_code
+        self.headers = headers
+        self.data = data
+        self.request = request
+        self._raw = raw
+
+    @property
+    def ok(self) -> bool:
+        """True if the status code indicates success (2xx)."""
+        return 200 <= self.status_code < 300
+
+    @property
+    def text(self) -> str:
+        """The response body as a string."""
+        if self.data is None:
+            try:
+                self.read()
+            except Exception:
+                pass
+        if isinstance(self.data, str):
+            return self.data
+        if isinstance(self.data, bytes):
+            return self.data.decode("utf-8", errors="replace")
+        return str(self.data) if self.data is not None else ""
+
+    def json(self) -> Any:
+        """Parse the response body as JSON.
+
+        Returns:
+            The parsed JSON data. If the body is already a dict or list,
+            it is returned directly.
+        """
+        if isinstance(self.data, (dict, list)):
+            return self.data
+        import json as _json
+        return _json.loads(self.text)
+
+    def raise_for_status(self) -> Response:
+        """Raises HTTPStatusError if one occurred.
+        
+        Returns:
+            The response object.
+        """
+        if not self.ok:
+            from axios_python.exceptions import HTTPStatusError
+            reason = getattr(self._raw, "reason_phrase", "Unknown Reason")
+            message = f"{self.status_code} {reason} for url: {self.request.url}"
+            raise HTTPStatusError(message, response=self)
+        return self
+
+    def iter_bytes(self, chunk_size: int | None = None) -> Iterator[bytes]:
+        """Iterate over the response body in bytes."""
+        return self._raw.iter_bytes(chunk_size=chunk_size)
+
+    def iter_text(self, chunk_size: int | None = None) -> Iterator[str]:
+        """Iterate over the response body in text."""
+        return self._raw.iter_text(chunk_size=chunk_size)
+
+    def iter_lines(self) -> Iterator[str]:
+        """Iterate over the response body line by line."""
+        return self._raw.iter_lines()
+
+    def aiter_bytes(self, chunk_size: int | None = None) -> AsyncIterator[bytes]:
+        """Asynchronously iterate over the response body in bytes."""
+        return self._raw.aiter_bytes(chunk_size=chunk_size)
+
+    def aiter_text(self, chunk_size: int | None = None) -> AsyncIterator[str]:
+        """Asynchronously iterate over the response body in text."""
+        return self._raw.aiter_text(chunk_size=chunk_size)
+
+    def aiter_lines(self) -> AsyncIterator[str]:
+        """Asynchronously iterate over the response body line by line."""
+        return self._raw.aiter_lines()
+
+    def read(self) -> bytes:
+        """Read the entire response body in bytes."""
+        self.data = self._raw.read()
+        return self.data
+
+    async def aread(self) -> bytes:
+        """Asynchronously read the entire response body in bytes."""
+        self.data = await self._raw.aread()
+        return self.data
+
+    def close(self) -> None:
+        """Close the underlying HTTP response stream."""
+        if self._raw is not None:
+            self._raw.close()
+
+    async def aclose(self) -> None:
+        """Asynchronously close the underlying HTTP response stream."""
+        if self._raw is not None:
+            await self._raw.aclose()
+            
+    def __enter__(self) -> Response:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> Response:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"<Response [{self.status_code}]>"

axios_python/retry/__init__.py

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