A transparent persistent cache for the requests library
Project description
Summary
requests-cache is a transparent, persistent cache that provides an easy way to get better performance with the python requests library.
Complete project documentation can be found at requests-cache.readthedocs.io.
Features
- 🍰 Ease of use: Keep using the
requestslibrary you're already familiar with. Add caching with a drop-in replacement forrequests.Session, or install globally to add caching to allrequestsfunctions. - 🚀 Performance: Get sub-millisecond response times for cached responses. When they expire, you still save time with conditional requests.
- 💾 Persistence: Works with several storage backends including SQLite, Redis, MongoDB, and DynamoDB; or save responses as plain JSON files, YAML, and more
- ⚙️ 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
- 🕗 Expiration: Keep your cache fresh using Cache-Control, eagerly cache everything for long-term storage, use URL patterns for selective caching, or any combination of strategies
- ✔️ Compatibility: Can be combined with other popular libraries based on requests
Quickstart
First, install with pip:
pip install requests-cache
Then, use requests_cache.CachedSession to make your requests. It behaves like a normal requests.Session, 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:
import requests
session = requests.Session()
for i in range(60):
session.get('http://httpbin.org/delay/1')
This takes 1 second:
import requests_cache
session = requests_cache.CachedSession('demo_cache')
for i in range(60):
session.get('http://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:
import requests
import requests_cache
requests_cache.install_cache('demo_cache')
requests.get('http://httpbin.org/delay/1')
Configuration:
A quick example of some of the options available:
# fmt: off
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 headers for expiration, if available
expire_after=timedelta(days=1), # Otherwise expire responses after one day
allowable_methods=['GET', 'POST'], # Cache POST requests to avoid sending the same data twice
allowable_codes=[200, 400], # Cache 400 responses as a solemn reminder of your failures
ignored_parameters=['api_key'], # Don't match this param or save it in the cache
match_headers=True, # Match all request headers
stale_if_error=True, # In case of request errors, use stale cache data if possible
)
Next Steps
To find out more about what you can do with requests-cache, see:
- User Guide
- API Reference
- Project Info
- A working example at Real Python: Caching External API Requests
- More examples in the examples/ folder
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file requests-cache-0.9.0.tar.gz.
File metadata
- Download URL: requests-cache-0.9.0.tar.gz
- Upload date:
- Size: 1.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.2.0a2 CPython/3.9.9 Linux/5.4.0-1064-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d82b3af855ffc16807a401cfe5a924957a083512b430e635045cee767b99d169 |
|
| MD5 | c8048f6e0f1c1333d1a827a0e53c792f |
|
| BLAKE2b-256 | e075305370da92c885dda1f90b5821929d8c15bd7fabe317ae4d3e278850fab2 |
File details
Details for the file requests_cache-0.9.0-py3-none-any.whl.
File metadata
- Download URL: requests_cache-0.9.0-py3-none-any.whl
- Upload date:
- Size: 46.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.2.0a2 CPython/3.9.9 Linux/5.4.0-1064-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | dbcb543e2ffbd365f0e88d9d63081c305673a1e10b8b9679dd990bb2c57864d9 |
|
| MD5 | 982c5d3309a10e361c9609a68f2e9550 |
|
| BLAKE2b-256 | 251f785833faa0aeced7c4aa466967e7ce76cbab578c634eb8c924844b9b7961 |
