Metadata-Version: 2.4
Name: rhttpx
Version: 0.1.0
Summary: rhttpx - Retrying HTTPX Client Package.
Author-email: Alex Semenyaka <alex.semenyaka@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: tenacity>=8.2.0
Dynamic: license-file

# rhttpx Package Documentation
[![PyPI version](https://img.shields.io/pypi/v/rhttpx.svg)](https://pypi.org/project/rhttpx/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rhttpx.svg)](https://pypi.org/project/rhttpx/)
[![PyPI - License](https://img.shields.io/pypi/l/rhttpx.svg)](https://pypi.org/project/rhttpx/)
[![Coverage Status](https://coveralls.io/repos/github/alexsemenyaka/rhttpx/badge.svg?branch=main)](https://coveralls.io/github/alexsemenyaka/rhttpx?branch=main)
[![CI/CD Status](https://github.com/alexsemenyaka/rhttpx/actions/workflows/ci.yml/badge.svg)](https://github.com/alexsemenyaka/rhttpx/actions/workflows/ci.yml)

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