HTTP Client Management

Optional dependency injection for HTTP client lifecycle management.

All public I/O functions accept an optional http_client parameter. When omitted (default), the library uses its built-in client management (module-level singleton for async, thread-local for sync). When provided, the injected client is used instead.

Sync Client

from py_identity_model import HTTPClient, get_discovery_document, DiscoveryDocumentRequest

with HTTPClient() as client:
    disco = get_discovery_document(
        DiscoveryDocumentRequest(address="https://..."),
        http_client=client,
    )

HTTPClient(client=None, timeout=None, verify=None)

Managed sync HTTP client with optional lifecycle ownership.

When constructed without an explicit client, a new httpx.Client is created and owned by this instance — calling :meth:close (or exiting the context manager) will close it.

When an existing client is provided, this instance acts as a non-owning wrapper and :meth:close is a no-op. Passing timeout or verify together with an existing client raises ValueError because those parameters only apply to newly created clients.

Parameters:

Name	Type	Description	Default
client	Client | None	Existing httpx.Client to wrap. If None, a new client is created with the given timeout and verify settings.	None
timeout	float | None	Request timeout in seconds. Defaults to the HTTP_TIMEOUT environment variable or 30.0.	None
verify	bool | str | None	SSL verification. Pass True/False or a CA bundle path. Defaults to None which uses environment-based configuration (see :mod:py_identity_model.ssl_config).	None

Raises:

Type	Description
ValueError	If timeout or verify are provided alongside an existing client.
RuntimeError	If the client is accessed after :meth:close.

client property

The underlying httpx.Client.

close()

Close the client if this instance owns it. Idempotent.

Async Client

from py_identity_model.aio import AsyncHTTPClient, get_discovery_document

async with AsyncHTTPClient() as client:
    disco = await get_discovery_document(
        DiscoveryDocumentRequest(address="https://..."),
        http_client=client,
    )

AsyncHTTPClient(client=None, timeout=None, verify=None)

Managed async HTTP client with optional lifecycle ownership.

When constructed without an explicit client, a new httpx.AsyncClient is created and owned by this instance — calling :meth:close (or exiting the context manager) will close it.

When an existing client is provided, this instance acts as a non-owning wrapper and :meth:close is a no-op. Passing timeout or verify together with an existing client raises ValueError because those parameters only apply to newly created clients.

Parameters:

Name	Type	Description	Default
client	AsyncClient | None	Existing httpx.AsyncClient to wrap. If None, a new client is created with the given timeout and verify settings.	None
timeout	float | None	Request timeout in seconds. Defaults to the HTTP_TIMEOUT environment variable or 30.0.	None
verify	bool | str | None	SSL verification. Pass True/False or a CA bundle path. Defaults to None which uses environment-based configuration (see :mod:py_identity_model.ssl_config).	None

Raises:

Type	Description
ValueError	If timeout or verify are provided alongside an existing client.
RuntimeError	If the client is accessed after :meth:close.

client property

The underlying httpx.AsyncClient.

close() async

Close the client if this instance owns it. Idempotent.