> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/llms.txt. # nemoguardrails.http Transport-neutral asynchronous HTTP clients for NeMo Guardrails integrations. ## Submodules * **[`nemoguardrails.http.client`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client)** * **[`nemoguardrails.http.composition`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/composition)** * **[`nemoguardrails.http.errors`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/errors)** * **[`nemoguardrails.http.instrumented`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/instrumented)** * **[`nemoguardrails.http.request`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/request)** * **[`nemoguardrails.http.retry`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/retry)** * **[`nemoguardrails.http.runtime`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/runtime)** * **[`nemoguardrails.http.telemetry`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/telemetry)** * **[`nemoguardrails.http.transport`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/transport)** * **[`nemoguardrails.http.types`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types)** ## Package Contents ### Classes | Name | Description | | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | [`ClosableHTTPClient`](#nemoguardrails-http-client-ClosableHTTPClient) | An HTTP client that exposes asynchronous resource cleanup. | | [`HTTPClient`](#nemoguardrails-http-client-HTTPClient) | Send asynchronous HTTP requests without exposing transport-specific types. | | [`HTTPClientError`](#nemoguardrails-http-errors-HTTPClientError) | Base class for outbound HTTP failures. | | [`HTTPConnectionError`](#nemoguardrails-http-errors-HTTPConnectionError) | Raised when the transport cannot establish or maintain a connection. | | [`HTTPRequest`](#nemoguardrails-http-types-HTTPRequest) | Describe an outbound HTTP request without transport-specific objects. | | [`HTTPResponse`](#nemoguardrails-http-types-HTTPResponse) | A materialized, transport-neutral HTTP response. | | [`HTTPResponseDecodeError`](#nemoguardrails-http-errors-HTTPResponseDecodeError) | Raised when a response body cannot be decoded as JSON. | | [`HTTPStatusError`](#nemoguardrails-http-errors-HTTPStatusError) | Raised for an unsuccessful HTTP status. | | [`HTTPTLSConfig`](#nemoguardrails-http-types-HTTPTLSConfig) | Configure TLS verification and optional mutual authentication. | | [`HTTPTimeoutError`](#nemoguardrails-http-errors-HTTPTimeoutError) | Raised when an outbound request exceeds its total timeout. | | [`HttpxHTTPClient`](#nemoguardrails-http-transport-HttpxHTTPClient) | Adapt an HTTPX asynchronous client to the neutral HTTP contract. | | [`InstrumentedHTTPClient`](#nemoguardrails-http-instrumented-InstrumentedHTTPClient) | Decorate an HTTP client with privacy-safe tracing and metrics. | | [`RetryPolicy`](#nemoguardrails-http-retry-RetryPolicy) | Configure bounded retries for an HTTP client. | | [`RetryingHTTPClient`](#nemoguardrails-http-retry-RetryingHTTPClient) | Apply a retry policy around another transport-neutral HTTP client. | ### Functions | Name | Description | | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | [`create_http_client`](#nemoguardrails-http-runtime-create_http_client) | Create a transport-neutral HTTP client with optional retry behavior. | | [`http_call`](#nemoguardrails-http-request-http_call) | Execute one outbound HTTP request with deterministic client ownership. | | [`instrument_http_client`](#nemoguardrails-http-instrumented-instrument_http_client) | Return `client` decorated with the requested HTTP telemetry. | ### API ```python class nemoguardrails.http.ClosableHTTPClient() ``` Protocol **Bases:** [HTTPClient](#nemoguardrails-http-client-HTTPClient) An HTTP client that exposes asynchronous resource cleanup. ```python nemoguardrails.http.ClosableHTTPClient.close() -> None ``` async Release resources owned by the client. Implementations must make repeated calls safe. ```python class nemoguardrails.http.HTTPClient() ``` Protocol Send asynchronous HTTP requests without exposing transport-specific types. ```python nemoguardrails.http.HTTPClient.request( method: str, url: str, headers: typing.Mapping[str, str] | None = None, params: typing.Mapping[str, typing.Any] | None = None, json: typing.Any = None, content: bytes | str | None = None, timeout: float | None = None ) -> nemoguardrails.http.types.HTTPResponse ``` async Send one request and return a response whose content is fully owned. **Parameters:** **`method`** `str` HTTP method, case-insensitive. --- **`url`** `str` Absolute request URL. --- **`headers`** `Mapping[str, str] | None` — default: None Optional request headers. --- **`params`** `Mapping[str, Any] | None` — default: None Optional query parameters. --- **`json`** `Any` — default: None Optional JSON-serializable request body. --- **`content`** `bytes | str | None` — default: None Optional raw request body. --- **`timeout`** `float | None` — default: None Optional total request timeout in seconds. --- **Returns:** [`HTTPResponse`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPResponse) A transport-neutral response containing materialized body bytes. ```python class nemoguardrails.http.HTTPClientError( args: object = () ) ``` Exception **Bases:** `Exception` Base class for outbound HTTP failures. `retry_count` records how many retries completed before the error was returned to the caller. **`retry_count`** `= 0` --- ```python class nemoguardrails.http.HTTPConnectionError() ``` **Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError) Raised when the transport cannot establish or maintain a connection. ```python class nemoguardrails.http.HTTPRequest( method: str, url: str, headers: typing.Mapping[str, str] | None = None, params: typing.Mapping[str, typing.Any] | None = None, json: typing.Any = None, content: bytes | str | None = None, timeout: float | None = None ) ``` Dataclass Describe an outbound HTTP request without transport-specific objects. The value is suitable for status-error context and deterministic test assertions. It does not perform a request itself. **`content`** `bytes | str | None = None` --- **`headers`** `Mapping[str, str] | None = None` --- **`method`** `str` --- **`params`** `Mapping[str, Any] | None = None` --- **`timeout`** `float | None = None` --- **`url`** `str` --- ```python class nemoguardrails.http.HTTPResponse( status_code: int, headers: typing.Mapping[str, str] = dict(), content: bytes = b'', extensions: typing.Mapping[str, typing.Any] = dict() ) ``` Dataclass A materialized, transport-neutral HTTP response. `content` owns the response bytes, so callers can decode the body after the transport or client context has closed. `extensions` carries optional non-portable metadata without changing the core contract. **`content`** `bytes = b''` --- **`extensions`** `Mapping[str, Any] = field(default_factory=dict)` --- **`headers`** `Mapping[str, str] = field(default_factory=dict)` --- **`is_success`** `bool` Return whether the status code is in the 2xx range. --- **`status_code`** `int` --- **`text`** `str` Decode the response body using its declared charset or UTF-8. --- ```python nemoguardrails.http.HTTPResponse.json() -> typing.Any ``` Decode the response body as JSON. **Raises:** * `HTTPResponseDecodeError`: If the body is not valid JSON. ```python nemoguardrails.http.HTTPResponse.raise_for_status( request: nemoguardrails.http.types.HTTPRequest | None = None ) -> None ``` Raise `HTTPStatusError` for status codes of 400 or greater. ```python class nemoguardrails.http.HTTPResponseDecodeError( response: nemoguardrails.http.types.HTTPResponse ) ``` **Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError) Raised when a response body cannot be decoded as JSON. ```python class nemoguardrails.http.HTTPStatusError( response: nemoguardrails.http.types.HTTPResponse, request: nemoguardrails.http.types.HTTPRequest | None = None ) ``` **Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError) Raised for an unsuccessful HTTP status. **`retry_count`** `= retry_count if isinstance(retry_count, int) else 0` --- ```python class nemoguardrails.http.HTTPTLSConfig( verify: bool = True, ca_bundle: str | None = None, client_certificate: str | None = None, client_key: str | None = None ) ``` Dataclass Configure TLS verification and optional mutual authentication. A custom CA bundle applies only when verification is enabled. Client certificate and key paths must be supplied together. **`ca_bundle`** `str | None = None` --- **`client_certificate`** `str | None = None` --- **`client_key`** `str | None = None` --- **`verify`** `bool = True` --- ```python nemoguardrails.http.HTTPTLSConfig.__post_init__() -> None ``` ```python class nemoguardrails.http.HTTPTimeoutError() ``` **Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError) Raised when an outbound request exceeds its total timeout. ```python class nemoguardrails.http.HttpxHTTPClient( client: httpx.AsyncClient | None = None, timeout: float | None = _DEFAULT_TIMEOUT_SECONDS, limits: httpx.Limits | None = None, follow_redirects: bool = False, tls: nemoguardrails.http.types.HTTPTLSConfig | None = None ) ``` Adapt an HTTPX asynchronous client to the neutral HTTP contract. A client created by this adapter is owned and closed by the adapter. An injected client remains owned by its caller. The configured timeout covers the complete request rather than each HTTPX timeout phase independently. **`_client`** --- **`_close_task`** `Task[None] | None = None` --- **`_owns_client`** `= client is None` --- **`_timeout`** `= timeout if self._owns_client else None` --- ```python nemoguardrails.http.HttpxHTTPClient.__aenter__() -> nemoguardrails.http.transport.HttpxHTTPClient ``` async Return this client from an asynchronous context manager. ```python nemoguardrails.http.HttpxHTTPClient.__aexit__( exc_type: object, exc_value: object, traceback: object ) -> None ``` async Close owned resources when leaving an asynchronous context. ```python nemoguardrails.http.HttpxHTTPClient.close() -> None ``` async Close owned resources, retaining unfinished cleanup for another call. Caller cancellation leaves the transport close running; later calls await the same attempt. A failed close remains failed because HTTPX may already have discarded partially closed connection state. ```python nemoguardrails.http.HttpxHTTPClient.request( method: str, url: str, headers: typing.Mapping[str, str] | None = None, params: typing.Mapping[str, typing.Any] | None = None, json: typing.Any = None, content: bytes | str | None = None, timeout: float | None = None ) -> nemoguardrails.http.types.HTTPResponse ``` async Send one request and materialize the HTTPX response. **Parameters:** **`method`** `str` HTTP method. --- **`url`** `str` Absolute request URL. --- **`headers`** `Mapping[str, str] | None` — default: None Optional request headers. --- **`params`** `Mapping[str, Any] | None` — default: None Optional query parameters. --- **`json`** `Any` — default: None Optional JSON-serializable request body. --- **`content`** `bytes | str | None` — default: None Optional raw request body. --- **`timeout`** `float | None` — default: None Optional per-request total timeout in seconds. --- **Returns:** [`HTTPResponse`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPResponse) A neutral response containing copied headers and body bytes. **Raises:** * `HTTPTimeoutError`: If the request exceeds its total timeout. * `HTTPConnectionError`: If HTTPX reports a request failure. * `ValueError`: If the per-request timeout is not positive. ```python class nemoguardrails.http.InstrumentedHTTPClient( client: nemoguardrails.http.client.HTTPClient, tracer: opentelemetry.trace.Tracer | None, metrics_enabled: bool = False ) ``` Decorate an HTTP client with privacy-safe tracing and metrics. The decorator preserves request behavior and client ownership. Wrapping an existing `InstrumentedHTTPClient` is idempotent, and tracing and metrics can be enabled independently. **`_close_lock`** `= asyncio.Lock()` --- **`wrapped_client`** `HTTPClient` Return the underlying client for direct access or re-instrumentation. --- ```python nemoguardrails.http.InstrumentedHTTPClient.__new__( client: nemoguardrails.http.client.HTTPClient, args: typing.Any = (), kwargs: typing.Any = {} ) ``` Return an existing instrumented client without wrapping it again. ```python nemoguardrails.http.InstrumentedHTTPClient._with_wrapped_client( client: nemoguardrails.http.client.HTTPClient ) -> nemoguardrails.http.instrumented.InstrumentedHTTPClient ``` Apply the current instrumentation settings to another client. ```python nemoguardrails.http.InstrumentedHTTPClient.close() -> None ``` async Close the wrapped client without taking ownership from its caller. Repeated calls are safe. A failed or cancelled close remains retryable. ```python nemoguardrails.http.InstrumentedHTTPClient.request( method: str, url: str, headers: typing.Mapping[str, str] | None = None, params: typing.Mapping[str, typing.Any] | None = None, json: typing.Any = None, content: bytes | str | None = None, timeout: float | None = None ) -> nemoguardrails.http.types.HTTPResponse ``` async Forward one request while recording privacy-safe HTTP telemetry. Telemetry includes the method, sanitized URL, payload sizes, response status, and retry count. Header, query, body, and credential values are never recorded. ```python class nemoguardrails.http.RetryPolicy( max_attempts: int = 3, retryable_methods: frozenset[str] = (lambda: frozenset({'DELETE..., retryable_status_codes: frozenset[int] = (lambda: frozenset({408, 40..., initial_delay: float = 0.5, max_delay: float = 8.0, max_retry_after: float = 60.0, retry_transport_errors: bool = True, honor_retry_override_header: bool = False, clamp_retry_after: bool = False ) ``` Dataclass Configure bounded retries for an HTTP client. `max_attempts` includes the initial request. Methods are normalized to uppercase, and POST is intentionally absent from the safe default set. `Retry-After` values are honored only when they fall within `max_retry_after` unless clamping is explicitly enabled. Vendor override headers are ignored unless `honor_retry_override_header` is enabled. **`clamp_retry_after`** `bool = False` --- **`honor_retry_override_header`** `bool = False` --- **`initial_delay`** `float = 0.5` --- **`max_attempts`** `int = 3` --- **`max_delay`** `float = 8.0` --- **`max_retry_after`** `float = 60.0` --- **`retry_transport_errors`** `bool = True` --- **`retryable_methods`** `frozenset[str]` --- **`retryable_status_codes`** `frozenset[int]` --- ```python nemoguardrails.http.RetryPolicy.__post_init__() -> None ``` ```python nemoguardrails.http.RetryPolicy.can_retry_method( method: str ) -> bool ``` Return whether the policy permits retrying the HTTP method. ```python nemoguardrails.http.RetryPolicy.retry_after( response: nemoguardrails.http.types.HTTPResponse, now: datetime.datetime ) -> float | None ``` Return a usable `Retry-After` delay in seconds. Both delta-seconds and HTTP-date values are supported. Invalid or out-of-policy values return `None` so the client uses exponential backoff instead. ```python nemoguardrails.http.RetryPolicy.should_retry( response: nemoguardrails.http.types.HTTPResponse ) -> bool ``` Return whether a response status or opted-in override requests a retry. ```python class nemoguardrails.http.RetryingHTTPClient( client: nemoguardrails.http.client.HTTPClient, policy: nemoguardrails.http.retry.RetryPolicy | None = None, sleep: collections.abc.Callable[[float], collections.abc.Awaitable[None]] = asyncio.sleep, random_value: collections.abc.Callable[[], float] = random.random, now: collections.abc.Callable[[], datetime.datetime] | None = None ) ``` Apply a retry policy around another transport-neutral HTTP client. Closing this wrapper closes the wrapped client only when it implements `ClosableHTTPClient`. **`_now`** `= now or (lambda: datetime.now(timezone.utc))` --- **`_policy`** `= policy or RetryPolicy()` --- **`wrapped_client`** `HTTPClient` Return the underlying client. --- ```python nemoguardrails.http.RetryingHTTPClient.__aenter__() -> nemoguardrails.http.retry.RetryingHTTPClient ``` async Return this client from an asynchronous context manager. ```python nemoguardrails.http.RetryingHTTPClient.__aexit__( exc_type: object, exc_value: object, traceback: object ) -> None ``` async Close wrapped resources when leaving an asynchronous context. ```python nemoguardrails.http.RetryingHTTPClient._backoff( retries: int ) -> float ``` ```python nemoguardrails.http.RetryingHTTPClient._with_wrapped_client( client: nemoguardrails.http.client.HTTPClient ) -> nemoguardrails.http.retry.RetryingHTTPClient ``` Apply the current retry settings to another client. ```python nemoguardrails.http.RetryingHTTPClient.close() -> None ``` async Close the wrapped closable client at most once. ```python nemoguardrails.http.RetryingHTTPClient.request( method: str, url: str, headers: typing.Mapping[str, str] | None = None, params: typing.Mapping[str, typing.Any] | None = None, json: typing.Any = None, content: bytes | str | None = None, timeout: float | None = None ) -> nemoguardrails.http.types.HTTPResponse ``` async Send a request and retry eligible failures within policy bounds. The returned response includes `retry_count` in its extensions. Transport errors also expose their completed retry count before being re-raised. ```python nemoguardrails.http.create_http_client( httpx_client: httpx.AsyncClient | None = None, timeout: float | None = 30.0, limits: httpx.Limits | None = None, retry_policy: nemoguardrails.http.retry.RetryPolicy | None = None, follow_redirects: bool = False, tls: nemoguardrails.http.types.HTTPTLSConfig | None = None ) -> nemoguardrails.http.client.ClosableHTTPClient ``` Create a transport-neutral HTTP client with optional retry behavior. When `httpx_client` is provided, it remains caller-owned and `timeout`, `limits`, `follow_redirects`, and `tls` must retain their defaults. `retry_policy` is still applied when supplied. **Parameters:** **`httpx_client`** `httpx.AsyncClient | None` — default: None Optional caller-owned HTTPX client. --- **`timeout`** `float | None` — default: 30.0 Total timeout for a client created by this function. --- **`limits`** `httpx.Limits | None` — default: None Connection-pool limits for a client created by this function. --- **`retry_policy`** `RetryPolicy | None` — default: None [`RetryPolicy`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/retry#nemoguardrails-http-retry-RetryPolicy) `| None` — Optional policy applied to created or injected clients. --- **`follow_redirects`** `bool` — default: False Whether a client created by this function follows redirects. --- **`tls`** `HTTPTLSConfig | None` — default: None [`HTTPTLSConfig`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPTLSConfig) `| None` — TLS settings for a client created by this function. --- **Returns:** [`ClosableHTTPClient`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client#nemoguardrails-http-client-ClosableHTTPClient) A closable transport-neutral HTTP client. **Raises:** * `ValueError`: If non-default owned-client options are supplied with an injected client. ```python nemoguardrails.http.http_call( client: nemoguardrails.http.client.HTTPClient | None, method: str, url: str, headers: typing.Mapping[str, str] | None = None, params: typing.Mapping[str, typing.Any] | None = None, json: typing.Any = None, content: bytes | str | None = None, timeout: float | None = None, raise_for_status: bool = True, factory: collections.abc.Callable[[], nemoguardrails.http.client.ClosableHTTPClient] = create_http_client ) -> nemoguardrails.http.types.HTTPResponse ``` async Execute one outbound HTTP request with deterministic client ownership. **Parameters:** **`client`** `HTTPClient | None` [`HTTPClient`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client#nemoguardrails-http-client-HTTPClient) `| None` — Optional caller-owned client. When omitted, `factory` creates a client that is closed after the request. --- **`method`** `str` HTTP method. --- **`url`** `str` Absolute request URL. --- **`headers`** `Mapping[str, str] | None` — default: None Optional request headers. --- **`params`** `Mapping[str, Any] | None` — default: None Optional query parameters. --- **`json`** `Any` — default: None Optional JSON-serializable request body. --- **`content`** `bytes | str | None` — default: None Optional raw request body. --- **`timeout`** `float | None` — default: None Optional total request timeout in seconds. --- **`raise_for_status`** `bool` — default: True Whether responses with status 400 or greater raise. --- **`factory`** `Callable[[], ClosableHTTPClient]` — default: create_http_client `Callable[[],` [`ClosableHTTPClient`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client#nemoguardrails-http-client-ClosableHTTPClient) `]` — Factory for an owned client when `client` is omitted. --- **Returns:** [`HTTPResponse`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPResponse) The materialized transport-neutral response. **Raises:** * `HTTPStatusError`: If `raise_for_status` is enabled and the response status is 400 or greater. * `TypeError`: If `factory` returns a client that cannot be closed. ```python nemoguardrails.http.instrument_http_client( client: nemoguardrails.http.client.HTTPClient, tracer: opentelemetry.trace.Tracer | None = None, metrics_enabled: bool = False ) -> nemoguardrails.http.client.HTTPClient ``` Return `client` decorated with the requested HTTP telemetry. The original client is returned when telemetry is disabled or the client is already instrumented. ## Docs - [nemoguardrails.http.client](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client.md) - [nemoguardrails.http.composition](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/composition.md) - [nemoguardrails.http.errors](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/errors.md) - [nemoguardrails.http.instrumented](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/instrumented.md) - [nemoguardrails.http.request](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/request.md) - [nemoguardrails.http.retry](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/retry.md) - [nemoguardrails.http.runtime](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/runtime.md) - [nemoguardrails.http.telemetry](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/telemetry.md) - [nemoguardrails.http.transport](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/transport.md) - [nemoguardrails.http.types](https://docs.nvidia.com/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types.md)