General Usage

There are two main ways of using requests-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('https://httpbin.org/get')

Any requests.Session method can be used (but see Filter by HTTP Methods section for options):

>>> session.request('GET', 'https://httpbin.org/get')
>>> session.head('https://httpbin.org/get')

Caching can be temporarily disabled for the session with CachedSession.cache_disabled():

>>> with session.cache_disabled():
...     session.get('https://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(). This adds fully transparent caching to all requests functions, without the need to modify any existing code:

>>> import requests
>>> import requests_cache

>>> requests_cache.install_cache()
>>> requests.get('https://httpbin.org/get')

As well as session methods:

>>> session = requests.Session()
>>> session.get('https://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('https://httpbin.org/get')  # Will be cached

Or temporarily disabled():

>>> requests_cache.install_cache()
>>> with requests_cache.disabled():
...     requests.get('https://httpbin.org/get')  # Will not be cached

Or completely removed with uninstall_cache():

>>> requests_cache.uninstall_cache()
>>> requests.get('https://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

There are some scenarios where patching requests with install_cache() is not ideal:

  • 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 these cases, consider using CachedSession instead.

Settings

There are a number of settings that affect cache behavior, which are covered in more detail in the following sections:

These can all be passed as keyword arguments to CachedSession or install_cache(). When using a session object, these can also be safely modified at any time via CachedSession.settings. For example:

>>> from requests_cache import CachedSession

>>> session = CachedSession()
>>> session.settings.expire_after = 360
>>> session.settings.stale_if_error = True

Note that this does not include backend and serializer settings, which cannot be changed after initialization.

The autoclose parameter (default True) controls whether the cache backend connection is closed when the session is closed. Set it to False when sharing a single backend instance across multiple sessions, so that closing one session does not disconnect the others:

>>> backend = RedisCache()
>>> session1 = CachedSession(backend=backend, autoclose=False)
>>> session2 = CachedSession(backend=backend, autoclose=False)