common_http.client

Async HTTP operations built from value contracts and exchange transports.

Classes

HttpClient

One async HTTP client for URLs, endpoints, prepared messages and batches.

create() accepts native config fields; init accepts the existing typed config or a mapping. Both are unconnected. Connection settings are fixed; call_config() provides validated immutable per-call patches.

Created transports are owned; injected transports and auth/admission collaborators are borrowed. A client belongs to one asyncio loop. Closing rejects active logical operations, including retry waits and whole batches.

send/batch compose common execution once and return the existing reports. stream exposes a managed exchange without the runner: execution retry, concurrency, timeout and run-local rate settings apply to buffered calls. Network phase timeouts and injected per-exchange admission apply to both.

__init__

def __init__(*, config: HttpClientConfig | Mapping[str, object] | None = None, transport: BaseTransport[Any] | None = None, auth: HttpAuth | None = None, admit: Callable[[Request], Awaitable[None]] | None = None) -> None

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

config

Read-only property.

config: HttpClientConfig

owns_transport

Read-only property.

owns_transport: bool

state

Read-only property.

state: Literal['new', 'open', 'closed']

transport

Read-only property.

transport: BaseTransport[Any]

aclose

async def aclose() -> None

aopen

async def aopen() -> Self

batch

async def batch(requests: Sequence[Request], *, options: HttpCallConfig | Mapping[str, object] | None = None) -> HttpBatchResult

One runner batch, in input order; never call execution-managed send.

build_request

def build_request(target: Endpoint | URL | str, *, method: HttpMethod | str | None = None, values: Mapping[str, object] | None = None, **inputs: Any) -> Request

Compose defaults BEFORE binding caller values, including removals.

URL targets accept Request’s params/headers/cookies/body shortcuts. Endpoint targets accept Endpoint.request inputs; use values for names colliding with this API. Endpoint methods cannot be changed by a call.

call_config

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

Resolve a call patch without mutating client settings or shared runners.

configuration_schema

@classmethod
def configuration_schema() -> dict[str, Any]

Discover accepted configuration, defaults and portable field types.

create

@classmethod
def create(*, transport: BaseTransport[Any] | None = None, auth: HttpAuth | None = None, admit: Callable[[Request], Awaitable[None]] | None = None, **settings: Any) -> Self

Construct from native HttpClientConfig fields through the same init.

get

async def get(url: URL | str, *, options: HttpCallConfig | Mapping[str, object] | None = None, **inputs: Any) -> HttpResult

post

async def post(url: URL | str, *, options: HttpCallConfig | Mapping[str, object] | None = None, **inputs: Any) -> HttpResult

request

async def request(target: Endpoint | URL | str, *, method: HttpMethod | str | None = None, values: Mapping[str, object] | None = None, options: HttpCallConfig | Mapping[str, object] | None = None, **inputs: Any) -> HttpResult

send

async def send(request: Request, *, options: HttpCallConfig | Mapping[str, object] | None = None) -> HttpResult

Execute an exact resolved message; do not reapply header/query defaults.

stream

async def stream(request: Request, *, network_timeout: HttpTimeout | None = None, follow_redirects: bool | None = None) -> AsyncIterator[Exchange]

Managed bytes, without a runner, silent replay or buffered result.

Auth-requested response buffering still obeys max_response_bytes. Caller iteration is inside the resource scope; early exit closes it.