apiroute 1.0.0__py3-none-any.whl

apiroute/__init__.py

@@ -0,0 +1,57 @@
+"""Build API clients declaratively: one @route per endpoint, safe defaults, httpx underneath."""
+
+from apiroute.api_route_error import ApiRouteError
+from apiroute.argument_targets import Body, Header, Query
+from apiroute.client import Client
+from apiroute.from_client import FROM_CLIENT
+from apiroute.namespace import namespace
+from apiroute.request_spec import RequestSpec
+from apiroute.response_validation_error import ResponseValidationError
+from apiroute.result import Result
+from apiroute.retries import Retries
+from apiroute.route import route
+from apiroute.route_definition_error import RouteDefinitionError
+from apiroute.section import Section
+from apiroute.transport_configuration import aclose_transports, close_transports, use_transport
+from apiroute.transports import (
+    AsyncHttpxClientTransport,
+    AsyncOneShotTransport,
+    AsyncPooledTransport,
+    AsyncTransport,
+    HttpxClientTransport,
+    OneShotTransport,
+    PooledTransport,
+    ThreadLocalTransport,
+    Transport,
+)
+from apiroute.unexpected_response import UnexpectedResponse
+
+__all__ = [
+    "AsyncHttpxClientTransport",
+    "AsyncOneShotTransport",
+    "AsyncPooledTransport",
+    "AsyncTransport",
+    "Body",
+    "Client",
+    "FROM_CLIENT",
+    "ApiRouteError",
+    "Header",
+    "HttpxClientTransport",
+    "OneShotTransport",
+    "PooledTransport",
+    "Query",
+    "RequestSpec",
+    "ResponseValidationError",
+    "Result",
+    "Retries",
+    "RouteDefinitionError",
+    "Section",
+    "ThreadLocalTransport",
+    "Transport",
+    "UnexpectedResponse",
+    "aclose_transports",
+    "close_transports",
+    "namespace",
+    "route",
+    "use_transport",
+]

apiroute/api_route_error.py

@@ -0,0 +1,2 @@
+class ApiRouteError(Exception):
+    """Base class for every error this library raises."""

apiroute/argument_targets.py

@@ -0,0 +1,33 @@
+class ArgumentTarget:
+    """Marks a route parameter that no {placeholder} names, saying where its value goes.
+
+    Use the class (`state: Query`) or an instance with a name (`sort: Query("sort_by")`),
+    or inside Annotated (`state: Annotated[str | None, Query()] = None`).
+    """
+
+    location = ""
+
+    def __init__(self, name: str | None = None):
+        self.name = name
+
+    def key_for(self, param_name: str) -> str:
+        return self.name or param_name
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.name!r})"
+
+
+class Query(ArgumentTarget):
+    location = "query"
+
+
+class Header(ArgumentTarget):
+    location = "header"
+
+    def key_for(self, param_name: str) -> str:
+        """trace_id becomes Trace-Id unless a header name was given."""
+        return self.name or "-".join(part.capitalize() for part in param_name.split("_"))
+
+
+class Body(ArgumentTarget):
+    location = "body"

apiroute/async_chunk_iterator.py

@@ -0,0 +1,35 @@
+from contextlib import AsyncExitStack
+from typing import Any
+
+import httpx
+
+
+class AsyncChunkIterator:
+    """The async counterpart of ChunkIterator, returned by stream="iter" routes through .aio.
+
+    Use it in an async with block to be sure the connection closes when you stop early.
+    """
+
+    def __init__(self, response: httpx.Response, stack: AsyncExitStack):
+        self.response = response
+        self._chunks = response.aiter_bytes()
+        self._stack = stack
+
+    def __aiter__(self) -> "AsyncChunkIterator":
+        return self
+
+    async def __anext__(self) -> bytes:
+        try:
+            return await self._chunks.__anext__()
+        except BaseException:
+            await self.aclose()
+            raise
+
+    async def aclose(self) -> None:
+        await self._stack.aclose()
+
+    async def __aenter__(self) -> "AsyncChunkIterator":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()

apiroute/async_retry_runner.py

@@ -0,0 +1,26 @@
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+from apiroute.retry_policy import RetryPolicy
+
+T = TypeVar("T")
+
+
+class AsyncRetryRunner:
+    """The async retry loop: awaits each attempt and sleeps without blocking the event loop."""
+
+    def __init__(self, policy: RetryPolicy, sleep: Callable[[float], Awaitable[Any]]):
+        self._policy = policy
+        self._sleep = sleep
+
+    async def run(self, attempt: Callable[[], Awaitable[T]]) -> T:
+        number = 1
+        while True:
+            try:
+                return await attempt()
+            except Exception as error:
+                delay = self._policy.delay_before_retry(error, number)
+                if delay is None:
+                    raise
+            await self._sleep(delay)
+            number += 1

