Registry / http-networking / aiohttp-retry

aiohttp-retry

JSON →
library2.9.1pypypi✓ verified 52d ago

aiohttp-retry is a simple retry client for aiohttp, providing robust request retrying capabilities for asynchronous HTTP operations. It supports various retry strategies like exponential backoff and random delays. The current version is 2.9.1 and it requires Python 3.7 or higher. The library is actively maintained with regular releases addressing bug fixes and introducing new features.

http-networking
pip install aiohttp-retry
Install & Compatibility
Where this runs
tested against v2.9.1 · 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.103.925 runs
installs and imports cleanly · install 0.0s · import 0.631s · 27.5MB
glibc
py 3.103.925 runs
installs and imports cleanly · install 3.9s · import 0.558s · 30MB
27MB installed
● package 27MB
Code
Verified usage

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

RetryClient
from aiohttp_retry import RetryClient
ExponentialRetry
from aiohttp_retry import ExponentialRetry
RandomRetry
from aiohttp_retry import RandomRetry
RetryOptions
from aiohttp_retry import RetryOptions
RequestParams
from aiohttp_retry import RequestParams

This quickstart demonstrates how to initialize a `RetryClient` with `ExponentialRetry` options and make a GET request. The `raise_for_status=False` parameter is often used to ensure that aiohttp-retry's retry logic can intercept and handle HTTP error responses instead of aiohttp immediately raising an exception. The example attempts to hit a 500 status endpoint, which should trigger the retry mechanism.

import asyncio from aiohttp_retry import RetryClient, ExponentialRetry async def main(): # Configure retry options, e.g., 3 attempts with exponential backoff retry_options = ExponentialRetry(attempts=3, start_timeout=0.1, factor=2) # Create a RetryClient instance # raise_for_status=False prevents aiohttp from raising exceptions for HTTP error statuses, # allowing aiohttp-retry to handle them based on its retry logic. async with RetryClient(raise_for_status=False, retry_options=retry_options) as retry_client: try: # Make a GET request that will be retried on failure async with retry_client.get('https://httpbin.org/status/500', retry_attempts=3) as response: print(f"Final status: {response.status}") print(f"Content-type: {response.headers.get('Content-Type')}") except Exception as e: print(f"Request failed after retries: {e}") if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
breakingVersion 2.0 introduced backward incompatible changes. If upgrading from versions prior to 2.0 (e.g., v1.2), expect breaking changes in API usage.
fix
Review the official documentation and examples for versions 2.0+ to adapt your code. Consider `pip install aiohttp-retry==1.2` if you cannot upgrade.
affects: <2.0.0
breakingThe `evaluate_response_callback` feature introduced a bug in versions 2.7.0 through 2.8.3 that could lead to infinite retries. These versions were yanked from PyPI.
fix
Upgrade to version 2.8.3 or higher (e.g., 2.9.1) to get the fix.
affects: 2.7.0 - 2.8.3
gotchaSince version 2.5.6, the `get_timeout` function in custom `RetryOptions` now receives an additional `response` parameter. If you have defined your own `RetryOptions` and custom `get_timeout` logic, it needs to be updated.
fix
Update your custom `get_timeout` signature to `def get_timeout(self, attempt_num: int, response: ClientResponse | None = None) -> float:`
affects: >=2.5.6
gotchaWhen using `ExponentialRetry` or similar, setting `start_timeout` and `factor` to 0 will cause all retries to occur in quick succession without any delay, defeating the purpose of a backoff strategy.
fix
Ensure `start_timeout` and `factor` are set to appropriate non-zero values to introduce delays between retry attempts.
affects: All versions
gotchaBy default, `RetryClient` retries on all 5xx HTTP responses. If you want to specify custom 5xx errors or disable default 5xx retries, you must pass `retry_all_server_errors=False` in `RetryClient` constructor and explicitly define `statuses` in `RetryOptions`.
fix
To customize 5xx behavior: `RetryClient(retry_all_server_errors=False, retry_options=RetryOptions(statuses={500, 503}))`
affects: All versions
breakingThe `retry_attempts` keyword argument has been removed from `RetryClient` methods (including internal ones like `_request`) starting from version 2.0.0. If your code, particularly when interacting with `RetryClient` methods, attempts to pass this argument, it will result in a `TypeError`.
fix
Remove the `retry_attempts` keyword argument from any calls where it is being used. To specify the total number of attempts (including the initial request), configure it via `RetryOptions` by setting the `attempts` parameter (e.g., `RetryOptions(attempts=3)`).
affects: >=2.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiohttp'
The 'aiohttp' package is not installed or not accessible in the current Python environment.
fix
Ensure 'aiohttp' is installed in the correct environment by running 'python3.6 -m pip install aiohttp'.
message='Attempt to decode JSON with unexpected mimetype: text/html; charset=utf-8'
The server responded with a non-JSON content type, causing a JSON decoding error.
fix
Implement error handling to manage unexpected content types and consider retrying the request upon failure.
ClientConnectorError: Cannot connect to host example.com:443 ssl:default [Connect call failed]
The client is unable to establish a connection to the specified host, possibly due to network issues or incorrect URL.
fix
Verify the URL and network connectivity; consider implementing retries with exponential backoff for transient errors.
ModuleNotFoundError: No module named 'aiohttp_retry'
The `aiohttp-retry` library is not installed in your Python environment or the environment where your code is being executed.
fix
Install the library using pip: `pip install aiohttp-retry`
TypeError: RetryClient.get() got an unexpected keyword argument 'retry_attempts'
This error occurs when using an older API parameter (`retry_attempts`) with `aiohttp-retry` versions 2.0.0 and newer. The `retry_attempts` keyword argument was removed in version 2.0.0.
fix
Instead of `retry_attempts`, configure the number of attempts via `RetryOptions` and pass it to the `RetryClient` constructor or the request method. For example: `from aiohttp_retry import RetryClient, ExponentialRetry; retry_options = ExponentialRetry(attempts=3); retry_client = RetryClient(retry_options=retry_options)` or `async with retry_client.get(url, retry_options=ExponentialRetry(attempts=3))`.
Upgrade
Version history
2.9.1latest on PyPI
Audit
Dependencies
aiohttprequiredaiohttp-retry is a wrapper client built on top of aiohttp for handling retries.
Agent activity
79 hits · last 30 days
node
12
seranking-bot
4
ahrefsbot
3
Amazon
1
amazonbot
1
bytedance
1
googlebot
1
Resources