..
  SPDX-FileCopyrightText: SPDX-FileCopyrightText: 2015 Eric Larson

  SPDX-License-Identifier: Apache-2.0

.. CacheControl documentation master file, created by
   sphinx-quickstart on Mon Nov  4 15:01:23 2013.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

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 :doc:`storage` for more info.



Quick Start
===========

.. important::

    You **must** read the :doc:`security` page before using CacheControl.

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

.. code-block:: python

  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 :doc:`security` page for more information.

.. _httplib2: https://github.com/httplib2/httplib2
.. _requests: https://requests.readthedocs.io/en/latest/
.. _PyPI: https://pypi.org/project/CacheControl/
.. _pip: https://pip.pypa.io/en/stable/


Contents
========

.. toctree::
   :maxdepth: 2

   usage
   storage
   etags
   custom_heuristics
   tips
   security

.. toctree::
   :hidden:
   :caption: Development
   :maxdepth: 2

   hacking
   release_notes
   GitHub <https://github.com/psf/cachecontrol>
   PyPI <https://pypi.org/project/cachecontrol>


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`