# aiohttp-client-cache
[![Build status](https://github.com/requests-cache/aiohttp-client-cache/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/requests-cache/aiohttp-client-cache/actions)
[![Documentation Status](https://img.shields.io/readthedocs/aiohttp-client-cache/latest?label=docs)](https://aiohttp-client-cache.readthedocs.io/en/stable/)
[![Codecov](https://codecov.io/gh/requests-cache/aiohttp-client-cache/branch/main/graph/badge.svg?token=I6PNLYTILM)](https://codecov.io/gh/requests-cache/aiohttp-client-cache)
[![PyPI](https://img.shields.io/pypi/v/aiohttp-client-cache?color=blue)](https://pypi.org/project/aiohttp-client-cache)
[![Conda](https://img.shields.io/conda/vn/conda-forge/aiohttp-client-cache?color=blue)](https://anaconda.org/conda-forge/aiohttp-client-cache)
[![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/aiohttp-client-cache)](https://pypi.org/project/aiohttp-client-cache)
[![PyPI - Format](https://img.shields.io/pypi/format/aiohttp-client-cache?color=blue)](https://pypi.org/project/aiohttp-client-cache)
**aiohttp-client-cache** is an async persistent cache for [aiohttp](https://docs.aiohttp.org)
client requests, based on [requests-cache](https://github.com/reclosedev/requests-cache).
# Features
- **Ease of use:** Use as a [drop-in replacement](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html)
for `aiohttp.ClientSession`
- **Customization:** Works out of the box with little to no config, but with plenty of options
available for customizing cache
[expiration](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html#cache-expiration)
and other [behavior](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html#cache-options)
- **Persistence:** Includes several [storage backends](https://aiohttp-client-cache.readthedocs.io/en/stable/backends.html):
SQLite, DynamoDB, MongoDB, DragonflyDB and Redis.
# Quickstart
First, install with pip (python 3.8+ required):
```bash
pip install aiohttp-client-cache[all]
```
**Note:**
Adding `[all]` will install optional dependencies for all supported backends. When adding this
library to your application, you can include only the dependencies you actually need; see individual
backend docs and [pyproject.toml](https://github.com/requests-cache/aiohttp-client-cache/blob/main/pyproject.toml)
for details.
## Basic Usage
Next, use [aiohttp_client_cache.CachedSession](https://aiohttp-client-cache.readthedocs.io/en/stable/modules/aiohttp_client_cache.session.html#aiohttp_client_cache.session.CachedSession)
in place of [aiohttp.ClientSession](https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.ClientSession).
To briefly demonstrate how to use it:
**Replace this:**
```python
from aiohttp import ClientSession
async with ClientSession() as session:
await session.get('http://httpbin.org/delay/1')
```
**With this:**
```python
from aiohttp_client_cache import CachedSession, SQLiteBackend
async with CachedSession(cache=SQLiteBackend('demo_cache')) as session:
await session.get('http://httpbin.org/delay/1')
```
The URL in this example adds a delay of 1 second, simulating a slow or rate-limited website.
With caching, the response will be fetched once, saved to `demo_cache.sqlite`, and subsequent
requests will return the cached response near-instantly.
## Configuration
Several options are available to customize caching behavior. This example demonstrates a few of them:
```python
# fmt: off
from aiohttp_client_cache import SQLiteBackend
cache = SQLiteBackend(
cache_name='~/.cache/aiohttp-requests.db', # For SQLite, this will be used as the filename
expire_after=60*60, # By default, cached responses expire in an hour
urls_expire_after={'*.fillmurray.com': -1}, # Requests for any subdomain on this site will never expire
allowed_codes=(200, 418), # Cache responses with these status codes
allowed_methods=['GET', 'POST'], # Cache requests with these HTTP methods
include_headers=True, # Cache requests with different headers separately
ignored_params=['auth_token'], # Keep using the cached response even if this param changes
timeout=2.5, # Connection timeout for SQLite backend
)
```
# More Info
To learn more, see:
- [User Guide](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html)
- [Cache Backends](https://aiohttp-client-cache.readthedocs.io/en/stable/backends.html)
- [API Reference](https://aiohttp-client-cache.readthedocs.io/en/stable/reference.html)
- [Examples](https://aiohttp-client-cache.readthedocs.io/en/stable/examples.html)
# Feedback
If there is a feature you want, if you've discovered a bug, or if you have other general feedback, please
[create an issue](https://github.com/requests-cache/aiohttp-client-cache/issues/new/choose) for it!
Raw data
{
"_id": null,
"home_page": "https://github.com/requests-cache/aiohttp-client-cache",
"name": "aiohttp-client-cache",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "aiohttp, async, asyncio, cache, cache-backends, client, http, persistence, requests, sqlite, redis, mongodb, dynamodb, dragonflydb",
"author": "Jordan Cook",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1e/89/60d829fa323e01006e8c6e76133284ae2ffd692752706e18db162f32df75/aiohttp_client_cache-0.12.3.tar.gz",
"platform": null,
"description": "# aiohttp-client-cache\n\n[![Build status](https://github.com/requests-cache/aiohttp-client-cache/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/requests-cache/aiohttp-client-cache/actions)\n[![Documentation Status](https://img.shields.io/readthedocs/aiohttp-client-cache/latest?label=docs)](https://aiohttp-client-cache.readthedocs.io/en/stable/)\n[![Codecov](https://codecov.io/gh/requests-cache/aiohttp-client-cache/branch/main/graph/badge.svg?token=I6PNLYTILM)](https://codecov.io/gh/requests-cache/aiohttp-client-cache)\n[![PyPI](https://img.shields.io/pypi/v/aiohttp-client-cache?color=blue)](https://pypi.org/project/aiohttp-client-cache)\n[![Conda](https://img.shields.io/conda/vn/conda-forge/aiohttp-client-cache?color=blue)](https://anaconda.org/conda-forge/aiohttp-client-cache)\n[![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/aiohttp-client-cache)](https://pypi.org/project/aiohttp-client-cache)\n[![PyPI - Format](https://img.shields.io/pypi/format/aiohttp-client-cache?color=blue)](https://pypi.org/project/aiohttp-client-cache)\n\n**aiohttp-client-cache** is an async persistent cache for [aiohttp](https://docs.aiohttp.org)\nclient requests, based on [requests-cache](https://github.com/reclosedev/requests-cache).\n\n# Features\n\n- **Ease of use:** Use as a [drop-in replacement](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html)\n for `aiohttp.ClientSession`\n- **Customization:** Works out of the box with little to no config, but with plenty of options\n available for customizing cache\n [expiration](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html#cache-expiration)\n and other [behavior](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html#cache-options)\n- **Persistence:** Includes several [storage backends](https://aiohttp-client-cache.readthedocs.io/en/stable/backends.html):\n SQLite, DynamoDB, MongoDB, DragonflyDB and Redis.\n\n# Quickstart\n\nFirst, install with pip (python 3.8+ required):\n\n```bash\npip install aiohttp-client-cache[all]\n```\n\n**Note:**\nAdding `[all]` will install optional dependencies for all supported backends. When adding this\nlibrary to your application, you can include only the dependencies you actually need; see individual\nbackend docs and [pyproject.toml](https://github.com/requests-cache/aiohttp-client-cache/blob/main/pyproject.toml)\nfor details.\n\n## Basic Usage\n\nNext, use [aiohttp_client_cache.CachedSession](https://aiohttp-client-cache.readthedocs.io/en/stable/modules/aiohttp_client_cache.session.html#aiohttp_client_cache.session.CachedSession)\nin place of [aiohttp.ClientSession](https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.ClientSession).\nTo briefly demonstrate how to use it:\n\n**Replace this:**\n\n```python\nfrom aiohttp import ClientSession\n\nasync with ClientSession() as session:\n await session.get('http://httpbin.org/delay/1')\n```\n\n**With this:**\n\n```python\nfrom aiohttp_client_cache import CachedSession, SQLiteBackend\n\nasync with CachedSession(cache=SQLiteBackend('demo_cache')) as session:\n await session.get('http://httpbin.org/delay/1')\n```\n\nThe URL in this example adds a delay of 1 second, simulating a slow or rate-limited website.\nWith caching, the response will be fetched once, saved to `demo_cache.sqlite`, and subsequent\nrequests will return the cached response near-instantly.\n\n## Configuration\n\nSeveral options are available to customize caching behavior. This example demonstrates a few of them:\n\n```python\n# fmt: off\nfrom aiohttp_client_cache import SQLiteBackend\n\ncache = SQLiteBackend(\n cache_name='~/.cache/aiohttp-requests.db', # For SQLite, this will be used as the filename\n expire_after=60*60, # By default, cached responses expire in an hour\n urls_expire_after={'*.fillmurray.com': -1}, # Requests for any subdomain on this site will never expire\n allowed_codes=(200, 418), # Cache responses with these status codes\n allowed_methods=['GET', 'POST'], # Cache requests with these HTTP methods\n include_headers=True, # Cache requests with different headers separately\n ignored_params=['auth_token'], # Keep using the cached response even if this param changes\n timeout=2.5, # Connection timeout for SQLite backend\n)\n```\n\n# More Info\n\nTo learn more, see:\n\n- [User Guide](https://aiohttp-client-cache.readthedocs.io/en/stable/user_guide.html)\n- [Cache Backends](https://aiohttp-client-cache.readthedocs.io/en/stable/backends.html)\n- [API Reference](https://aiohttp-client-cache.readthedocs.io/en/stable/reference.html)\n- [Examples](https://aiohttp-client-cache.readthedocs.io/en/stable/examples.html)\n\n# Feedback\n\nIf there is a feature you want, if you've discovered a bug, or if you have other general feedback, please\n[create an issue](https://github.com/requests-cache/aiohttp-client-cache/issues/new/choose) for it!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Persistent cache for aiohttp requests",
"version": "0.12.3",
"project_urls": {
"Documentation": "https://aiohttp-client-cache.readthedocs.io",
"Homepage": "https://github.com/requests-cache/aiohttp-client-cache",
"Repository": "https://github.com/requests-cache/aiohttp-client-cache"
},
"split_keywords": [
"aiohttp",
" async",
" asyncio",
" cache",
" cache-backends",
" client",
" http",
" persistence",
" requests",
" sqlite",
" redis",
" mongodb",
" dynamodb",
" dragonflydb"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4da428cd74591e7ba46e36a14e8cc9566c14486f3c5b8a92eff1de728460908",
"md5": "ff85f35e6a430e5bdd4a6b5a33dd2f36",
"sha256": "7bc03d5352714969a180ab7be70c1d02141c22bc759f79f7c8207b7c473c8184"
},
"downloads": -1,
"filename": "aiohttp_client_cache-0.12.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff85f35e6a430e5bdd4a6b5a33dd2f36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 32540,
"upload_time": "2024-10-04T16:04:44",
"upload_time_iso_8601": "2024-10-04T16:04:44.031516Z",
"url": "https://files.pythonhosted.org/packages/f4/da/428cd74591e7ba46e36a14e8cc9566c14486f3c5b8a92eff1de728460908/aiohttp_client_cache-0.12.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1e8960d829fa323e01006e8c6e76133284ae2ffd692752706e18db162f32df75",
"md5": "ef7feecc0e551a24d8ef698525f717e6",
"sha256": "184661458e46773a6b5d5da9e9cd916a11e540c523bff2928dea6d52142b1026"
},
"downloads": -1,
"filename": "aiohttp_client_cache-0.12.3.tar.gz",
"has_sig": false,
"md5_digest": "ef7feecc0e551a24d8ef698525f717e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 62591,
"upload_time": "2024-10-04T16:04:45",
"upload_time_iso_8601": "2024-10-04T16:04:45.359330Z",
"url": "https://files.pythonhosted.org/packages/1e/89/60d829fa323e01006e8c6e76133284ae2ffd692752706e18db162f32df75/aiohttp_client_cache-0.12.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 16:04:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "requests-cache",
"github_project": "aiohttp-client-cache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiohttp-client-cache"
}