HTTP

Use the same async client for external HTTP providers and internal container APIs. Endpoint declarations and site-specific parsers belong to the consuming package.

Installation

uv add common-http

Quick Start

from common_http import HttpClient

async with HttpClient.create(
    base_url="http://solutions-agents:8000/",
    max_concurrency=8,
) as http:
    result = await http.post("/estimate", json={"items": []})
    payload = result.unwrap().payload

Choose the entry point

Need	Entry point
Ordinary keyword configuration	HttpClient.create(**settings)
Validated configuration or dictionary	HttpClient(config=...)
Discover accepted settings	HttpClient.configuration_schema()
Derive validated call overrides	http.call_config(...)
Construct without network I/O	http.build_request(target, ...)
Bind and execute an endpoint or URL	await http.request(target, ...)
Simple GET or POST	await http.get(url, ...), await http.post(url, ...)
Execute a resolved message	await http.send(request)
Execute prepared messages in order	await http.batch(requests)
Consume response chunks	async with http.stream(request)

PUT, PATCH, DELETE, HEAD and OPTIONS use request(method=...) or a prepared Request. Construction is unconnected; the first operation opens the client. Use an async context to close it predictably. Run these examples inside an async function or a notebook supporting top-level await. Python 3.12 or newer is required.

unwrap() requires successful execution, a complete decoded body and 2xx status. Inspect the result directly when a non-2xx response is meaningful to your caller.

Core concepts

• Build independently with Request / Endpoint, or use http.build_request(...).
• request builds and executes; send accepts a resolved Request.
• batch returns input-aligned results through one execution runner.
• call_config(...) creates a validated override; configuration_schema() exposes configuration fields and defaults. Objects and native dictionaries are accepted.
• stream manages response bytes explicitly; buffered methods decode JSON/text/bytes.
• Injected transports and authentication objects are borrowed. A created transport is owned and closed by the client. Closing rejects active operations.
• HttpAuth is an HTTP interaction interface; shared token/refresh/storage logic belongs to a separate authentication implementation.

The container supplies reachable service addresses and credentials. The package reads no .env and contacts no secret manager.

Follow the guides

• Requests and providers: endpoints, parameters, repeated fields, body formats and embedded site data.
• Configuration: every client/call setting, defaults, nested merging and portable configuration.
• Results and execution: failures, concurrency, batching, pacing and retries.
• Integrations and lifecycle: authentication, cookies, redirects, streaming and transport ownership.
• Verification and release: evidence and limits.
• Client API, request API, configuration API.

The executed client notebook demonstrates provider HTML, JSON services, batching, retries, authentication and streaming against local fixtures. These outputs do not establish that a live site will always return the required data.

During migration, this workspace consumes released common-execution/core from the old common repository. Their reserved directories are excluded from workspace resolution and publication. See the release guide.