User guide

Installation

Install with pip or easy_install:

pip install --upgrade requests-cache

or download latest version from version control:

git clone git://github.com/reclosedev/requests-cache.git
cd requests-cache
python setup.py install

Usage

There is two ways of using requests_cache:

Monkey-patching allows to add caching to existent program by adding just two lines:

Import requests_cache and call install_cache()

import requests
import requests_cache

requests_cache.install_cache()

And you can use requests, all responses will be cached transparently!

For example, following code will take only 1-2 seconds instead 10:

for i in range(10):
    requests.get('http://httpbin.org/delay/1')

Cache can be configured with some options, such as cache filename, backend (sqlite, mongodb, redis, memory), expiration time, etc. E.g. cache stored in sqlite database (default format) named 'test_cache.sqlite' with expiration set to 300 seconds can be configured as:

requests_cache.install_cache('test_cache', backend='sqlite', expire_after=300)

See also

Full list of options can be found in requests_cache.install_cache() reference

Transparent caching is achieved by monkey-patching requests library It is possible to uninstall this patch with requests_cache.uninstall_cache().

Also, you can use requests_cache.disabled() context manager for temporary disabling caching:

with requests_cache.disabled():
    print(requests.get('http://httpbin.org/ip').text)

If Response is taken from cache, from_cache attribute will be True:

>>> import requests
>>> import requests_cache
>>> requests_cache.install_cache()
>>> requests_cache.clear()
>>> r = requests.get('http://httpbin.org/get')
>>> r.from_cache
False
>>> r = requests.get('http://httpbin.org/get')
>>> r.from_cache
True

It can be used, for example, for request throttling with help of requests hook system:

import time
import requests
import requests_cache

def make_throttle_hook(timeout=1.0):
    """
    Returns a response hook function which sleeps for `timeout` seconds if
    response is not cached
    """
    def hook(response):
        if not getattr(response, 'from_cache', False):
            print 'sleeping'
            time.sleep(timeout)
        return response
    return hook

if __name__ == '__main__':
    requests_cache.install_cache('wait_test')
    requests_cache.clear()

    s = requests_cache.CachedSession()
    s.hooks = {'response': make_throttle_hook(0.1)}
    s.get('http://httpbin.org/delay/get')
    s.get('http://httpbin.org/delay/get')

See also

example.py

Persistence

requests_cache designed to support different backends for persistent storage. By default it uses sqlite database. Type of storage can be selected with backend argument of install_cache().

List of available backends:

  • 'sqlite' - sqlite database (default)

  • 'memory' - not persistent, stores all data in Python dict in memory

  • 'mongodb' - (experimental) MongoDB database (pymongo required)

  • 'redis' - stores all data on a redis data store (redis required)

    Note

    pymongo doesn’t work fine with gevent which powers grequests, but there is some workarounds, see question on StackOverflow.

You can write your own and pass instance to install_cache() or CachedSession constructor. See Cache backends API documentation and sources.

Backward incompatible changes

There is backward incompatible changes introduced in version 0.3.0:

  • expire_after is now seconds
  • UTC time in cache
  • Deleted requests_cache.enabled() context manager
  • Storage backends are now using hash for keys
  • Renamed methods in backends

For more information see API reference .