apiroute/base_url_validator.py

@@ -0,0 +1,15 @@
+from urllib.parse import urlsplit
+
+# Only web URLs, to keep a misconfigured base_url from reaching file:, gopher: and the like
+ALLOWED_URL_SCHEMES = ("http", "https")
+
+
+def validate_base_url(url: str) -> None:
+    parts = urlsplit(str(url))
+    if parts.scheme.lower() not in ALLOWED_URL_SCHEMES:
+        raise ValueError(
+            f"invalid base_url scheme {parts.scheme!r} in {url!r}; "
+            f"allowed: {', '.join(ALLOWED_URL_SCHEMES)}"
+        )
+    if not parts.hostname:
+        raise ValueError(f"invalid base_url {url!r}: it has no host")

apiroute/body_encoder.py

@@ -0,0 +1,25 @@
+import json
+from typing import Any
+from urllib.parse import urlencode
+
+from apiroute.query_encoder import QueryEncoder
+
+BODY_FORMATS = ("json", "form")
+
+
+class BodyEncoder:
+    """Serializes a route's body data according to the class's body_format."""
+
+    def __init__(self, body_format: Any):
+        self._format = body_format
+
+    def encode(self, client: Any, data: Any) -> tuple[bytes | str, str | None]:
+        """Returns the content and the Content-Type it implies (None when it implies none)."""
+        if isinstance(data, (str, bytes)):
+            return data, None
+        if callable(self._format):
+            return self._format(client, data), None
+        if self._format == "form":
+            pairs = QueryEncoder("nested").encode(data)
+            return urlencode(pairs), "application/x-www-form-urlencoded"
+        return json.dumps(data).encode(), "application/json"

apiroute/chunk_iterator.py

@@ -0,0 +1,36 @@
+from contextlib import ExitStack
+from typing import Any
+
+import httpx
+
+
+class ChunkIterator:
+    """A streamed response body, chunk by chunk (what a stream="iter" route returns).
+
+    The connection stays open until the chunks run out or close() is called; use it in a
+    with block to be sure it closes when you stop early.
+    """
+
+    def __init__(self, response: httpx.Response, stack: ExitStack):
+        self.response = response
+        self._chunks = response.iter_bytes()
+        self._stack = stack
+
+    def __iter__(self) -> "ChunkIterator":
+        return self
+
+    def __next__(self) -> bytes:
+        try:
+            return next(self._chunks)
+        except BaseException:
+            self.close()
+            raise
+
+    def close(self) -> None:
+        self._stack.close()
+
+    def __enter__(self) -> "ChunkIterator":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()

apiroute/client.py

@@ -0,0 +1,85 @@
+import asyncio
+import time
+from dataclasses import replace
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from apiroute.base_url_validator import validate_base_url
+from apiroute.client_config import ClientConfig
+from apiroute.request_spec import RequestSpec
+from apiroute.router import Router
+from apiroute.transport_configuration import ASYNC_TRANSPORTS, TRANSPORTS, is_async_transport
+from apiroute.transports.async_transport import AsyncTransport
+from apiroute.transports.transport import Transport
+
+# Network failures worth another attempt; other errors (bad URL, TLS) won't fix themselves
+RETRYABLE_ERRORS = (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError)
+
+
+class Client(Router):
+    """Base class for an API client. Configure it with class attributes and @route methods.
+
+    The class describes the API only. How requests are sent is a Transport, chosen for the
+    environment with apiroute.use_transport() or, for one instance, the transport and
+    async_transport arguments. Async calls go through client.aio.
+    """
+
+    last_response: httpx.Response | None = None
+
+    # Class-level defaults, so a subclass that skips super().__init__() still works
+    _base_url: str | None = None
+    _transport: Transport | None = None
+    _async_transport: AsyncTransport | None = None
+    _sleep = staticmethod(time.sleep)
+    _async_sleep = staticmethod(asyncio.sleep)
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        transport: Transport | None = None,
+        async_transport: AsyncTransport | None = None,
+    ):
+        if base_url is not None:
+            validate_base_url(base_url)
+        if transport is not None and is_async_transport(transport):
+            raise TypeError("transport is async; pass it as async_transport")
+        if async_transport is not None and not is_async_transport(async_transport):
+            raise TypeError("async_transport is not async; pass it as transport")
+        self._base_url = base_url
+        self._transport = transport
+        self._async_transport = async_transport
+
+    def should_retry(self, error: Exception, attempt: int) -> bool:
+        """Override to retry other errors, e.g. an UnexpectedResponse with status 503."""
+        return isinstance(error, RETRYABLE_ERRORS)
+
+    def on_request(self, request: RequestSpec) -> RequestSpec | None:
+        """Runs before every attempt, sync or async. Return a changed request, e.g. one with a
+        signature header added through dataclasses.replace, or None to send it as is."""
+        return None
+
+    def on_response(self, request: RequestSpec, response: httpx.Response, elapsed: float) -> None:
+        """Runs after every response, whatever its status, with the seconds it took; for a
+        stream, once the status is in and before the body is read. Use it for metrics or
+        logging. Network errors don't reach it; they are logged by the retry policy."""
+
+    def escape_path(self, value: Any) -> str:
+        """Every path value is escaped so it stays one segment; override to allow '/'."""
+        return quote(str(value), safe="")
+
+    @property
+    def _root(self) -> "Client":
+        return self
+
+    def _request_config(self) -> ClientConfig:
+        config = type(self)._config
+        return config if self._base_url is None else replace(config, base_url=self._base_url)
+
+    def _http_transport(self) -> Transport:
+        return self._transport or TRANSPORTS.for_class(type(self))
+
+    def _async_http_transport(self) -> AsyncTransport:
+        return self._async_transport or ASYNC_TRANSPORTS.for_class(type(self))

