common_http.schemas.configs

Validated HTTP operating configuration, separate from request values.

These schemas perform no file, environment, credential-provider, or network I/O. Connection setup consumes paths and trust material only when a client opens.

Classes

`ConnectionLimits`

Bases: _Config

Connection-pool settings, not request concurrency or a shared quota.

None means no configured limit. Zero keepalive connections disables idle connection retention. An unlimited idle capacity requires unlimited total capacity so the two settings cannot contradict one another.

Fields and properties declared here; inherited members belong to the bases above.

`keepalive_expiry`

keepalive_expiry: _Seconds | None = 5.0

`max_connections`

max_connections: int | None = Field(default=100, ge=1)

`max_keepalive_connections`

max_keepalive_connections: int | None = Field(default=20, ge=0)

`HttpCallConfig`

Bases: RunnerConfig, _Config

Per-call execution and HTTP settings, extending the existing foundation.

Inherited timeout retains RunnerConfig’s per-attempt meaning. HTTP phase waits live in network_timeout. A whole-operation deadline is not invented here. Retry remains opt-in; these schemas execute no retry policy.

merge() returns a validated new object. Nested configuration updates touch only supplied fields, including when an object is used as the patch. None is explicit, never silently skipped. Execution classes and hooks remain Python inputs; JSON discovery describes their portable subset.

Fields and properties declared here; inherited members belong to the bases above.

`decode`

decode: Literal['auto', 'json', 'text', 'bytes'] = 'auto'

`default_encoding`

default_encoding: str = 'utf-8'

`follow_redirects`

follow_redirects: bool = False

`max_response_bytes`

max_response_bytes: int | None = Field(default=None, ge=0)

`network_timeout`

network_timeout: HttpTimeout = Field(default_factory=HttpTimeout)

`merge`

def merge(**overrides: Any) -> Self

Replace contract/default collections; recursively patch settings.

Header/query defaults are whole validated values at this configuration boundary. Combining them with a message belongs to request preparation. Use a full model_dump() as a patch to reset every nested setting.

`HttpClientConfig`

Bases: HttpCallConfig

Client call defaults plus connection/session creation settings.

Ordinary strings, dictionaries, and nested configs normalize into typed values. base_url must be absolute without query/fragment; use default_query for query defaults. URL.resolve semantics control relative addressing.

default_query serializes as encoded text, avoiding ambiguity with a query parameter actually named ‘encoded’. A mapping always means native query values; a string preserves wire spelling. Request’s existing conversion is reused. for_call() accepts only call settings and produces HttpCallConfig. Ownership, authenticators, shared limiters and live clients are injected into runtime classes, not stored in these configuration schemas.

Fields and properties declared here; inherited members belong to the bases above.

`base_url`

base_url: URL | None = Field(default=None, repr=False)

`default_headers`

default_headers: Headers = Field(default_factory=Headers, repr=False)

`default_query`

default_query: QueryParams = Field(default_factory=QueryParams, repr=False)

`http1`

http1: bool = True

`http2`

http2: bool = False

`limits`

limits: ConnectionLimits = Field(default_factory=ConnectionLimits)

`max_redirects`

max_redirects: int = Field(default=20, ge=0)

`persist_cookies`

persist_cookies: bool = True

`proxy`

proxy: SecretStr | None = Field(default=None, repr=False)

`tls`

tls: TLSConfig = Field(default_factory=TLSConfig)

`trust_env`

trust_env: bool = False

`for_call`

def for_call(options: HttpCallConfig | Mapping[str, Any] | None = None, **overrides: Any) -> HttpCallConfig

Resolve call overrides without accepting creation-only settings.

`HttpTimeout`

Bases: _Config

Network phase limits in seconds; None disables only that phase.

Read/write limits apply to waits for chunks, not a total operation duration. Execution attempt limits and whole-operation deadlines have separate owners.

Fields and properties declared here; inherited members belong to the bases above.

`connect`

connect: _Seconds | None = 5.0

`pool`

pool: _Seconds | None = 5.0

`read`

read: _Seconds | None = 30.0

`write`

write: _Seconds | None = 30.0

`TLSConfig`

Bases: _Config

TLS verification and optional client identity, resolved at connect time.

Trust sources may be combined. A key may be stored in cert_file, so key_file is optional even with a client certificate. A separate key/password requires cert_file. Verification-disabled configurations cannot also supply CA trust.

ca_data accepts PEM text or DER bytes; bytes use {‘base64’: ’…’} in JSON configuration to preserve their type. Passwords are masked in JSON exports: callers must re-inject real credentials when restoring serialized settings.

Fields and properties declared here; inherited members belong to the bases above.

`ca_data`

ca_data: str | bytes | None = Field(default=None, repr=False)

`ca_directory`

ca_directory: Path | None = Field(default=None, repr=False)

`ca_file`

ca_file: Path | None = Field(default=None, repr=False)

`cert_file`

cert_file: Path | None = Field(default=None, repr=False)

`key_file`

key_file: Path | None = Field(default=None, repr=False)

`key_password`

key_password: SecretStr | None = Field(default=None, repr=False)

`verify`

verify: bool = True