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 therepr. -
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 ¶
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;
0sets no ceiling. -
jitter(float) –How much of each delay is randomness, from
0to1. -
http_codes(Mapping[int, Sequence[str] | None] | None) –The status codes retried, each mapped to the methods it is retried for —
Nonefor every method.Nonekeeps 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.RetryStrategyInterfaceservice 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) –Trueanswers this client's requests from the mock transport,Falsesends them for real, whatever the bundle's own setting is;Nonefollows it.
inheriting ¶
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.