apiroute/client_config.py

@@ -0,0 +1,95 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from apiroute.base_url_validator import validate_base_url
+from apiroute.body_encoder import BODY_FORMATS
+from apiroute.query_encoder import QUERY_FORMATS
+from apiroute.retries import Retries
+
+# Class attributes a client or section reads its configuration from
+CONFIG_ATTRIBUTES = (
+    "base_url",
+    "headers",
+    "query_params",
+    "timeout",
+    "retries",
+    "body_format",
+    "query_format",
+    "inherit",
+)
+
+# These merge down the class hierarchy, as the gem's header and query_param calls do;
+# the rest are replaced by a subclass
+MERGED_ATTRIBUTES = ("headers", "query_params")
+
+INHERITABLE = frozenset({"headers", "query_params"})
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    base_url: str | None = None
+    headers: Mapping[str, Any] = field(default_factory=dict)
+    query_params: Mapping[str, Any] = field(default_factory=dict)
+    # httpx defaults to 5 seconds, which is short for API calls that do real work
+    timeout: float | None = 30.0
+    retries: Retries = field(default_factory=Retries)
+    body_format: Any = "json"
+    query_format: Any = "flat"
+    inherit: frozenset[str] = frozenset()
+
+    @classmethod
+    def from_class(cls, router_class: type) -> "ClientConfig":
+        own = {
+            name: vars(router_class)[name]
+            for name in CONFIG_ATTRIBUTES
+            if name in vars(router_class)
+        }
+        return _parent_config(router_class)._extended(own, router_class.__qualname__)
+
+    def for_section(self, parent: "ClientConfig", root: "ClientConfig") -> "ClientConfig":
+        """This (a section's) config, with its parent's base_url and what it inherits from root."""
+        changes: dict[str, Any] = {"base_url": self.base_url or parent.base_url}
+        for name in self.inherit:
+            changes[name] = {**getattr(root, name), **getattr(self, name)}
+        return replace(self, **changes)
+
+    def _extended(self, own: dict[str, Any], owner: str) -> "ClientConfig":
+        changes = dict(own)
+        for name in MERGED_ATTRIBUTES:
+            if name in own:
+                changes[name] = _merged_dict(getattr(self, name), own[name])
+        if "inherit" in own:
+            changes["inherit"] = frozenset(own["inherit"])
+        config = replace(self, **changes)
+        try:
+            config._validate()
+        except ValueError as error:
+            raise ValueError(f"{owner}: {error}") from error
+        return config
+
+    def _validate(self) -> None:
+        if self.base_url is not None:
+            validate_base_url(self.base_url)
+        if not callable(self.body_format) and self.body_format not in BODY_FORMATS:
+            raise ValueError(f"body_format must be one of {BODY_FORMATS} or a callable")
+        if not callable(self.query_format) and self.query_format not in QUERY_FORMATS:
+            raise ValueError(f"query_format must be one of {QUERY_FORMATS} or a callable")
+        if not isinstance(self.retries, Retries):
+            raise ValueError("retries must be a Retries")
+        if not self.inherit <= INHERITABLE:
+            raise ValueError(f"inherit may only list {sorted(INHERITABLE)}")
+
+
+def _parent_config(router_class: type) -> ClientConfig:
+    for base in router_class.__mro__[1:]:
+        config = vars(base).get("_config")
+        if config is not None:
+            return config
+    return ClientConfig()
+
+
+def _merged_dict(base: Mapping[str, Any], own: Mapping[str, Any]) -> dict[str, Any]:
+    """A None value in the subclass removes that key."""
+    merged = {**base, **own}
+    return {name: value for name, value in merged.items() if value is not None}

