xtr-http-client 4.0.2__py3-none-any.whl

xtr_http_client/bundle/http_client_bundle.py

@@ -0,0 +1,85 @@
+"""The xtr-http-client bundle: the application's HTTP client, and one more per service.
+
+An application listing :class:`HttpClientBundle` gets an
+:class:`~xtr_http_client_contracts.HttpClientInterface` — the default client — and,
+for every scoped client its :class:`HttpClientConfig` names, another one qualified
+by that name. Each is a transport the bundle owns, wrapped in the layers its
+configuration turns on, from the inside out: the pace of an xtr-rate-limiter
+limiter, the options of one service, another try at what failed, and a record of
+every request.
+
+Every client shares one transport — :class:`~xtr_http_client.HttpxHttpClient`, or
+:class:`~xtr_http_client.MockHttpClient` for a client answering from a script — so
+they share its connections. Nothing is opened until a request is made, and the
+connections are closed with the container.
+"""
+
+from __future__ import annotations
+
+from typing import final
+
+from typing_extensions import override
+from xtr_dependency_injection import (
+    Bundle,
+    ContainerBuilder,
+    ServiceConfigurator,
+    as_bundle,
+    bundle_active,
+    required_bundle,
+)
+
+from xtr_http_client.exception import InvalidArgumentError
+
+from ._clients import register_client, register_transports
+from .http_client_config import HttpClientConfig
+
+__all__ = ["HttpClientBundle"]
+
+
+@final
+@required_bundle("xtr_rate_limiter.bundle:RateLimiterBundle", ignore_on_invalid=True)
+@as_bundle("http_client", config=HttpClientConfig)
+class HttpClientBundle(Bundle[HttpClientConfig]):
+    """Turns an :class:`HttpClientConfig` into the default client and a client per service."""
+
+    @override
+    def load_extension(
+        self,
+        config: HttpClientConfig,
+        services: ServiceConfigurator,
+        builder: ContainerBuilder,
+    ) -> None:
+        """Register every client, and the transports they send through.
+
+        Raises:
+            InvalidArgumentError: When a client is paced by a rate limiter while
+                the rate limiter bundle is not active.
+        """
+        pacing = bundle_active(builder, "rate_limiter")
+        defaults = config.default_options
+        _check_pace("The default HTTP client", defaults.rate_limiter, pacing)
+        register_client(services, None, defaults, mocked=config.mock_response_factory)
+
+        mocked = [config.mock_response_factory]
+        for name, scoped in config.scoped_clients.items():
+            client = scoped.inheriting(defaults)
+            mock = scoped.mock_response_factory
+            mocked.append(config.mock_response_factory if mock is None else mock)
+            _check_pace(f'The "{name}" HTTP client', client.rate_limiter, pacing)
+            register_client(services, name, client, mocked=mocked[-1])
+
+        register_transports(services, mocked)
+
+
+def _check_pace(owner: str, rate_limiter: str | None, pacing: bool) -> None:
+    """Refuse a rate limiter nothing can provide.
+
+    Raises:
+        InvalidArgumentError: When ``rate_limiter`` is named while the rate
+            limiter bundle is not active.
+    """
+    if rate_limiter is not None and not pacing:
+        raise InvalidArgumentError(
+            f'{owner} is paced by the "{rate_limiter}" rate limiter, but the rate limiter '
+            f'bundle is not active: install "xtr-http-client[throttling]".'
+        )

xtr_http_client/bundle/http_client_config.py

