General Usage#
There are two main ways of using requests-cache:
Sessions: (recommended) Use
CachedSession
to send your requestsPatching: Globally patch
requests
usinginstall_cache()
Sessions#
CachedSession
can be used as a drop-in replacement for requests.Session
.
Basic usage looks like this:
>>> from requests_cache import CachedSession
>>>
>>> session = CachedSession()
>>> session.get('http://httpbin.org/get')
Any requests.Session
method can be used (but see Cached HTTP Methods section for
options):
>>> session.request('GET', 'http://httpbin.org/get')
>>> session.head('http://httpbin.org/get')
Caching can be temporarily disabled for the session with
CachedSession.cache_disabled()
:
>>> with session.cache_disabled():
... session.get('http://httpbin.org/get')
The best way to clean up your cache is through Expiration settings, but you can also
clear out everything at once with BaseCache.clear()
:
>>> session.cache.clear()
Patching#
In some situations, it may not be possible or convenient to manage your own session object. In those
cases, you can use install_cache()
to add caching to all requests
functions:
>>> import requests
>>> import requests_cache
>>>
>>> requests_cache.install_cache()
>>> requests.get('http://httpbin.org/get')
As well as session methods:
>>> session = requests.Session()
>>> session.get('http://httpbin.org/get')
install_cache()
accepts all the same parameters as CachedSession
:
>>> requests_cache.install_cache(expire_after=360, allowable_methods=('GET', 'POST'))
It can be temporarily enabled()
:
>>> with requests_cache.enabled():
... requests.get('http://httpbin.org/get') # Will be cached
Or temporarily disabled()
:
>>> requests_cache.install_cache()
>>> with requests_cache.disabled():
... requests.get('http://httpbin.org/get') # Will not be cached
Or completely removed with uninstall_cache()
:
>>> requests_cache.uninstall_cache()
>>> requests.get('http://httpbin.org/get')
You can also clear out all responses in the cache with clear()
, and check if
requests-cache is currently installed with is_installed()
.
Patching Limitations & Potential Issues#
Like any other utility that uses monkey-patching, there are some scenarios where you won’t want to
use install_cache()
:
When using other libraries that patch
requests.Session
In a multi-threaded or multiprocess application
In a library that will be imported by other libraries or applications
In a larger application that makes requests in several different modules, where it may not be obvious what is and isn’t being cached
In any of these cases, consider using CachedSession
, the enabled()
contextmanager, or Cached URLs.