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.