API Reference

This section covers all the public interfaces of requests-cache.

Sessions

class requests_cache.session.CachedSession(cache_name='http_cache', backend=None, expire_after=- 1, urls_expire_after=None, allowable_codes=(200,), allowable_methods=('GET', 'HEAD'), filter_fn=None, old_data_on_error=False, cache_control=False, **kwargs)

Bases: requests_cache.session.CacheMixin, requests.sessions.Session

Class that extends requests.Session with caching features.

See individual backend classes for additional backend-specific arguments. Also see User Guide for more details and examples on how the following arguments affect cache behavior.

Parameters

• cache_name (str) – Cache prefix or namespace, depending on backend

• backend (Union[str, BaseCache, Type[BaseCache], None]) – Cache backend name, class, or instance; name may be one of ['sqlite', 'mongodb', 'gridfs', 'redis', 'dynamodb', 'memory'].

• expire_after (Union[None, int, float, str, datetime, timedelta]) – Time after which cached items will expire

• urls_expire_after (Optional[Dict[str, Union[None, int, float, str, datetime, timedelta]]]) – Expiration times to apply for different URL patterns

• allowable_codes (Iterable[int]) – Only cache responses with one of these codes

• allowable_methods (Iterable[str]) – Cache only responses for one of these HTTP methods

• include_get_headers – Make request headers part of the cache key

• ignored_parameters – List of request parameters to be excluded from the cache key

• filter_fn (Optional[Callable]) – function that takes a aiohttp.ClientResponse object and returns a boolean indicating whether or not that response should be cached. Will be applied to both new and previously cached responses.

• old_data_on_error (bool) – Return stale cache data if a new request raises an exception

• cache_control (bool) – Use Cache-Control request and response headers

cache_disabled()

Context manager for temporary disabling the cache

Warning

This method is not thread-safe.

Example

>>> s = CachedSession()
>>> with s.cache_disabled():
...     s.get('http://httpbin.org/ip')

remove_expired_responses(expire_after=None)

Remove expired responses from the cache, optionally with revalidation

Parameters

expire_after (Union[None, int, float, str, datetime, timedelta]) – A new expiration time used to revalidate the cache

request(method, url, params=None, data=None, json=None, expire_after=None, **kwargs)

This method prepares and sends a request while automatically performing any necessary caching operations. This will be called by any other method-specific requests functions (get, post, etc.). This does not include prepared requests, which will still be cached via send().

See requests.Session.request() for parameters. Additional parameters:

Parameters

expire_after (Union[None, int, float, str, datetime, timedelta]) – Expiration time to set only for this request; see details below. Overrides CachedSession.expire_after. Accepts all the same values as CachedSession.expire_after except for None; use -1 to disable expiration on a per-request basis.

Return type

Union[Response, CachedResponse]

Returns

Either a new or cached response

Order of operations: For reference, a request will pass through the following methods:

1. requests.get()/requests.Session.get() or other method-specific functions (optional)

2. CachedSession.request()

3. requests.Session.request()

4. CachedSession.send()

5. BaseCache.get_response()

6. requests.Session.send() (if not previously cached)

7. BaseCache.save_response() (if not previously cached)

send(request, **kwargs)

Send a prepared request, with caching. See request() for notes on behavior.

Return type

Union[Response, CachedResponse]

class requests_cache.session.CacheMixin(cache_name='http_cache', backend=None, expire_after=- 1, urls_expire_after=None, allowable_codes=(200,), allowable_methods=('GET', 'HEAD'), filter_fn=None, old_data_on_error=False, cache_control=False, **kwargs)

Mixin class that extends requests.Session with caching features. See CachedSession for usage information.

Patching

Utilities for patching requests.

Warning

These functions are not thread-safe. Use CachedSession directly if you want to use caching in a multi-threaded environment.

requests_cache.patcher.clear()

Clear the currently installed cache (if any)

requests_cache.patcher.disabled()

Context manager for temporarily disabling caching for all requests functions

Example

>>> with requests_cache.disabled():
...     requests.get('http://httpbin.org/get')

requests_cache.patcher.enabled(*args, **kwargs)

Context manager for temporarily enabling caching for all requests functions

Accepts the same arguments as install_cache().

Example

>>> with requests_cache.enabled('cache_db'):
...     requests.get('http://httpbin.org/get')

requests_cache.patcher.get_cache()

Get the internal cache object from the currently installed CachedSession (if any)

Return type

Optional[BaseCache]

requests_cache.patcher.install_cache(cache_name='http_cache', backend=None, expire_after=-1, urls_expire_after=None, allowable_codes=(200, ), allowable_methods=('GET', 'HEAD'), filter_fn=None, old_data_on_error=False, session_factory=<class 'requests_cache.session.CachedSession'>, **kwargs)

Install the cache for all requests functions by monkey-patching requests.Session

Example

>>> requests_cache.install_cache('demo_cache')

Accepts all the same parameters as CachedSession. Additional parameters:

Parameters

session_factory (Type[Session]) – Session class to use. It must inherit from either CachedSession or CacheMixin

requests_cache.patcher.is_installed()

Indicate whether or not requests-cache is currently installed

Return type

bool

requests_cache.patcher.remove_expired_responses(expire_after=None)

Remove expired responses from the cache, optionally with revalidation

Parameters

expire_after (Union[None, int, float, str, datetime, timedelta]) – A new expiration time used to revalidate the cache

requests_cache.patcher.uninstall_cache()

Disable the cache by restoring the original requests.Session

Cache Backends

• requests_cache.backends package
  • Submodules
  • requests_cache.backends.base module
  • requests_cache.backends.dynamodb module
  • requests_cache.backends.filesystem module
  • requests_cache.backends.gridfs module
  • requests_cache.backends.mongo module
  • requests_cache.backends.redis module
  • requests_cache.backends.sqlite module

Models

• requests_cache.models package
  • Submodules
  • requests_cache.models.raw_response module
  • requests_cache.models.request module
  • requests_cache.models.response module

Serializers

• requests_cache.serializers package
  • Submodules
  • requests_cache.serializers.cattrs module
  • requests_cache.serializers.pipeline module
  • requests_cache.serializers.preconf module

Utilities

• Utility Modules
  • Cache Keys
  • Cache-Control