Welcome to CacheControl’s documentation!

CacheControl is a port of the caching algorithms in httplib2 for use with the requests session object.

It was written because httplib2’s better support for caching is often mitigated by its lack of thread-safety. The same is true of requests in terms of caching.

Install

CacheControl is available from PyPI. You can install it with pip

$ pip install CacheControl

Some of the included cache storage classes have external requirements. See Storing Cache Data for more info.

Quick Start

Important

You must read the Security Considerations page before using CacheControl.

For the impatient, here is how to get started using CacheControl:

import requests

from cachecontrol import CacheControl


sess = requests.session()
cached_sess = CacheControl(sess)

response = cached_sess.get('http://google.com')

This uses a thread-safe in-memory dictionary for storage.

Disclaimers

HTTP caching comes with important security considerations. Please read the Security Considerations page for more information.

Contents

• Using CacheControl
  • Wrapper
  • Adapter
  • Use a Different Cache Store
• Storing Cache Data
  • DictCache
  • FileCache
  • SeparateBodyFileCache
  • RedisCache
  • Third-Party Cache Providers
• ETag Support
  • Turning Off Equal Priority Caching
  • Equal Priority Caching Benefits
  • Endpoint Specific Caching
• Custom Caching Strategies
  • Caching Heuristics
  • Best Practices
  • Warning!
• Tips and Best Practices
  • Timezones
  • Cached Responses
  • Query String Params
• Security Considerations
  • CacheControl’s security model
  • Reporting security issues

Indices and tables

• Index

• Module Index

• Search Page