| single |
[![]](https://requests-cache.readthedocs.io)
[Build]
[Codecov]
[Documentation]
[Code Shelter]
[PyPI]
[Conda]
[![PyPI - Python Versions]](https://pypi.org/project/requests-cache)
[![PyPI - Downloads]](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] library.
Complete project documentation can be found at
[requests-cache.readthedocs.io].
## Features
* 🍰 **Ease of use:** Keep using the `requests` library you're already
familiar with. Add caching
with a [drop-in replacement]
for `requests.Session`, or
[install globally]
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].
* 💾 **Persistence:** Works with several
[storage backends]
including SQLite, Redis, MongoDB, and DynamoDB; or save responses as
plain JSON files, YAML,
and more
* 🕗 **Expiration:** Use
[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]
## Quickstart
First, install with pip:
```bash
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:**
```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')
```
|