Skip to navigation

Transport-neutral asynchronous HTTP clients for NeMo Guardrails integrations.

Submodules

Package Contents

Classes

NameDescription
ClosableHTTPClientAn HTTP client that exposes asynchronous resource cleanup.
HTTPClientSend asynchronous HTTP requests without exposing transport-specific types.
HTTPClientErrorBase class for outbound HTTP failures.
HTTPConnectionErrorRaised when the transport cannot establish or maintain a connection.
HTTPRequestDescribe an outbound HTTP request without transport-specific objects.
HTTPResponseA materialized, transport-neutral HTTP response.
HTTPResponseDecodeErrorRaised when a response body cannot be decoded as JSON.
HTTPStatusErrorRaised for an unsuccessful HTTP status.
HTTPTLSConfigConfigure TLS verification and optional mutual authentication.
HTTPTimeoutErrorRaised when an outbound request exceeds its total timeout.
HttpxHTTPClientAdapt an HTTPX asynchronous client to the neutral HTTP contract.
InstrumentedHTTPClientDecorate an HTTP client with privacy-safe tracing and metrics.
RetryPolicyConfigure bounded retries for an HTTP client.
RetryingHTTPClientApply a retry policy around another transport-neutral HTTP client.

Functions

NameDescription
create_http_clientCreate a transport-neutral HTTP client with optional retry behavior.
http_callExecute one outbound HTTP request with deterministic client ownership.
instrument_http_clientReturn client decorated with the requested HTTP telemetry.

API

class nemoguardrails.http.ClosableHTTPClient()
Protocol

Bases: HTTPClient

An HTTP client that exposes asynchronous resource cleanup.

nemoguardrails.http.ClosableHTTPClient.close() -> None
async

Release resources owned by the client.

Implementations must make repeated calls safe.

class nemoguardrails.http.HTTPClient()
Protocol

Send asynchronous HTTP requests without exposing transport-specific types.

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
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] | NoneDefaults to None

Optional request headers.

params
Mapping[str, Any] | NoneDefaults to None

Optional query parameters.

json
AnyDefaults to None

Optional JSON-serializable request body.

content
bytes | str | NoneDefaults to None

Optional raw request body.

timeout
float | NoneDefaults to None

Optional total request timeout in seconds.

Returns: HTTPResponse

A transport-neutral response containing materialized body bytes.

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
class nemoguardrails.http.HTTPConnectionError()

Bases: HTTPClientError

Raised when the transport cannot establish or maintain a connection.

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
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.

nemoguardrails.http.HTTPResponse.json() -> typing.Any

Decode the response body as JSON.

Raises:

  • HTTPResponseDecodeError: If the body is not valid JSON.
nemoguardrails.http.HTTPResponse.raise_for_status(
) -> None

Raise HTTPStatusError for status codes of 400 or greater.

class nemoguardrails.http.HTTPResponseDecodeError(
)

Bases: HTTPClientError

Raised when a response body cannot be decoded as JSON.

class nemoguardrails.http.HTTPStatusError(
)

Bases: HTTPClientError

Raised for an unsuccessful HTTP status.

retry_count
= retry_count if isinstance(retry_count, int) else 0
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
nemoguardrails.http.HTTPTLSConfig.__post_init__() -> None
class nemoguardrails.http.HTTPTimeoutError()

Bases: HTTPClientError

Raised when an outbound request exceeds its total timeout.

class nemoguardrails.http.HttpxHTTPClient(
client: httpx.AsyncClient | None = None,
timeout: float | None = _DEFAULT_TIMEOUT_SECONDS,
limits: httpx.Limits | None = None,
follow_redirects: bool = False,
)

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
nemoguardrails.http.HttpxHTTPClient.__aenter__() -> nemoguardrails.http.transport.HttpxHTTPClient
async

Return this client from an asynchronous context manager.

nemoguardrails.http.HttpxHTTPClient.__aexit__(
exc_type: object,
exc_value: object,
traceback: object
) -> None
async

Close owned resources when leaving an asynchronous context.

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.

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
async

Send one request and materialize the HTTPX response.

Parameters:

method
str

HTTP method.

url
str

Absolute request URL.

headers
Mapping[str, str] | NoneDefaults to None

Optional request headers.

params
Mapping[str, Any] | NoneDefaults to None

Optional query parameters.

json
AnyDefaults to None

Optional JSON-serializable request body.

content
bytes | str | NoneDefaults to None

Optional raw request body.

timeout
float | NoneDefaults to None

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.
class nemoguardrails.http.InstrumentedHTTPClient(
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.

nemoguardrails.http.InstrumentedHTTPClient.__new__(
args: typing.Any = (),
kwargs: typing.Any = {}
)

Return an existing instrumented client without wrapping it again.

nemoguardrails.http.InstrumentedHTTPClient._with_wrapped_client(

Apply the current instrumentation settings to another client.

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.

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
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.

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]
nemoguardrails.http.RetryPolicy.__post_init__() -> None
nemoguardrails.http.RetryPolicy.can_retry_method(
method: str
) -> bool

Return whether the policy permits retrying the HTTP method.

nemoguardrails.http.RetryPolicy.retry_after(
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.

nemoguardrails.http.RetryPolicy.should_retry(
) -> bool

Return whether a response status or opted-in override requests a retry.

class nemoguardrails.http.RetryingHTTPClient(
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.

nemoguardrails.http.RetryingHTTPClient.__aenter__() -> nemoguardrails.http.retry.RetryingHTTPClient
async

Return this client from an asynchronous context manager.

nemoguardrails.http.RetryingHTTPClient.__aexit__(
exc_type: object,
exc_value: object,
traceback: object
) -> None
async

Close wrapped resources when leaving an asynchronous context.

nemoguardrails.http.RetryingHTTPClient._backoff(
retries: int
) -> float
nemoguardrails.http.RetryingHTTPClient._with_wrapped_client(

Apply the current retry settings to another client.

nemoguardrails.http.RetryingHTTPClient.close() -> None
async

Close the wrapped closable client at most once.

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
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.

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,

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 | NoneDefaults to None

Optional caller-owned HTTPX client.

timeout
float | NoneDefaults to 30.0

Total timeout for a client created by this function.

limits
httpx.Limits | NoneDefaults to None

Connection-pool limits for a client created by this function.

retry_policy
RetryPolicy | NoneDefaults to None

RetryPolicy | None — Optional policy applied to created or injected clients.

follow_redirects
boolDefaults to False

Whether a client created by this function follows redirects.

tls
HTTPTLSConfig | NoneDefaults to None

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.
nemoguardrails.http.http_call(
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
async

Execute one outbound HTTP request with deterministic client ownership.

Parameters:

client
HTTPClient | None

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] | NoneDefaults to None

Optional request headers.

params
Mapping[str, Any] | NoneDefaults to None

Optional query parameters.

json
AnyDefaults to None

Optional JSON-serializable request body.

content
bytes | str | NoneDefaults to None

Optional raw request body.

timeout
float | NoneDefaults to None

Optional total request timeout in seconds.

raise_for_status
boolDefaults to True

Whether responses with status 400 or greater raise.

factory
Callable[[], ClosableHTTPClient]Defaults to create_http_client

Callable[[], ClosableHTTPClient ] — Factory for an owned client when client is omitted.

Returns: 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.
nemoguardrails.http.instrument_http_client(
tracer: opentelemetry.trace.Tracer | None = None,
metrics_enabled: bool = False

Return client decorated with the requested HTTP telemetry.

The original client is returned when telemetry is disabled or the client is already instrumented.