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

Just import requests_cache and call configure()

import requests
import requests_cache

requests_cache.configure()

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, memory), expiration time, etc. E.g. cache stored in sqlite database (default format) named 'test_cache.sqlite' with expiration set to 5 minutes can be configured as:

requests_cache.configure('test_cache', backend='sqlite', expire_after=5)

See also

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

Transparent caching is achieved by monkey-patching requests library (it can be disabled, see monkey_patch argument for configure()) , It is possible to undo this patch, and redo it again with undo_patch() and redo_patch(). But preferable way is to use requests_cache.disabled() and requests_cache.enabled context managers for temporary disabling and enabling caching:

with requests_cache.disabled():
    for i in range(3):
        print(requests.get('http://httpbin.org/ip').text)

with requests_cache.enabled():
    for i in range(10):
        print(requests.get('http://httpbin.org/delay/1').text)

Also, you can check if url is present in cache with requests_cache.has_url() and delete it with requests_cache.delete_url():

>>> import requests
>>> import requests_cache
>>> requests_cache.configure()
>>> requests.get('http://httpbin.org/get')
>>> requests_cache.has_url('http://httpbin.org/get')
True
>>> requests_cache.delete_url('http://httpbin.org/get')
>>> requests_cache.has_url('http://httpbin.org/get')
False

New in version 0.1.4: If Response is taken from cache, it will have from_cache attribute:

>>> import requests
>>> import requests_cache
>>> requests_cache.configure()
>>> requests_cache.clear()
>>> r = requests.get('http://httpbin.org/get')
>>> hasattr(r, 'from_cache')
False
>>> r = requests.get('http://httpbin.org/get')
>>> hasattr(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 hasattr(response, 'from_cache'):
            time.sleep(timeout)
        return response
    return hook

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

    s = requests.Session(hooks={'response': make_throttle_hook(2.0)})
    s.get('http://httpbin.org/get')
    s.get('http://httpbin.org/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 configure().

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)

  Note

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

Also, you can write your own. See Cache backends API documentation and sources.

---

For more information see API reference .