@@ -0,0 +1,75 @@
+"""Configuration for :class:`~xtr_http_client.bundle.http_client_bundle.HttpClientBundle`."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import final
+
+from xtr_http_client.exception import InvalidArgumentError
+
+from .client_options_config import ClientOptionsConfig
+from .scoped_client_config import ScopedClientConfig
+
+__all__ = ["HttpClientConfig"]
+
+
+def _no_scoped_clients() -> dict[str, ScopedClientConfig]:
+    """The empty set of services a zero-config application starts with."""
+    return {}
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class HttpClientConfig:
+    """The application's default client, and one more per service it calls.
+
+    Buildable with no arguments: the zero-config path is one client sending
+    requests as they are given, over connections opened when the first
+    request is made.
+
+    ```python
+    HttpClientConfig(
+        default_options=ClientOptionsConfig(
+            timeout=10, retry_failed=RetryFailedConfig(enabled=True)
+        ),
+        scoped_clients={
+            "github": ScopedClientConfig(
+                base_uri="https://api.github.com/", auth_bearer=env("GITHUB_TOKEN")
+            ),
+        },
+    )
+    ```
+
+    Attributes:
+        max_host_connections: How many connections one pool may hold at once.
+        default_options: What every request starts from, and the layers the
+            default client — and every scoped one leaving them unset — is
+            wrapped in.
+        scoped_clients: A client per service, by the name it is qualified by.
+        mock_response_factory: Answer every request from a
+            :class:`~xtr_http_client.MockHttpClient` — an empty 200 until a test
+            scripts it — instead of the network.
+        tracing: Wrap every client in a
+            :class:`~xtr_http_client.TraceableHttpClient`, which writes down
+            each request made through it.
+    """
+
+    max_host_connections: int = 6
+    default_options: ClientOptionsConfig = field(default_factory=ClientOptionsConfig)
+    scoped_clients: Mapping[str, ScopedClientConfig] = field(default_factory=_no_scoped_clients)
+    mock_response_factory: bool = False
+    tracing: bool = False
+
+    def __post_init__(self) -> None:
+        """Refuse a scoped client with no name, or one that cannot take what it inherits.
+
+        Raises:
+            InvalidArgumentError: When the configuration cannot be used.
+        """
+        for name, scoped in self.scoped_clients.items():
+            if name == "":
+                raise InvalidArgumentError("A scoped HTTP client needs a name, got an empty one.")
+            # Validated as it is built: retries falling back to other base URIs
+            # are only usable by a client with a base URI of its own.
+            _ = scoped.inheriting(self.default_options)

xtr_http_client/bundle/retry_failed_config.py

@@ -0,0 +1,77 @@
+"""Whether a configured client makes a failed request again, and how."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Final, final
+
+from xtr_http_client.exception import InvalidArgumentError
+
+__all__ = ["RetryFailedConfig"]
+
+_DELAY_MS: Final = 1000
+_MULTIPLIER: Final = 2.0
+_MAX_DELAY_MS: Final = 0
+_JITTER: Final = 0.1
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class RetryFailedConfig:
+    """The retrying layer of a configured client: off unless ``enabled``.
+
+    What is retried, and how long is waited in between, is decided either by a
+    :class:`~xtr_http_client.retry.GenericRetryStrategy` built from the numbers
+    here, or by the strategy service ``retry_strategy`` names — one or the
+    other, since numbers next to a service that ignores them would be settings
+    that silently never apply.
+
+    Attributes:
+        enabled: Whether a failed request is made again.
+        max_retries: How many further attempts a request may have.
+        delay: How many milliseconds to wait before the first retry, and what
+            the growing delay starts from.
+        multiplier: What the delay is multiplied by per attempt already made.
+        max_delay: The longest wait, in milliseconds; ``0`` sets no ceiling.
+        jitter: How much of each delay is randomness, from ``0`` to ``1``.
+        http_codes: The status codes retried, each mapped to the methods it is
+            retried for — ``None`` for every method. ``None`` keeps the
+            strategy's own list.
+        base_uris: The base URIs each further attempt moves along, after the
+            client's own ``base_uri``.
+        retry_strategy: The qualifier of a
+            :class:`~xtr_http_client.retry.RetryStrategyInterface` service
+            deciding instead of the numbers above.
+    """
+
+    enabled: bool = False
+    max_retries: int = 3
+    delay: int = _DELAY_MS
+    multiplier: float = _MULTIPLIER
+    max_delay: int = _MAX_DELAY_MS
+    jitter: float = _JITTER
+    http_codes: Mapping[int, Sequence[str] | None] | None = None
+    base_uris: Sequence[str] = ()
+    retry_strategy: str | None = None
+
+    def __post_init__(self) -> None:
+        """Refuse fallback URIs nothing retries towards, and numbers a strategy service ignores.
+
+        Raises:
+            InvalidArgumentError: When the configuration cannot be used.
+        """
+        if self.base_uris and not self.enabled:
+            raise InvalidArgumentError('The "base_uris" option requires retries to be enabled.')
+        tuned = (self.http_codes, self.delay, self.multiplier, self.max_delay, self.jitter) != (
+            None,
+            _DELAY_MS,
+            _MULTIPLIER,
+            _MAX_DELAY_MS,
+            _JITTER,
+        )
+        if self.retry_strategy is not None and tuned:
+            raise InvalidArgumentError(
+                'The "retry_strategy" option cannot be used along with the "http_codes", '
+                '"delay", "multiplier", "max_delay" or "jitter" options.'
+            )

