Registry / http-networking / retry-requests

retry-requests

library2.0.0pypypi✓ verified 87d ago

retry-requests is a Python library that enhances `requests.Session` objects to automatically retry failed HTTP requests. It handles transient issues like connection errors, timeouts, and specific HTTP response codes (5XX and 3XX by default) with exponential backoff. Currently at version 2.0.0, the library is actively maintained, with releases as needed based on contributions and bug fixes.

http-networking

pip install retry-requests

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · RETRY-REQUESTS

retry-requests

http-networkingpythonv2.0.0

Install

2.1s avg

Import

565ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.600s · 21.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.530s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

retry

✓ from retry_requests import retry

The primary factory function to create a retry-enabled requests Session.

TSession

✓ from retry_requests import TSession

A convenience Session with a default timeout.

RSession

✓ from retry_requests import RSession

A convenience Session with a timeout that always calls `raise_for_status()`.

Demonstrates how to create a retry-enabled requests Session using the `retry` function, both with default settings and with custom retry attempts and backoff factor. It shows how the session automatically retries on specified HTTP status codes (like 503) or connection errors.

from retry_requests import retry from requests import Session # Basic usage with default retries (3 retries, exponential backoff) my_session = retry() try: response = my_session.get("https://httpbin.org/status/503") # Will retry on 503 response.raise_for_status() print(f"Success after retries: {response.status_code}") except Exception as e: print(f"Request failed after all retries: {e}") # Customizing retries and backoff # Example: 5 retries, backoff factor of 0.2 custom_session = retry(Session(), retries=5, backoff_factor=0.2) try: response = custom_session.get("https://httpbin.org/status/503") response.raise_for_status() print(f"Success after custom retries: {response.status_code}") except Exception as e: print(f"Request failed after custom retries: {e}")

Debug

Known issues

gotchaRetrying non-idempotent methods (e.g., POST, PUT, DELETE) by default can lead to unintended side effects if the initial request succeeded on the server but the response was lost. The underlying `urllib3.Retry` (used by requests) typically excludes POST by default, but be mindful when customising `method_whitelist` or similar parameters.

fix

Ensure that if you customize retry logic for non-GET methods, the target API endpoint is truly idempotent, or implement your own idempotency keys.

affects: All versions

gotchaConfiguring too many retries or a zero/fixed `backoff_factor` can lead to a 'retry storm' that overloads the target service, exacerbating the problem rather than solving it. This can result in IP bans or further service degradation.

fix

Use a reasonable `retries` count (e.g., 3-5) and always apply an exponential `backoff_factor` to avoid hammering the server. Default values often provide a good starting point.

affects: All versions

gotchaWhile `retry-requests` provides sensible defaults for retriable HTTP status codes (5XX, 3XX, connection errors), a common mistake is to extend `status_forcelist` to include non-transient errors like 400 Bad Request, 401 Unauthorized, or 404 Not Found. Retrying these errors will not resolve them and wastes resources.

fix

Only retry on transient error codes (e.g., 429, 500, 502, 503, 504) and connection issues. Handle client-side errors (4XX) by checking your request parameters or authentication before retrying.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'retry_requests'

The `retry-requests` library is not installed in the current environment or there is a typo in the import statement.

fix

First, install the library using pip: `pip install retry-requests`. Then, ensure the import statement is correct: `from retry_requests import retry`.

TypeError: retry() missing 1 required positional argument: 'session'

The `retry` function was called without providing a `requests.Session` instance (or a callable that returns one) as its first argument.

fix

Pass an instantiated `requests.Session` object to the `retry` function: `import requests; from retry_requests import retry; session = retry(requests.Session())`.

TypeError: retry() got an unexpected keyword argument 'max_retries'

The keyword argument used to specify the maximum number of retries is `retries`, not `max_retries` or similar variations.

fix

Use the correct parameter name `retries` when configuring the retry behavior: `session = retry(requests.Session(), retries=5)`.

ModuleNotFoundError: No module named 'retry'

The user is attempting to import `retry` directly, likely intending to import the `retry` function from the `retry-requests` library, but without specifying the correct package path.

fix

Use the correct import statement to get the `retry` function from the `retry-requests` package: `from retry_requests import retry`.

Upgrade

Version history

2.0.0latest on PyPI · released May 28, 2023

Audit

Dependencies

requestsrequiredCore dependency for making HTTP requests, which this library wraps for retry logic.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bustawin/retry-requests ↗

packagehttps://pypi.org/project/retry-requests/ ↗

docshttps://github.com/bustawin/retry-requests ↗