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:: python
9
10   from cachetools import cached, LRUCache, TTLCache
11
12   # speed up calculating Fibonacci numbers with dynamic programming
13   @cached(cache={})
14   def fib(n):
15       return n if n < 2 else fib(n - 1) + fib(n - 2)
16
17   # cache least recently used Python Enhancement Proposals
18   @cached(cache=LRUCache(maxsize=32))
19   def get_pep(num):
20       url = 'http://www.python.org/dev/peps/pep-%04d/' % num
21       with urllib.request.urlopen(url) as s:
22           return s.read()
23
24   # cache weather data for no longer than ten minutes
25   @cached(cache=TTLCache(maxsize=1024, ttl=600))
26   def get_weather(place):
27       return owm.weather_at_place(place).get_weather()
28
29For the purpose of this module, a *cache* is a mutable_ mapping_ of a
30fixed maximum size.  When the cache is full, i.e. by adding another
31item the cache would exceed its maximum size, the cache must choose
32which item(s) to discard based on a suitable `cache algorithm`_.  In
33general, a cache's size is the total size of its items, and an item's
34size is a property or function of its value, e.g. the result of
35``sys.getsizeof(value)``.  For the trivial but common case that each
36item counts as ``1``, a cache's size is equal to the number of its
37items, or ``len(cache)``.
38
39Multiple cache classes based on different caching algorithms are
40implemented, and decorators for easily memoizing function and method
41calls are provided, too.
42
43For more information, please refer to the online documentation_.
44
45
46Installation
47------------------------------------------------------------------------
48
49Install cachetools using pip::
50
51    pip install cachetools
52
53
54Project Resources
55------------------------------------------------------------------------
56
57.. image:: http://img.shields.io/pypi/v/cachetools.svg?style=flat
58   :target: https://pypi.python.org/pypi/cachetools/
59   :alt: Latest PyPI version
60
61.. image:: http://img.shields.io/travis/tkem/cachetools/master.svg?style=flat
62   :target: https://travis-ci.org/tkem/cachetools/
63   :alt: Travis CI build status
64
65.. image:: http://img.shields.io/coveralls/tkem/cachetools/master.svg?style=flat
66   :target: https://coveralls.io/r/tkem/cachetools
67   :alt: Test coverage
68
69.. image:: https://readthedocs.org/projects/cachetools/badge/?version=latest&style=flat
70   :target: http://cachetools.readthedocs.io/en/latest/
71   :alt: Documentation Status
72
73- `Issue Tracker`_
74- `Source Code`_
75- `Change Log`_
76
77
78License
79------------------------------------------------------------------------
80
81Copyright (c) 2014-2019 Thomas Kemmer.
82
83Licensed under the `MIT License`_.
84
85
86.. _@lru_cache: http://docs.python.org/3/library/functools.html#functools.lru_cache
87.. _mutable: http://docs.python.org/dev/glossary.html#term-mutable
88.. _mapping: http://docs.python.org/dev/glossary.html#term-mapping
89.. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms
90
91.. _Documentation: http://cachetools.readthedocs.io/en/latest/
92.. _Issue Tracker: https://github.com/tkem/cachetools/issues/
93.. _Source Code: https://github.com/tkem/cachetools/
94.. _Change Log: https://github.com/tkem/cachetools/blob/master/CHANGES.rst
95.. _MIT License: http://raw.github.com/tkem/cachetools/master/LICENSE
96