apiroute/dataclass_converter.py

@@ -0,0 +1,56 @@
+import dataclasses
+from typing import Any, get_args, get_origin, get_type_hints
+
+from apiroute.model_types import is_dataclass_type, is_union, strip_annotated
+
+
+class DataclassConverter:
+    """Builds dataclasses (inside lists, dicts and unions too) from parsed JSON, without pydantic.
+
+    Keys the dataclass doesn't declare are ignored, since APIs add fields over time; a
+    missing required field raises TypeError. Values aren't type-checked beyond that.
+    """
+
+    def __init__(self, model: Any):
+        self._model = model
+
+    def convert(self, data: Any) -> Any:
+        return self._convert(self._model, data)
+
+    def _convert(self, tp: Any, data: Any) -> Any:
+        tp = strip_annotated(tp)
+        if is_union(tp):
+            return self._convert_union(tp, data)
+        if is_dataclass_type(tp):
+            return self._convert_dataclass(tp, data)
+        origin = get_origin(tp)
+        if origin in (list, tuple, set, frozenset) and get_args(tp):
+            item = get_args(tp)[0]
+            return origin(self._convert(item, value) for value in data)
+        if origin is dict and get_args(tp):
+            value_type = get_args(tp)[1]
+            return {key: self._convert(value_type, value) for key, value in data.items()}
+        return data
+
+    def _convert_union(self, tp: Any, data: Any) -> Any:
+        options = [arg for arg in get_args(tp) if arg is not type(None)]
+        if data is None:
+            return None
+        errors = []
+        for option in options:
+            try:
+                return self._convert(option, data)
+            except (TypeError, KeyError, AttributeError) as error:
+                errors.append(error)
+        raise TypeError(f"no type in {tp} fits the data: {errors}")
+
+    def _convert_dataclass(self, tp: type, data: Any) -> Any:
+        if not isinstance(data, dict):
+            raise TypeError(f"{tp.__name__} needs an object, got {type(data).__name__}")
+        hints = get_type_hints(tp, include_extras=True)
+        values = {
+            field.name: self._convert(hints[field.name], data[field.name])
+            for field in dataclasses.fields(tp)
+            if field.init and field.name in data
+        }
+        return tp(**values)

apiroute/deferred_converter.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from apiroute.response_converter import converter_for
+
+
+class DeferredConverter:
+    """Converts with a model type named by a string annotation that couldn't be evaluated
+    when the class was created, e.g. `-> "User"` with User defined further down the module.
+    The name is looked up on first use."""
+
+    def __init__(self, annotation: str, namespace: dict[str, Any]):
+        self._annotation = annotation
+        self._namespace = namespace
+        self._converter: Any = None
+        self._resolved = False
+
+    def convert(self, data: Any) -> Any:
+        if not self._resolved:
+            model = eval(self._annotation, self._namespace)  # noqa: S307
+            self._converter = converter_for(model)
+            self._resolved = True
+        return data if self._converter is None else self._converter.convert(data)

apiroute/from_client.py

@@ -0,0 +1,9 @@
+class _FromClient:
+    """The default of a route parameter that, when left out, comes from the client instead."""
+
+    def __repr__(self) -> str:
+        return "FROM_CLIENT"
+
+
+# Usable in a def too: def list_repos(self, org: str = FROM_CLIENT, page: int = 1)
+FROM_CLIENT = _FromClient()

apiroute/generated_signature.py

