Skip to content

xtr_http_client.bundle

The xtr-dependency-injection bundle for xtr-http-client.

ClientOptionsConfig dataclass

ClientOptionsConfig(headers: Mapping[str, str | Sequence[str]] | None = None, max_redirects: int | None = None, http_version: str | None = None, timeout: float | None = None, max_duration: float | None = None, max_connect_duration: float | None = None, resolve: Mapping[str, str] | None = None, proxy: str | None = None, verify_peer: bool | None = None, verify_host: bool | None = None, cafile: str | None = None, capath: str | None = None, local_cert: str | None = None, local_pk: str | None = None, passphrase: str | None = None, extra: Mapping[str, object] | None = None, retry_failed: RetryFailedConfig = RetryFailedConfig(), rate_limiter: str | None = None)

The request options a client starts from, and the layers wrapped around it.

Each option field is the request option of the same name, and None leaves it to the client's own default. retry_failed and rate_limiter are not request options: they say whether the client makes a failed request again, and which rate it is held to.

Attributes:

  • headers (Mapping[str, str | Sequence[str]] | None) –

    Headers to send, a mapping of name to one value or several.

  • max_redirects (int | None) –

    How many redirects to follow.

  • http_version (str | None) –

    The HTTP version to ask for.

  • timeout (float | None) –

    How long the transfer may go quiet for, in seconds.

  • max_duration (float | None) –

    How long a whole request and response may take, in seconds.

  • max_connect_duration (float | None) –

    How long connecting may take, in seconds.

  • resolve (Mapping[str, str] | None) –

    Host to IP address, used instead of asking a resolver.

  • proxy (str | None) –

    The proxy to go through, as a URL.

  • verify_peer (bool | None) –

    Whether to check that the peer's certificate is trusted.

  • verify_host (bool | None) –

    Whether to check that the certificate is for the host.

  • cafile (str | None) –

    A file of certificates to trust instead of the defaults.

  • capath (str | None) –

    A directory of certificates to trust instead of the defaults.

  • local_cert (str | None) –

    A client certificate to present.

  • local_pk (str | None) –

    The private key of local_cert, when it is kept apart.

  • passphrase (str | None) –

    The passphrase of local_pk; kept out of the repr.

  • extra (Mapping[str, object] | None) –

    Additional options a client may ignore.

  • retry_failed (RetryFailedConfig) –

    Whether and how a failed request is made again.

  • rate_limiter (str | None) –

    The name of the xtr-rate-limiter limiter every request waits its turn from; needs xtr-rate-limiter installed.

to_options

to_options() -> RequestOptions

Return the request options that are set, as a client takes them.

HttpClientBundle

Bases: Bundle[HttpClientConfig]

Turns an :class:HttpClientConfig into the default client and a client per service.

load_extension

load_extension(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.

HttpClientConfig dataclass

HttpClientConfig(max_host_connections: int = 6, default_options: ClientOptionsConfig = ClientOptionsConfig(), scoped_clients: Mapping[str, ScopedClientConfig] = _no_scoped_clients(), mock_response_factory: bool = False, tracing: bool = False)

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.

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 (int) –

    How many connections one pool may hold at once.

  • default_options (ClientOptionsConfig) –

    What every request starts from, and the layers the default client — and every scoped one leaving them unset — is wrapped in.

  • scoped_clients (Mapping[str, ScopedClientConfig]) –

    A client per service, by the name it is qualified by.

  • mock_response_factory (bool) –

    Answer every request from a :class:~xtr_http_client.MockHttpClient — an empty 200 until a test scripts it — instead of the network.

  • tracing (bool) –

    Wrap every client in a :class:~xtr_http_client.TraceableHttpClient, which writes down each request made through it.

RetryFailedConfig dataclass

RetryFailedConfig(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)

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 (bool) –

    Whether a failed request is made again.

  • max_retries (int) –

    How many further attempts a request may have.

  • delay (int) –

    How many milliseconds to wait before the first retry, and what the growing delay starts from.

  • multiplier (float) –

    What the delay is multiplied by per attempt already made.

  • max_delay (int) –

    The longest wait, in milliseconds; 0 sets no ceiling.

  • jitter (float) –

    How much of each delay is randomness, from 0 to 1.

  • http_codes (Mapping[int, Sequence[str] | None] | None) –

    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 (Sequence[str]) –

    The base URIs each further attempt moves along, after the client's own base_uri.

  • retry_strategy (str | None) –

    The qualifier of a :class:~xtr_http_client.retry.RetryStrategyInterface service deciding instead of the numbers above.

ScopedClientConfig dataclass

ScopedClientConfig(headers: Mapping[str, str | Sequence[str]] | None = None, max_redirects: int | None = None, http_version: str | None = None, timeout: float | None = None, max_duration: float | None = None, max_connect_duration: float | None = None, resolve: Mapping[str, str] | None = None, proxy: str | None = None, verify_peer: bool | None = None, verify_host: bool | None = None, cafile: str | None = None, capath: str | None = None, local_cert: str | None = None, local_pk: str | None = None, passphrase: str | None = None, extra: Mapping[str, object] | None = None, retry_failed: RetryFailedConfig = RetryFailedConfig(), rate_limiter: str | None = None, scope: str | None = None, base_uri: str | None = None, auth_basic: str | tuple[str] | tuple[str, str] | None = None, auth_bearer: str | None = None, query: Mapping[str, str | int | float | Sequence[str | int | float]] | None = None, mock_response_factory: bool | None = None)

Bases: ClientOptionsConfig

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.

ScopedClientConfig(
    base_uri="https://api.github.com/",
    headers={"Accept": "application/vnd.github+json"},
    auth_bearer=env("GITHUB_TOKEN"),
)

Attributes:

  • scope (str | None) –

    A regular expression a URL must match from its start for these options to apply.

  • base_uri (str | None) –

    What a relative URL resolves against, and — with no scope — what a URL must start with to be in scope.

  • auth_basic (str | tuple[str] | tuple[str, str] | None) –

    Credentials for basic authentication; kept out of the repr.

  • auth_bearer (str | None) –

    A token to send as a bearer credential; kept out of the repr.

  • query (Mapping[str, str | int | float | Sequence[str | int | float]] | None) –

    Parameters merged into the query of every URL resolved against base_uri.

  • mock_response_factory (bool | None) –

    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.

inheriting

inheriting(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.