rhttpx 0.1.0

rhttpx - Retrying HTTPX Client Package.

rhttpx Package Documentation

Overview

The rhttpx package provides synchronous and asynchronous HTTP client wrappers based on httpx. It implements automatic exponential backoff retry mechanisms utilizing tenacity for network-level failures and server-side errors.

Class: RetryingClient

__init__

RetryingClient(**kwargs: Any) -> None

This method initializes a synchronous HTTP client instance with integrated retry logic.

It accepts max_attempts (integer, default 10), backoff_factor (float, default 1.5), initial_delay (float, default 1.0), alongside any standard keyword arguments supported by httpx.Client.

It instantiates and returns the configured RetryingClient object.

It raises a TypeError if unsupported keyword arguments are passed to the underlying httpx.Client constructor.

If the timeout parameter is explicitly set to None, the underlying client will wait indefinitely for server responses, which bypasses the network timeout triggers and can cause the retry logic to stall entirely on dropped connections.

request

request(method: str, url: str, **kwargs: Any) -> httpx.Response

This method executes an HTTP request using the specified method and URL, applying the configured exponential backoff strategy for network exceptions and 5xx HTTP status codes.

It requires the method (string) and target url (string), and accepts optional kwargs representing standard HTTP parameters or temporary overrides for max_attempts, backoff_factor, and initial_delay.

It returns a standard httpx.Response object representing the final server reply upon successful execution or upon receiving a non-retryable status code.

It raises httpx.HTTPStatusError if the maximum retry limit is reached and the final received response is a 5xx error, or propagates standard httpx network exceptions if underlying connectivity issues persist beyond the retry threshold.

Providing override retry parameters via kwargs modifies the behavior strictly for the lifecycle of that specific request execution, leaving the instance's base configuration unmodified for subsequent calls.

get, post, put, delete, patch

<method>(url: str, **kwargs: Any) -> httpx.Response

These methods act as convenience wrappers around the request method, executing an HTTP request with the corresponding implicit HTTP verb.

They require the target url (string) and accept optional kwargs for request payloads, headers, query parameters, or retry parameter overrides.

They return the resulting httpx.Response object upon successful execution or the exhaustion of non-retryable HTTP responses.

They propagate httpx.HTTPStatusError on persistent 5xx responses or underlying httpx network exceptions after all retry attempts fail.

When supplying data payloads such as streams or generators in methods like post or put, the data source must be replayable, as a triggered retry attempt will need to consume the payload from the beginning.

close

close() -> None

This method terminates the underlying synchronous httpx.Client session and safely closes all active transport connections in the connection pool.

It takes no arguments.

It returns None.

It does not inherently raise exceptions under normal operational conditions.

Calling this method on an already closed client instance results in a safe no-operation, but any subsequent HTTP request attempts utilizing this specific instance will raise a RuntimeError.

Class: AsyncRetryingClient

__init__

__init__(**kwargs: Any) -> None

This method initializes an asynchronous HTTP client instance with integrated retry logic for non-blocking operations.

It accepts max_attempts (integer, default 10), backoff_factor (float, default 1.5), initial_delay (float, default 1.0), and any standard keyword arguments supported by httpx.AsyncClient.

It instantiates and returns the configured AsyncRetryingClient object.

It raises a TypeError if unsupported keyword arguments are supplied to the underlying httpx.AsyncClient constructor.

Instantiating this class outside of an active asynchronous event loop is permitted, as the internal httpx.AsyncClient defers the creation of loop-bound resources until the first request is executed.

request

async request(method: str, url: str, **kwargs: Any) -> httpx.Response

This method executes an asynchronous HTTP request using the specified method and URL, applying the configured exponential backoff strategy for network exceptions and 5xx HTTP status codes.

It requires the method (string) and target url (string), and accepts optional kwargs representing standard HTTP parameters or temporary overrides for max_attempts, backoff_factor, and initial_delay.

It asynchronously yields a standard httpx.Response object representing the final server reply upon successful execution or upon receiving a non-retryable status code.

It raises httpx.HTTPStatusError if the maximum retry limit is reached and the final received response is a 5xx error, or propagates standard httpx network exceptions if underlying connectivity issues persist beyond the retry threshold.

Executing this method requires an active event loop; attempting to run it synchronously or across mismatched event loops will result in an asyncio RuntimeError.

get, post, put, delete, patch

async <method>(url: str, **kwargs: Any) -> httpx.Response

These methods act as asynchronous convenience wrappers around the request method, executing an HTTP request with the corresponding implicit HTTP verb.

They require the target url (string) and accept optional kwargs for request payloads, headers, query parameters, or retry parameter overrides.

They asynchronously yield the resulting httpx.Response object upon successful execution or the exhaustion of non-retryable HTTP responses.

They propagate httpx.HTTPStatusError on persistent 5xx responses or underlying httpx network exceptions after all retry attempts fail.

Similar to their synchronous counterparts, streaming payloads passed into post or put methods must support asynchronous rewinding or replayability to ensure data integrity during retry iterations.

aclose

async aclose() -> None

This method asynchronously terminates the underlying httpx.AsyncClient session and safely closes all active transport connections in the asynchronous connection pool.

It takes no arguments.

It returns None.

It does not inherently raise exceptions under normal operational conditions.

The method must be awaited within an active event loop context; failure to await the closure can lead to unclosed resource warnings emitted by the Python runtime during garbage collection.

Global Functions

request, get, post, put, delete, patch

request(method: str, url: str, **kwargs: Any) -> httpx.Response (and specific verb aliases)

These functions execute a synchronous HTTP request utilizing a globally maintained, lazy-loaded RetryingClient singleton instance.

They require the HTTP method (for request only), the target url (string), and accept optional kwargs for request parameters or retry configuration overrides.

They return the httpx.Response object generated by the global singleton session.

They raise httpx.HTTPStatusError on persistent 5xx server responses or standard httpx network exceptions after all retry attempts are exhausted.

The global singleton is initialized automatically upon the first invocation of any of these functions; if the global instance is externally manipulated or closed improperly, subsequent calls will transparently instantiate a fresh client to maintain continuity.

arequest, aget, apost, aput, adelete, apatch

async arequest(method: str, url: str, **kwargs: Any) -> httpx.Response (and specific verb aliases)

These functions execute an asynchronous HTTP request utilizing a globally maintained, lazy-loaded AsyncRetryingClient singleton instance.

They require the HTTP method (for arequest only), the target url (string), and accept optional kwargs for request parameters or retry configuration overrides.

They asynchronously yield the httpx.Response object generated by the global asynchronous singleton session.

They raise httpx.HTTPStatusError on persistent 5xx server responses or standard httpx network exceptions after all retry attempts are exhausted.

The global asynchronous instance binds to the specific event loop active during its initialization; invoking these functions from a distinctly different thread or a newly created event loop will trigger cross-loop execution exceptions.

close

close() -> None

This function explicitly terminates the globally maintained synchronous singleton client and releases its associated connection pool resources.

It takes no arguments.

It returns None.

It does not raise exceptions.

If this function is called prior to any synchronous global requests being made, or after the client has already been closed, it exits silently without applying any state changes.

aclose

async aclose() -> None

This function explicitly and asynchronously terminates the globally maintained asynchronous singleton client and releases its event loop resources.

It takes no arguments.

It returns None.

It does not raise exceptions.

This function acts as a safeguard for clean application teardowns; if invoked when the global asynchronous instance does not exist, the awaitable completes instantly without errors.