1cachetools
2========================================================================
3
4This module provides various memoizing collections and decorators,
5including variants of the Python 3 Standard Library `@lru_cache`_
6function decorator.
7
8.. code-block:: pycon
9
10   >>> from cachetools import LRUCache
11   >>> cache = LRUCache(maxsize=2)
12   >>> cache.update([('first', 1), ('second', 2)])
13   >>> cache
14   LRUCache([('second', 2), ('first', 1)], maxsize=2, currsize=2)
15   >>> cache['third'] = 3
16   >>> cache
17   LRUCache([('second', 2), ('third', 3)], maxsize=2, currsize=2)
18   >>> cache['second']
19   2
20   >>> cache['fourth'] = 4
21   >>> cache
22   LRUCache([('second', 2), ('fourth', 4)], maxsize=2, currsize=2)
23
24For the purpose of this module, a *cache* is a mutable_ mapping_ of a
25fixed maximum size.  When the cache is full, i.e. by adding another
26item the cache would exceed its maximum size, the cache must choose
27which item(s) to discard based on a suitable `cache algorithm`_.  In
28general, a cache's size is the total size of its items, and an item's
29size is a property or function of its value, e.g. the result of
30``sys.getsizeof(value)``.  For the trivial but common case that each
31item counts as ``1``, a cache's size is equal to the number of its
32items, or ``len(cache)``.
33
34Multiple cache classes based on different caching algorithms are
35implemented, and decorators for easily memoizing function and method
36calls are provided, too.
37
38
39Installation
40------------------------------------------------------------------------
41
42Install cachetools using pip::
43
44    pip install cachetools
45
46
47Project Resources
48------------------------------------------------------------------------
49
50.. image:: http://img.shields.io/pypi/v/cachetools.svg?style=flat
51   :target: https://pypi.python.org/pypi/cachetools/
52   :alt: Latest PyPI version
53
54.. image:: http://img.shields.io/pypi/dm/cachetools.svg?style=flat
55   :target: https://pypi.python.org/pypi/cachetools/
56   :alt: Number of PyPI downloads
57
58.. image:: http://img.shields.io/travis/tkem/cachetools/master.svg?style=flat
59   :target: https://travis-ci.org/tkem/cachetools/
60   :alt: Travis CI build status
61
62.. image:: http://img.shields.io/coveralls/tkem/cachetools/master.svg?style=flat
63   :target: https://coveralls.io/r/tkem/cachetools
64   :alt: Test coverage
65
66- `Documentation`_
67- `Issue Tracker`_
68- `Source Code`_
69- `Change Log`_
70
71
72License
73------------------------------------------------------------------------
74
75Copyright (c) 2014-2016 Thomas Kemmer.
76
77Licensed under the `MIT License`_.
78
79
80.. _@lru_cache: http://docs.python.org/3/library/functools.html#functools.lru_cache
81.. _mutable: http://docs.python.org/dev/glossary.html#term-mutable
82.. _mapping: http://docs.python.org/dev/glossary.html#term-mapping
83.. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms
84
85.. _Documentation: http://pythonhosted.org/cachetools/
86.. _Issue Tracker: https://github.com/tkem/cachetools/issues/
87.. _Source Code: https://github.com/tkem/cachetools/
88.. _Change Log: https://github.com/tkem/cachetools/blob/master/CHANGES.rst
89.. _MIT License: http://raw.github.com/tkem/cachetools/master/LICENSE
90
91
92