README.rst
1cachetools
2========================================================================
3
4.. image:: https://img.shields.io/pypi/v/cachetools
5 :target: https://pypi.org/project/cachetools/
6 :alt: Latest PyPI version
7
8.. image:: https://img.shields.io/readthedocs/cachetools
9 :target: https://cachetools.readthedocs.io/
10 :alt: Documentation build status
11
12.. image:: https://img.shields.io/github/workflow/status/tkem/cachetools/CI
13 :target: https://github.com/tkem/cachetools/actions/workflows/ci.yml
14 :alt: CI build status
15
16.. image:: https://img.shields.io/codecov/c/github/tkem/cachetools/master.svg
17 :target: https://codecov.io/gh/tkem/cachetools
18 :alt: Test coverage
19
20.. image:: https://img.shields.io/github/license/tkem/cachetools
21 :target: https://raw.github.com/tkem/cachetools/master/LICENSE
22 :alt: License
23
24.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
25 :target: https://github.com/psf/black
26 :alt: Code style: black
27
28This module provides various memoizing collections and decorators,
29including variants of the Python Standard Library's `@lru_cache`_
30function decorator.
31
32.. code-block:: python
33
34 from cachetools import cached, LRUCache, TTLCache
35
36 # speed up calculating Fibonacci numbers with dynamic programming
37 @cached(cache={})
38 def fib(n):
39 return n if n < 2 else fib(n - 1) + fib(n - 2)
40
41 # cache least recently used Python Enhancement Proposals
42 @cached(cache=LRUCache(maxsize=32))
43 def get_pep(num):
44 url = 'http://www.python.org/dev/peps/pep-%04d/' % num
45 with urllib.request.urlopen(url) as s:
46 return s.read()
47
48 # cache weather data for no longer than ten minutes
49 @cached(cache=TTLCache(maxsize=1024, ttl=600))
50 def get_weather(place):
51 return owm.weather_at_place(place).get_weather()
52
53For the purpose of this module, a *cache* is a mutable_ mapping_ of a
54fixed maximum size. When the cache is full, i.e. by adding another
55item the cache would exceed its maximum size, the cache must choose
56which item(s) to discard based on a suitable `cache algorithm`_. In
57general, a cache's size is the total size of its items, and an item's
58size is a property or function of its value, e.g. the result of
59``sys.getsizeof(value)``. For the trivial but common case that each
60item counts as ``1``, a cache's size is equal to the number of its
61items, or ``len(cache)``.
62
63Multiple cache classes based on different caching algorithms are
64implemented, and decorators for easily memoizing function and method
65calls are provided, too.
66
67
68Installation
69------------------------------------------------------------------------
70
71cachetools is available from PyPI_ and can be installed by running::
72
73 pip install cachetools
74
75Typing stubs for this package are provided by typeshed_ and can be
76installed by running::
77
78 pip install types-cachetools
79
80
81Project Resources
82------------------------------------------------------------------------
83
84- `Documentation`_
85- `Issue tracker`_
86- `Source code`_
87- `Change log`_
88
89
90License
91------------------------------------------------------------------------
92
93Copyright (c) 2014-2021 Thomas Kemmer.
94
95Licensed under the `MIT License`_.
96
97
98.. _@lru_cache: https://docs.python.org/3/library/functools.html#functools.lru_cache
99.. _mutable: https://docs.python.org/dev/glossary.html#term-mutable
100.. _mapping: https://docs.python.org/dev/glossary.html#term-mapping
101.. _cache algorithm: https://en.wikipedia.org/wiki/Cache_algorithms
102
103.. _PyPI: https://pypi.org/project/cachetools/
104.. _typeshed: https://github.com/python/typeshed/
105.. _Documentation: https://cachetools.readthedocs.io/
106.. _Issue tracker: https://github.com/tkem/cachetools/issues/
107.. _Source code: https://github.com/tkem/cachetools/
108.. _Change log: https://github.com/tkem/cachetools/blob/master/CHANGELOG.rst
109.. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
110