@@ -0,0 +1,93 @@
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from apiroute.from_client import FROM_CLIENT
+from apiroute.http_method import infer_http_method, normalize_http_method
+from apiroute.path_template import PathTemplate
+from apiroute.route_compiler import STREAM_PARAMS
+from apiroute.route_definition_error import RouteDefinitionError
+from apiroute.route_spec import RouteSpec
+from apiroute.value_template import ValueTemplate
+
+_BODY_METHODS = frozenset({"POST", "PUT", "PATCH"})
+_KEYWORD_ONLY = inspect.Parameter.KEYWORD_ONLY
+
+
+class GeneratedSignature:
+    """Builds the stub function for a route written without a def.
+
+    Every placeholder becomes a keyword-only parameter, in path, query, body order. One the
+    class declares (a class attribute, method, property or annotation such as `org: str`)
+    is optional and falls back to the client's value. A POST, PUT or PATCH route without a
+    body template also takes an optional `body`, and a stream="file" or "io" route a
+    required `file` or `io`.
+    """
+
+    def __init__(self, owner: type, name: str, spec: RouteSpec):
+        self._owner = owner
+        self._name = name
+        self._spec = spec
+
+    def function(self) -> Callable:
+        try:
+            signature = self._signature()
+        except (TypeError, ValueError) as error:
+            raise RouteDefinitionError(f"{self._label()}: {error}") from error
+        return self._stub(signature)
+
+    def _signature(self) -> inspect.Signature:
+        parameters = [inspect.Parameter("self", inspect.Parameter.POSITIONAL_OR_KEYWORD)]
+        parameters += [self._parameter(name) for name in self._placeholder_names()]
+        if self._takes_body():
+            parameters.append(inspect.Parameter("body", _KEYWORD_ONLY, default=None))
+        stream_param = STREAM_PARAMS.get(self._spec.stream)
+        if stream_param is not None:
+            parameters.append(inspect.Parameter(stream_param, _KEYWORD_ONLY))
+        return inspect.Signature(parameters)
+
+    def _placeholder_names(self) -> list[str]:
+        names = list(PathTemplate(self._spec.path).names)
+        for template in (self._spec.query, self._spec.body):
+            if template is not None and not isinstance(template, (str, bytes)):
+                names += ValueTemplate(template).names
+        return list(dict.fromkeys(names))
+
+    def _parameter(self, name: str) -> inspect.Parameter:
+        if self._declared_on_class(name):
+            return inspect.Parameter(name, _KEYWORD_ONLY, default=FROM_CLIENT)
+        return inspect.Parameter(name, _KEYWORD_ONLY)
+
+    def _declared_on_class(self, name: str) -> bool:
+        return hasattr(self._owner, name) or any(
+            name in _annotations(base) for base in self._owner.__mro__
+        )
+
+    def _takes_body(self) -> bool:
+        if self._spec.body is not None:
+            return False
+        method = self._spec.method
+        http_method = infer_http_method(self._name) if method is None else method
+        return normalize_http_method(http_method) in _BODY_METHODS
+
+    def _stub(self, signature: inspect.Signature) -> Callable:
+        def stub(*args: Any, **kwargs: Any) -> Any:
+            raise NotImplementedError("generated routes are called through the client")
+
+        stub.__name__ = self._name
+        stub.__qualname__ = self._label()
+        stub.__module__ = self._owner.__module__
+        stub.__doc__ = f"{self._spec.method or infer_http_method(self._name)} {self._spec.path}"
+        stub.__signature__ = signature
+        return stub
+
+    def _label(self) -> str:
+        return f"{self._owner.__qualname__}.{self._name}"
+
+
+def _annotations(cls: type) -> dict[str, Any]:
+    """A class's own annotations; ones that can't be evaluated still count by name."""
+    try:
+        return inspect.get_annotations(cls)
+    except Exception:
+        return vars(cls).get("__annotations__", {})

apiroute/http_method.py

@@ -0,0 +1,44 @@
+import re
+
+HTTP_METHODS = frozenset(
+    {
+        "GET",
+        "POST",
+        "PUT",
+        "PATCH",
+        "DELETE",
+        "HEAD",
+        "OPTIONS",
+        "TRACE",
+        "COPY",
+        "LOCK",
+        "UNLOCK",
+        "MKCOL",
+        "MOVE",
+        "PROPFIND",
+        "PROPPATCH",
+    }
+)
+
+# The verb must be the whole name or be followed by '_', so create_user is a POST
+# but names such as posts or deleted_users stay GET.
+_INFERRED_METHODS = (
+    (re.compile(r"(?:post|create|add|insert)(?:_|$)", re.IGNORECASE), "POST"),
+    (re.compile(r"(?:put|update|modify|change)(?:_|$)", re.IGNORECASE), "PUT"),
+    (re.compile(r"patch(?:_|$)", re.IGNORECASE), "PATCH"),
+    (re.compile(r"(?:delete|remove|destroy)(?:_|$)", re.IGNORECASE), "DELETE"),
+)
+
+
+def infer_http_method(route_name: str) -> str:
+    for pattern, method in _INFERRED_METHODS:
+        if pattern.match(route_name):
+            return method
+    return "GET"
+
+
+def normalize_http_method(method: str) -> str:
+    upper = method.upper()
+    if upper not in HTTP_METHODS:
+        raise ValueError(f"unknown HTTP method {method!r}")
+    return upper