API References

class src.adapter.BaseAdapter[source]

Abstract base class for HTTP adapters

Defines the interface that all HTTP adapter implementations must follow Adapters are responsible for executing the actual HTTP request and returning a Response object

request(method, url, **kwargs)[source]

Execute an HTTP request

Parameters:

method (str) – HTTP method (GET, POST, and so on)
url (str) – URL to request
**kwargs – Additional arguments for the adapter

Returns:

Response object containing status, headers, and body

Return type:

Response

Raises:

NotImplementedError – Must be implemented by subclass

class src.adapter.RequestsAdapter(pool_connections: int = 10, pool_maxsize: int = 50)[source]

HTTP adapter using the requests library

Provides connection pooling and advanced HTTP features through the requests library

close() → None[source]

Close the session and clean up connection pools.

Closes the underlying requests session, releasing all pooled connections and resources.

request(method: str, url: str, headers: dict = None, data: dict = None, timeout: int = None) → Response[source]

Execute an HTTP request using requests library.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
url (str) – URL to request
headers (dict, optional) – HTTP headers. Defaults to None.
data (dict, optional) – Request body data. Defaults to None.
timeout (int, optional) – Request timeout in seconds. Defaults to None.

Returns:

Response object with status code, headers, body, and elapsed time

Return type:

Response

class src.adapter.UrllibAdapter[source]

HTTP adapter using Python’s built-in urllib library.

Provides a lightweight HTTP adapter without external dependencies. Note: Does not support connection pooling

request(method: str, url: str, headers: dict = None, data: dict = None, timeout: int = 10) → Response[source]

Execute an HTTP request using urllib.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
url (str) – URL to request
headers (dict, optional) – HTTP headers. Defaults to None
data (dict, optional) – Request body data. Defaults to None
timeout (int, optional) – Request timeout in seconds. Defaults to 10

Returns:

Response object with status code, headers, body, and elapsed time

Return type:

Response

class src.client.HttpClient(adapter: str = 'urllib', middleware: list = None, headers: dict = None, **config)[source]

HTTP client for making requests with pluggable adapters and middleware.

Provides a unified interface for HTTP requests with support for different adapters (urllib, requests) and middleware processing (retry, logging, timeout, and also rate limit).

close() → None[source]

Close the client and clean up adapter resources.

Closes the underlying adapter and releases all connections if the adapter supports closing.

delete(url: str, **kwargs) → Response[source]

Send a DELETE request.

Parameters:

url (str) – URL to request
**kwargs – Additional request options (headers, timeout, etc.)

Returns:

Response object

Return type:

Response

get(url: str, **kwargs) → Response[source]

Send a GET request.

Parameters:

url (str) – URL to request
**kwargs – Additional request options (headers, timeout, etc.)

Returns:

Response object

Return type:

Response

head(url: str, **kwargs) → Response[source]

Send a HEAD request.

Parameters:

url (str) – URL to request
**kwargs – Additional request options (headers, timeout, etc.)

Returns:

Response object with no response body, headers preserved

Return type:

Response

options(url: str, **kwargs) → Response[source]

Send an OPTIONS request.

Parameters:

url (str) – URL to request
**kwargs – Additional request options (headers, timeout, etc.)

Returns:

Response object

Return type:

Response

patch(url: str, **kwargs) → Response[source]

Send a PATCH request.

Parameters:

url (str) – URL to request
**kwargs – Additional request options (headers, data, timeout, etc.)

Returns:

Response object

Return type:

Response

post(url: str, **kwargs) → Response[source]

Send a POST request.

Parameters:

url (str) – URL to request
**kwargs – Additional request options (headers, data, timeout, etc.)

Returns:

Response object

Return type:

Response

put(url: str, **kwargs) → Response[source]

Send a PUT request.

Parameters:

url (str) – URL to request
**kwargs – Additional request options (headers, data, timeout, etc.)

Returns:

Response object

Return type:

Response

request(method: str, url: str, **kwargs) → Response[source]

Execute an HTTP request with the specified method.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
url (str) – URL to request
**kwargs – Additional request options (headers, data, timeout, etc.)

Returns:

Response object containing status, headers, and body

Return type:

Response

src.middleware.logging(logger=<built-in function print>)[source]

Middleware that logs request and response information.

Logs HTTP method, URL, response status code, and elapsed time for each request.

Parameters:: logger (callable, optional) – Function to use for logging. Defaults to print. Will be called with formatted log strings.
Returns:: Middleware function to be passed to HttpClient
Return type:: function

src.middleware.rate_limit(calls: int = 10, period: float = 1.0)[source]

Middleware that enforces a rate limit across all requests through this client.

It will uses a sliding-window counter (and it’s thread-safe) to ensure no more than calls requests are processed within any period seconds window. It won’t drop requests silently but will delay them until they can be processed again

Parameters:

calls (int) – Maximum number of calls allowed within the specified period. defaults to 10.
period (float) – Time window in seconds for the rate limit. Defaults to 1.0

Returns:

Middleware function to be passed to HttpClient

Return type:

function

Raises:

ValueError – If calls is not postive or period is not positive.

src.middleware.retry(retries: int = 3, delay: float = 0.1, retry_on_status_code=None)[source]

Middleware that retries failed requests.

Automatically retries requests that fail with specified status codes or connection errors (status code 0).

Parameters:

retries (int, optional) – Number of retry attempts. Defaults to 3.
delay (float, optional) – Delay in seconds between retries. Defaults to 0.1.
retry_on_status_code (set, optional) – HTTP status codes to retry on. Defaults to {500, 502, 503, 504}.

Returns:

Middleware function to be passed to HttpClient

Return type:

function

src.middleware.timeout(seconds: float = 10.0)[source]

Middleware that enforces a timeout during request processing.

This is adapter-agnostic and will works with any adapter that supports the timeout parameter, such as requests, urllib or httpx.

Parameters:: seconds (float, optional) – Timeout duration in seconds. Defaults to 10.0.
Raises:: TimeoutError – If the request processing doesn’t compelete within the specified timeout duration.
Returns:: Middleware function to be passed to HttpClient
Return type:: function

class src.request.Request(method: str, url: str, headers: dict = None, data: dict = None, timeout: int = None)[source]

HTTP request object.

Created by HttpClient and passed through middleware chain. Contains all information needed to execute an HTTP request.

class src.response.Response(status_code: int, headers: dict, body: bytes, elapsed: float = None)[source]

HTTP response object.

Contains the status code, headers, body, and timing information from an HTTP response. Provides convenience methods for processing the response.

property elapsed_time: int | None

Get the elapsed time in milliseconds.

Returns:: Elapsed time in milliseconds, or None if not available
Return type:: int | None

is_ok() → bool[source]

Check if the response status code indicates success (2xx).

Returns:: True if status code is 200-299, False otherwise
Return type:: bool

json() → Any[source]

Parse the response body as JSON.

Returns:: Parsed JSON object
Return type:: Any
Raises:: ValueError – If response body is not valid JSON

raise_for_status() → None[source]

Raise an exception if the status code indicates an error.

Raises an exception for 4xx and 5xx status codes.

Raises:: Exception – If status code is 400-599

text() → str[source]

Get the response body as text.

Returns:: Response body decoded as UTF-8 string
Return type:: str