HTTP configuration

Objects, dictionaries and construction helpers

All construction paths validate the same configuration. Unknown fields fail. Configurations are immutable; no connection is opened during construction.

from common_http import HttpClient, HttpClientConfig, HttpTimeout

config = HttpClientConfig(
    base_url="https://provider.example/api/",
    network_timeout=HttpTimeout(connect=5, read=90),
    max_concurrency=8,
)
client = HttpClient(config=config)
equivalent = HttpClient.create(
    base_url="https://provider.example/api/",
    network_timeout={"connect": 5, "read": 90},
    max_concurrency=8,
)
call = client.call_config(network_timeout={"read": 180})
assert call.network_timeout.connect == 5
assert call.network_timeout.read == 180
schema = HttpClient.configuration_schema()

Pass options=call or options={"network_timeout": {"read": 180}} to a buffered operation. Nested patches preserve unspecified fields. Explicit None has its documented meaning and is not skipped. A typed patch uses only explicitly set fields; pass its full model_dump() to reset all fields, including defaults. Client-only settings cannot be supplied as call overrides.

Buffered call settings

Every field below belongs to HttpCallConfig and can also be set as a client default through HttpClientConfig.

Field	Default	Meaning
`network_timeout`	`HttpTimeout()`	Network phase limits; detailed below
`follow_redirects`	`False`	Follow the configured bounded redirect policy
`decode`	`"auto"`	`auto`, `json`, `text` or `bytes`
`default_encoding`	`"utf-8"`	Text fallback when no response charset exists
`max_response_bytes`	`None`	Maximum retained content-decoded bytes; `0` allows only an empty body
`max_concurrency`	`5`	Concurrent tasks within one batch
`batch_size`	`None`	Sequential batch size; defaults to max concurrency
`timeout`	`None`	Execution timeout for each attempt, not the whole retry sequence
`fail_fast`	`False`	Stop launching later batches after an execution failure
`retry`	`RetryPolicy()`	No retries unless explicitly enabled and classified
`rate_limit`	`None`	Existing execution pacing of task starts within a run
`show_progress`	`False`	Execution progress display
`show_item_logs`	`False`	Per-item success logs; foundation failure logging still applies

Auto decoding selects JSON for application/json and +json, text for text/XML/ JavaScript media types, and bytes otherwise. Empty bodies have decoded_as="empty". Declared charsets take precedence. JSON defaults to UTF-8 with BOM handling. Invalid JSON/encoding produces a failed result retaining complete response bytes.

Client/session settings

Field	Default	Meaning
`base_url`	`None`	Absolute base without query or fragment
`default_headers`	Empty `Headers`	Base fields combined during construction
`default_query`	Empty `QueryParams`	Base query combined during construction
`limits`	`ConnectionLimits()`	Transport pool capacity
`tls`	`TLSConfig()`	Verification, trust roots and client identity
`http1`	`True`	Enable HTTP/1.1
`http2`	`False`	Enable HTTP/2 negotiation; at least one protocol must be enabled
`proxy`	`None`	HTTP(S), SOCKS5 or SOCKS5H proxy URI; stored as SecretStr
`trust_env`	`False`	Let HTTPX use supported proxy/trust environment settings
`max_redirects`	`20`	Maximum followed redirects when enabled
`persist_cookies`	`True`	Store response cookies and apply them by destination scope

Header/query config patches replace their whole values. Request construction combines those defaults with caller values. Dictionaries, ordered pairs and the typed contracts are accepted at their documented boundaries. Encoded query text is also accepted and preserves wire spelling.

Network and pool configuration

HttpTimeout values are positive seconds or None to disable that phase.

Field	Default	Meaning
`connect`	`5.0`	Establish connection
`read`	`30.0`	Wait for response data, including waits between chunks
`write`	`30.0`	Wait while sending request data
`pool`	`5.0`	Wait for a connection from the pool

ConnectionLimits controls transport capacity, independently of task concurrency.

Field	Default	Meaning
`max_connections`	`100`	Total connections; positive integer or unlimited with `None`
`max_keepalive_connections`	`20`	Idle connections; `0` disables retention, `None` is unlimited
`keepalive_expiry`	`5.0`	Idle expiry seconds, or no expiry with `None`

Idle capacity cannot exceed a finite total limit. These are per-transport settings, not container-wide or distributed quotas.

TLS and secrets

TLSConfig field	Default	Meaning
`verify`	`True`	Verify server certificates
`ca_file`	`None`	CA bundle path
`ca_directory`	`None`	CA trust directory
`ca_data`	`None`	PEM text or DER bytes
`cert_file`	`None`	Client certificate, optionally containing its key
`key_file`	`None`	Separate client private key
`key_password`	`None`	SecretStr password for the private key

Trust sources may be combined. A key or password requires a client certificate; custom trust cannot be combined with verify=False. Files are resolved when the transport opens, so paths must exist inside the consuming container.

Container/runtime code reads environment variables populated through Doppler and passes settings into this package:

import os
from common_http import HttpClient

http = HttpClient.create(
    base_url=os.environ["PROVIDER_BASE_URL"],
    default_headers={"X-Api-Key": os.environ["PROVIDER_API_KEY"]},
)

Do not log header/query values or export credential-bearing configuration as a secret backup. SecretStr fields mask exported secrets; headers and query fields can still contain sensitive values. Re-inject secrets when restoring settings. DER bytes use {"base64": "..."} in serialized TLS configuration.

Execution policy details

RetryPolicy accepts max_retries, retry_on, retry_when, retry_after, delay, multiplier, max_delay, jitter, retry_timeouts and on_retry. Defaults are respectively 0, (), None, None, 1.0, 2.0, 10.0, True, False, None. See execution examples.

RateLimit accepts positive rate and per (seconds, default 1.0), with optional burst. per_second(...) and per_minute(...) are construction helpers. Execution callbacks and exception classes are Python inputs; JSON schema discovery does not invent string-to-code loading for them.

stream accepts only its explicit network_timeout and follow_redirects overrides. It does not use runner retries, task pacing or per-attempt deadlines. Use asyncio.timeout around its context for an overall stream deadline.