[](https://requests-cache.readthedocs.io)
[](https://github.com/requests-cache/requests-cache/actions)
[](https://codecov.io/gh/requests-cache/requests-cache)
[](https://requests-cache.readthedocs.io/en/stable/)
[](https://www.codeshelter.co/)
[](https://pypi.org/project/requests-cache)
[](https://anaconda.org/conda-forge/requests-cache)
[](https://pypi.org/project/requests-cache)
[](https://pypi.org/project/requests-cache)
## Summary
**requests-cache** is a persistent HTTP cache that provides an easy way to get better
performance with the python [requests](https://requests.readthedocs.io/) library.
<!-- RTD-IGNORE -->
Complete project documentation can be found at [requests-cache.readthedocs.io](https://requests-cache.readthedocs.io).
<!-- END-RTD-IGNORE -->
## Features
* 🍰 **Ease of use:** Keep using the `requests` library you're already familiar with. Add caching
with a [drop-in replacement](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#sessions)
for `requests.Session`, or
[install globally](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#patching)
to add transparent caching to all `requests` functions.
* 🚀 **Performance:** Get sub-millisecond response times for cached responses. When they expire, you
still save time with
[conditional requests](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#conditional-requests).
* 💾 **Persistence:** Works with several
[storage backends](https://requests-cache.readthedocs.io/en/stable/user_guide/backends.html)
including SQLite, Redis, MongoDB, and DynamoDB; or save responses as plain JSON files, YAML,
and more
* 🕗 **Expiration:** Use
[Cache-Control](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#cache-control)
and other standard HTTP headers, define your own expiration schedule, keep your cache clutter-free
with backends that natively support TTL, or any combination of strategies
* ⚙️ **Customization:** Works out of the box with zero config, but with a robust set of features for
configuring and extending the library to suit your needs
* 🧩 **Compatibility:** Can be combined with other
[popular libraries based on requests](https://requests-cache.readthedocs.io/en/stable/user_guide/compatibility.html)
## Quickstart
First, install with pip:
```bash
pip install requests-cache
```
Then, use [requests_cache.CachedSession](https://requests-cache.readthedocs.io/en/stable/modules/requests_cache.session.html)
to make your requests. It behaves like a normal
[requests.Session](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects),
but with caching behavior.
To illustrate, we'll call an endpoint that adds a delay of 1 second, simulating a slow or
rate-limited website.
**This takes 1 minute:**
```python
import requests
session = requests.Session()
for i in range(60):
session.get('https://httpbin.org/delay/1')
```
**This takes 1 second:**
```python
import requests_cache
session = requests_cache.CachedSession('demo_cache')
for i in range(60):
session.get('https://httpbin.org/delay/1')
```
With caching, the response will be fetched once, saved to `demo_cache.sqlite`, and subsequent
requests will return the cached response near-instantly.
### Patching
If you don't want to manage a session object, or just want to quickly test it out in your
application without modifying any code, requests-cache can also be installed globally, and all
requests will be transparently cached:
```python
import requests
import requests_cache
requests_cache.install_cache('demo_cache')
requests.get('https://httpbin.org/delay/1')
```
### Headers and Expiration
By default, requests-cache will keep cached responses indefinitely. In most cases, you will want to
use one of the two following strategies to balance cache freshness and performance:
**Define exactly how long to keep responses:**
Use the `expire_after` parameter to set a fixed expiration time for all new responses:
```python
from requests_cache import CachedSession
from datetime import timedelta
# Keep responses for 360 seconds
session = CachedSession('demo_cache', expire_after=360)
# Or use timedelta objects to specify other units of time
session = CachedSession('demo_cache', expire_after=timedelta(hours=1))
```
See [Expiration](https://requests-cache.readthedocs.io/en/stable/user_guide/expiration.html) for
more features and settings.
**Use Cache-Control headers:**
Use the `cache_control` parameter to enable automatic expiration based on `Cache-Control` and other
standard HTTP headers sent by the server:
```python
from requests_cache import CachedSession
session = CachedSession('demo_cache', cache_control=True)
```
See [Cache Headers](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html)
for more details.
### Settings
The default settings work well for most use cases, but there are plenty of ways to customize
caching behavior when needed. Here is a quick example of some of the options available:
```python
from datetime import timedelta
from requests_cache import CachedSession
session = CachedSession(
'demo_cache',
use_cache_dir=True, # Save files in the default user cache dir
cache_control=True, # Use Cache-Control response headers for expiration, if available
expire_after=timedelta(days=1), # Otherwise expire responses after one day
allowable_codes=[200, 400], # Cache 400 responses as a solemn reminder of your failures
allowable_methods=['GET', 'POST'], # Cache whatever HTTP methods you want
ignored_parameters=['api_key'], # Don't match this request param, and redact if from the cache
match_headers=['Accept-Language'], # Cache a different response per language
stale_if_error=True, # In case of request errors, use stale cache data if possible
)
```
<!-- RTD-IGNORE -->
## Next Steps
To find out more about what you can do with requests-cache, see:
* [User Guide](https://requests-cache.readthedocs.io/en/stable/user_guide.html)
* [Examples](https://requests-cache.readthedocs.io/en/stable/examples.html)
* [API Reference](https://requests-cache.readthedocs.io/en/stable/reference.html)
* [Project Info](https://requests-cache.readthedocs.io/en/stable/project_info.html)
<!-- END-RTD-IGNORE -->
Raw data
{
"_id": null,
"home_page": "https://github.com/requests-cache/requests-cache",
"name": "requests-cache",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "requests,python-requests,cache,http,http-client,web,webscraping,performance,sqlite,redis,mongodb,gridfs,dynamodb",
"author": "Roman Haritonov",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/0c/f6/2a1078b61b5b21718b61500b08e84ecd525d94a162db782c1065f9f571c7/requests_cache-1.2.0.tar.gz",
"platform": null,
"description": "[](https://requests-cache.readthedocs.io)\n\n[](https://github.com/requests-cache/requests-cache/actions)\n[](https://codecov.io/gh/requests-cache/requests-cache)\n[](https://requests-cache.readthedocs.io/en/stable/)\n[](https://www.codeshelter.co/)\n\n[](https://pypi.org/project/requests-cache)\n[](https://anaconda.org/conda-forge/requests-cache)\n[](https://pypi.org/project/requests-cache)\n[](https://pypi.org/project/requests-cache)\n\n## Summary\n**requests-cache** is a persistent HTTP cache that provides an easy way to get better\nperformance with the python [requests](https://requests.readthedocs.io/) library.\n\n<!-- RTD-IGNORE -->\nComplete project documentation can be found at [requests-cache.readthedocs.io](https://requests-cache.readthedocs.io).\n<!-- END-RTD-IGNORE -->\n\n## Features\n* \ud83c\udf70 **Ease of use:** Keep using the `requests` library you're already familiar with. Add caching\n with a [drop-in replacement](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#sessions)\n for `requests.Session`, or\n [install globally](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#patching)\n to add transparent caching to all `requests` functions.\n* \ud83d\ude80 **Performance:** Get sub-millisecond response times for cached responses. When they expire, you\n still save time with\n [conditional requests](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#conditional-requests).\n* \ud83d\udcbe **Persistence:** Works with several\n [storage backends](https://requests-cache.readthedocs.io/en/stable/user_guide/backends.html)\n including SQLite, Redis, MongoDB, and DynamoDB; or save responses as plain JSON files, YAML,\n and more\n* \ud83d\udd57 **Expiration:** Use\n [Cache-Control](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#cache-control)\n and other standard HTTP headers, define your own expiration schedule, keep your cache clutter-free\n with backends that natively support TTL, or any combination of strategies\n* \u2699\ufe0f **Customization:** Works out of the box with zero config, but with a robust set of features for\n configuring and extending the library to suit your needs\n* \ud83e\udde9 **Compatibility:** Can be combined with other\n [popular libraries based on requests](https://requests-cache.readthedocs.io/en/stable/user_guide/compatibility.html)\n\n## Quickstart\nFirst, install with pip:\n```bash\npip install requests-cache\n```\n\nThen, use [requests_cache.CachedSession](https://requests-cache.readthedocs.io/en/stable/modules/requests_cache.session.html)\nto make your requests. It behaves like a normal\n[requests.Session](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects),\nbut with caching behavior.\n\nTo illustrate, we'll call an endpoint that adds a delay of 1 second, simulating a slow or\nrate-limited website.\n\n**This takes 1 minute:**\n```python\nimport requests\n\nsession = requests.Session()\nfor i in range(60):\n session.get('https://httpbin.org/delay/1')\n```\n\n**This takes 1 second:**\n```python\nimport requests_cache\n\nsession = requests_cache.CachedSession('demo_cache')\nfor i in range(60):\n session.get('https://httpbin.org/delay/1')\n```\n\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### Patching\nIf you don't want to manage a session object, or just want to quickly test it out in your\napplication without modifying any code, requests-cache can also be installed globally, and all\nrequests will be transparently cached:\n```python\nimport requests\nimport requests_cache\n\nrequests_cache.install_cache('demo_cache')\nrequests.get('https://httpbin.org/delay/1')\n```\n\n### Headers and Expiration\nBy default, requests-cache will keep cached responses indefinitely. In most cases, you will want to\nuse one of the two following strategies to balance cache freshness and performance:\n\n**Define exactly how long to keep responses:**\n\nUse the `expire_after` parameter to set a fixed expiration time for all new responses:\n```python\nfrom requests_cache import CachedSession\nfrom datetime import timedelta\n\n# Keep responses for 360 seconds\nsession = CachedSession('demo_cache', expire_after=360)\n\n# Or use timedelta objects to specify other units of time\nsession = CachedSession('demo_cache', expire_after=timedelta(hours=1))\n```\nSee [Expiration](https://requests-cache.readthedocs.io/en/stable/user_guide/expiration.html) for\nmore features and settings.\n\n**Use Cache-Control headers:**\n\nUse the `cache_control` parameter to enable automatic expiration based on `Cache-Control` and other\nstandard HTTP headers sent by the server:\n```python\nfrom requests_cache import CachedSession\n\nsession = CachedSession('demo_cache', cache_control=True)\n```\nSee [Cache Headers](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html)\nfor more details.\n\n\n### Settings\nThe default settings work well for most use cases, but there are plenty of ways to customize\ncaching behavior when needed. Here is a quick example of some of the options available:\n```python\nfrom datetime import timedelta\nfrom requests_cache import CachedSession\n\nsession = CachedSession(\n 'demo_cache',\n use_cache_dir=True, # Save files in the default user cache dir\n cache_control=True, # Use Cache-Control response headers for expiration, if available\n expire_after=timedelta(days=1), # Otherwise expire responses after one day\n allowable_codes=[200, 400], # Cache 400 responses as a solemn reminder of your failures\n allowable_methods=['GET', 'POST'], # Cache whatever HTTP methods you want\n ignored_parameters=['api_key'], # Don't match this request param, and redact if from the cache\n match_headers=['Accept-Language'], # Cache a different response per language\n stale_if_error=True, # In case of request errors, use stale cache data if possible\n)\n```\n\n<!-- RTD-IGNORE -->\n## Next Steps\nTo find out more about what you can do with requests-cache, see:\n\n* [User Guide](https://requests-cache.readthedocs.io/en/stable/user_guide.html)\n* [Examples](https://requests-cache.readthedocs.io/en/stable/examples.html)\n* [API Reference](https://requests-cache.readthedocs.io/en/stable/reference.html)\n* [Project Info](https://requests-cache.readthedocs.io/en/stable/project_info.html)\n<!-- END-RTD-IGNORE -->\n\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "A persistent cache for python requests",
"version": "1.2.0",
"project_urls": {
"Changelog": "https://requests-cache.readthedocs.io/en/stable/project_info/history.html",
"Documentation": "https://requests-cache.readthedocs.io",
"Homepage": "https://github.com/requests-cache/requests-cache",
"Issues": "https://github.com/requests-cache/requests-cache/issues",
"Repository": "https://github.com/requests-cache/requests-cache"
},
"split_keywords": [
"requests",
"python-requests",
"cache",
"http",
"http-client",
"web",
"webscraping",
"performance",
"sqlite",
"redis",
"mongodb",
"gridfs",
"dynamodb"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cc23863f517b5d74e297e669c88093ecd92e13a06c488e90acbd5507819049ac",
"md5": "0e90cd49b10298501f0389a8c9e94459",
"sha256": "490324301bf0cb924ff4e6324bd2613453e7e1f847353928b08adb0fdfb7f722"
},
"downloads": -1,
"filename": "requests_cache-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e90cd49b10298501f0389a8c9e94459",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 61409,
"upload_time": "2024-02-17T23:28:03",
"upload_time_iso_8601": "2024-02-17T23:28:03.432821Z",
"url": "https://files.pythonhosted.org/packages/cc/23/863f517b5d74e297e669c88093ecd92e13a06c488e90acbd5507819049ac/requests_cache-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0cf62a1078b61b5b21718b61500b08e84ecd525d94a162db782c1065f9f571c7",
"md5": "6ddc0516be3e76bab56589fe946501df",
"sha256": "db1c709ca343cc1cd5b6c8b1a5387298eceed02306a6040760db538c885e3838"
},
"downloads": -1,
"filename": "requests_cache-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "6ddc0516be3e76bab56589fe946501df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3018038,
"upload_time": "2024-02-17T23:28:05",
"upload_time_iso_8601": "2024-02-17T23:28:05.852492Z",
"url": "https://files.pythonhosted.org/packages/0c/f6/2a1078b61b5b21718b61500b08e84ecd525d94a162db782c1065f9f571c7/requests_cache-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-17 23:28:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "requests-cache",
"github_project": "requests-cache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "requests-cache"
}
JSON