xtr_http_client/bundle/scoped_client_config.py

@@ -0,0 +1,99 @@
+"""A client of its own for one service: where it is, and what reaching it takes."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from typing import ClassVar, final
+
+from xtr_http_client.exception import InvalidArgumentError
+
+from .client_options_config import ClientOptionsConfig
+from .retry_failed_config import RetryFailedConfig
+
+__all__ = ["ScopedClientConfig"]
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ScopedClientConfig(ClientOptionsConfig):
+    r"""A client whose options apply to the URLs of one service.
+
+    A request whose URL ``scope`` matches from its start — or which falls under
+    ``base_uri``, when there is no scope — starts from these options, and a
+    relative URL resolves against ``base_uri``. Left as they are,
+    ``retry_failed`` and ``rate_limiter`` are the default options' own.
+
+    ```python
+    ScopedClientConfig(
+        base_uri="https://api.github.com/",
+        headers={"Accept": "application/vnd.github+json"},
+        auth_bearer=env("GITHUB_TOKEN"),
+    )
+    ```
+
+    Attributes:
+        scope: A regular expression a URL must match from its start for these
+            options to apply.
+        base_uri: What a relative URL resolves against, and — with no
+            ``scope`` — what a URL must start with to be in scope.
+        auth_basic: Credentials for basic authentication; kept out of the
+            ``repr``.
+        auth_bearer: A token to send as a bearer credential; kept out of the
+            ``repr``.
+        query: Parameters merged into the query of every URL resolved against
+            ``base_uri``.
+        mock_response_factory: ``True`` answers this client's requests from
+            the mock transport, ``False`` sends them for real, whatever the
+            bundle's own setting is; ``None`` follows it.
+    """
+
+    _NOT_OPTIONS: ClassVar[frozenset[str]] = frozenset(
+        {"retry_failed", "rate_limiter", "scope", "mock_response_factory"}
+    )
+
+    scope: str | None = None
+    base_uri: str | None = None
+    auth_basic: str | tuple[str] | tuple[str, str] | None = field(default=None, repr=False)
+    auth_bearer: str | None = field(default=None, repr=False)
+    query: Mapping[str, str | int | float | Sequence[str | int | float]] | None = None
+    mock_response_factory: bool | None = None
+
+    def __post_init__(self) -> None:
+        """Refuse a client that says nothing about which URLs are its own.
+
+        Raises:
+            InvalidArgumentError: When neither a scope nor a base URI is given,
+                or ``query`` or fallback base URIs come without a base URI.
+        """
+        if self.scope is None and self.base_uri is None:
+            raise InvalidArgumentError('Either "scope" or "base_uri" should be defined.')
+        if self.query and self.base_uri is None:
+            raise InvalidArgumentError('"query" applies to "base_uri" but no base URI is defined.')
+        if self.retry_failed.base_uris and self.base_uri is None:
+            raise InvalidArgumentError(
+                '"retry_failed.base_uris" lists the URIs to fall back to, so a "base_uri" '
+                "must be defined as well."
+            )
+
+    def inheriting(self, defaults: ClientOptionsConfig) -> ScopedClientConfig:
+        """Return this client with the retries and the limiter it left to ``defaults``.
+
+        Inherited whole, not field by field: a client that configures its own
+        retries says everything about them.
+
+        Raises:
+            InvalidArgumentError: When what it inherits cannot be used with it —
+                fallback base URIs, for a client with no base URI.
+        """
+        return replace(
+            self,
+            retry_failed=(
+                self.retry_failed
+                if self.retry_failed != RetryFailedConfig()
+                else defaults.retry_failed
+            ),
+            rate_limiter=self.rate_limiter
+            if self.rate_limiter is not None
+            else defaults.rate_limiter,
+        )

xtr_http_client/exception/__init__.py

@@ -0,0 +1,40 @@
+"""Everything calling out through this package can raise.
+
+The hierarchy is the contract's, re-exported here so one import answers "what
+can this client raise" without reaching into two packages: :class:`HttpClientError`
+at the root, :class:`TransportError` for "there is no answer" (with
+:class:`TransportTimeoutError` for running out of time), :class:`HttpError` for
+"there is one and it is not a success" (:class:`RedirectionError`,
+:class:`ClientError`, :class:`ServerError`), :class:`DecodingError` for an
+answer that is not what it was read as (with :class:`JsonError` for a body that
+is not the JSON it was read as), and :class:`InvalidArgumentError` for a request
+this client refuses to make.
+"""
+
+from __future__ import annotations
+
+from xtr_http_client_contracts import (
+    ClientError,
+    DecodingError,
+    HttpClientError,
+    HttpError,
+    InvalidArgumentError,
+    JsonError,
+    RedirectionError,
+    ServerError,
+    TransportError,
+    TransportTimeoutError,
+)
+
+__all__ = [
+    "ClientError",
+    "DecodingError",
+    "HttpClientError",
+    "HttpError",
+    "InvalidArgumentError",
+    "JsonError",
+    "RedirectionError",
+    "ServerError",
+    "TransportError",
+    "TransportTimeoutError",
+]

xtr_http_client/exception/_http_error_message.py

@@ -0,0 +1,129 @@
+"""What an unsuccessful status says it means, read off the response."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_http_client_contracts import HttpResponseInterface
+
+__all__ = ["build_message"]
+
+_MAX_ERROR_BODY: Final = 32768
+"""How much of an error document is worth reading to name the error.
+
+An error message is a line or two; a body larger than this is a payload that
+happens to have failed, and reading it to the end to quote 40 characters of it
+would mean holding it all. Past the limit the status line stands on its own.
+"""
+
+_HYDRA: Final = ("hydra:title", "hydra:description")
+_PROBLEM: Final = ("title", "detail")
+_JSON_WORD: Final = re.compile(r"\bjson\b", re.IGNORECASE)
+
+
+async def build_message(response: HttpResponseInterface) -> str:
+    """Say what the status means for the request that got it.
+
+    The code and the URL are always enough — ``HTTP 404 returned for "..."``.
+    Two things make it better, and both come off the response itself: the
+    status line the server sent, which carries its own wording of the code,
+    and an error document, which carries the server's wording of the problem.
+
+    The document is only looked for when the head says the body is JSON, and
+    only the head of it is parsed, so naming an error never means holding a
+    payload. The two shapes read are the ones APIs actually send: ``title`` and
+    ``detail``, or the same pair under a ``hydra:`` prefix. The media type is
+    not checked beyond "it says JSON" because these shapes travel under many of
+    them.
+
+    Args:
+        response: The response the status came on. Its body is read with
+            ``throw=False``, so reading it cannot raise over the very status
+            this message is about.
+
+    Returns:
+        The message, ready to be the ``reason`` of an
+        :class:`HttpError <xtr_http_client_contracts.exception.http_error.HttpError>`.
+    """
+    url = response.get_info("url")
+    message = f'HTTP {response.get_info("http_code")} returned for "{url}".'
+    status_line, is_json = _read_head(response.get_info("response_headers"))
+
+    if status_line is not None:
+        message = f'{status_line} returned for "{url}".'
+    if not is_json:
+        return message
+
+    content = (await response.get_content(throw=False))[:_MAX_ERROR_BODY]
+    try:
+        document = cast("object", json.loads(content))
+    except ValueError:
+        return message
+
+    return _described(document) or message
+
+
+def _read_head(response_headers: object) -> tuple[str | None, bool]:
+    """Find the last status line, and whether its response said JSON.
+
+    Read backwards, because a chain of redirects leaves every hop's head in
+    there and it is the last one the status belongs to. A content type is
+    noted wherever it appears, since it may be written before the status line
+    it belongs to.
+    """
+    if not isinstance(response_headers, Sequence) or isinstance(response_headers, str):
+        return None, False
+
+    status_line: str | None = None
+    is_json = False
+    for line in reversed([entry for entry in response_headers if isinstance(entry, str)]):
+        if line.startswith("HTTP/"):
+            if status_line is not None:
+                break
+            status_line = line
+        if line.lower().startswith("content-type:"):
+            is_json = is_json or _JSON_WORD.search(line) is not None
+            if status_line is not None:
+                break
+
+    return status_line, is_json
+
+
+def _described(document: object) -> str | None:
+    """Join the two fields an error document names the problem with."""
+    if not document or not isinstance(document, dict):
+        return None
+
+    # A decoded JSON object is keyed by strings; the cast says so once rather
+    # than at every lookup below.
+    fields = cast("Mapping[str, object]", document)
+    for title, detail in (_HYDRA, _PROBLEM):
+        head, tail = fields.get(title), fields.get(detail)
+        if head is None and tail is None:
+            continue
+        if not _is_scalar(head) or not _is_scalar(tail):
+            return None
+        separator = "\n\n" if head is not None and tail is not None else ""
+        return f"{_as_text(head)}{separator}{_as_text(tail)}"
+
+    return None
+
+
+def _is_scalar(value: object) -> bool:
+    """Tell whether a decoded JSON value can stand in a message as it is."""
+    return value is None or isinstance(value, str | int | float | bool)
+
+
+def _as_text(value: object) -> str:
+    """Write a scalar out the way the document meant it to be read."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "1" if value else ""
+    return str(value)

xtr_http_client/http_client.py

@@ -0,0 +1,57 @@
+"""Where a client comes from when the caller has no opinion about which one."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import Unpack
+
+from .httpx_http_client import HttpxHttpClient
+
+if TYPE_CHECKING:
+    from xtr_http_client_contracts import HttpClientInterface, RequestOptions
+
+__all__ = ["HttpClient"]
+
+
+@final
+class HttpClient:
+    """One call that hands back a client, so nothing has to name an implementation.
+
+    Code that calls out depends on the interface. Code that *builds* a client
+    has to pick something, and picking is a decision worth making in one
+    place: this is that place.
+
+    ```python
+    from xtr_http_client import HttpClient
+
+    client = HttpClient.create(base_uri="https://example.com/", timeout=5)
+    ```
+
+    It is not a client itself and holds nothing; there is nothing to keep an
+    instance of.
+    """
+
+    __slots__ = ()
+
+    @staticmethod
+    def create(
+        max_host_connections: int = 6,
+        **default_options: Unpack[RequestOptions],
+    ) -> HttpClientInterface:
+        """Return a client whose requests start from ``default_options``.
+
+        Args:
+            max_host_connections: How many connections one pool may hold at
+                once.
+            **default_options: What every request the client makes starts
+                from, over the contract's own defaults.
+
+        Returns:
+            A client, typed as the interface: what is behind it is this
+            package's decision, not the caller's.
+
+        Raises:
+            InvalidArgumentError: When an option is not one the client knows.
+        """
+        return HttpxHttpClient(default_options, max_host_connections)