nemoguardrails.http
Transport-neutral asynchronous HTTP clients for NeMo Guardrails integrations.
Submodules
nemoguardrails.http.clientnemoguardrails.http.compositionnemoguardrails.http.errorsnemoguardrails.http.instrumentednemoguardrails.http.requestnemoguardrails.http.retrynemoguardrails.http.runtimenemoguardrails.http.telemetrynemoguardrails.http.transportnemoguardrails.http.types
Package Contents
Classes
Functions
API
Bases: HTTPClient
An HTTP client that exposes asynchronous resource cleanup.
Release resources owned by the client.
Implementations must make repeated calls safe.
Send asynchronous HTTP requests without exposing transport-specific types.
Send one request and return a response whose content is fully owned.
Parameters:
HTTP method, case-insensitive.
Absolute request URL.
Optional request headers.
Optional query parameters.
Optional JSON-serializable request body.
Optional raw request body.
Optional total request timeout in seconds.
Returns: HTTPResponse
A transport-neutral response containing materialized body bytes.
Bases: Exception
Base class for outbound HTTP failures.
retry_count records how many retries completed before the error was
returned to the caller.
Bases: HTTPClientError
Raised when the transport cannot establish or maintain a connection.
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.
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.
Return whether the status code is in the 2xx range.
Decode the response body using its declared charset or UTF-8.
Decode the response body as JSON.
Raises:
HTTPResponseDecodeError: If the body is not valid JSON.
Raise HTTPStatusError for status codes of 400 or greater.
Bases: HTTPClientError
Raised when a response body cannot be decoded as JSON.
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.
Bases: HTTPClientError
Raised when an outbound request exceeds its total timeout.
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.
Return this client from an asynchronous context manager.
Close owned resources when leaving an asynchronous context.
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.
Send one request and materialize the HTTPX response.
Parameters:
HTTP method.
Absolute request URL.
Optional request headers.
Optional query parameters.
Optional JSON-serializable request body.
Optional raw request body.
Optional per-request total timeout in seconds.
Returns: 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.
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.
Return the underlying client for direct access or re-instrumentation.
Return an existing instrumented client without wrapping it again.
Apply the current instrumentation settings to another client.
Close the wrapped client without taking ownership from its caller.
Repeated calls are safe. A failed or cancelled close remains retryable.
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.
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.
Return whether the policy permits retrying the HTTP method.
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.
Return whether a response status or opted-in override requests a retry.
Apply a retry policy around another transport-neutral HTTP client.
Closing this wrapper closes the wrapped client only when it implements
ClosableHTTPClient.
Return the underlying client.
Return this client from an asynchronous context manager.
Close wrapped resources when leaving an asynchronous context.
Apply the current retry settings to another client.
Close the wrapped closable client at most once.
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.
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:
Optional caller-owned HTTPX client.
Total timeout for a client created by this function.
Connection-pool limits for a client created by this function.
RetryPolicy | None — Optional policy applied to created or injected clients.
Whether a client created by this function follows redirects.
HTTPTLSConfig | None — TLS settings for a client created by this function.
Returns: ClosableHTTPClient
A closable transport-neutral HTTP client.
Raises:
ValueError: If non-default owned-client options are supplied with an injected client.
Execute one outbound HTTP request with deterministic client ownership.
Parameters:
HTTPClient | None — Optional caller-owned client. When omitted, factory creates
a client that is closed after the request.
HTTP method.
Absolute request URL.
Optional request headers.
Optional query parameters.
Optional JSON-serializable request body.
Optional raw request body.
Optional total request timeout in seconds.
Whether responses with status 400 or greater raise.
Callable[[], ClosableHTTPClient ] — Factory for an owned client when client is omitted.
Returns: HTTPResponse
The materialized transport-neutral response.
Raises:
HTTPStatusError: Ifraise_for_statusis enabled and the response status is 400 or greater.TypeError: Iffactoryreturns a client that cannot be closed.
Return client decorated with the requested HTTP telemetry.
The original client is returned when telemetry is disabled or the client is already instrumented.