Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 1 | cachetools |
| 2 | ======================================================================== |
| 3 | |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 4 | This module provides various memoizing collections and decorators, |
Thomas Kemmer | b6bc350 | 2015-08-28 16:30:38 +0200 | [diff] [blame] | 5 | including variants of the Python 3 Standard Library `@lru_cache`_ |
Thomas Kemmer | 5385445 | 2014-11-12 07:58:59 +0100 | [diff] [blame] | 6 | function decorator. |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 7 | |
Thomas Kemmer | eac1c25 | 2018-11-04 16:11:55 +0100 | [diff] [blame^] | 8 | .. code-block:: python |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 9 | |
Thomas Kemmer | eac1c25 | 2018-11-04 16:11:55 +0100 | [diff] [blame^] | 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() |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 28 | |
Thomas Kemmer | b210c14 | 2014-06-16 20:22:12 +0200 | [diff] [blame] | 29 | For the purpose of this module, a *cache* is a mutable_ mapping_ of a |
Thomas Kemmer | 886f48e | 2014-12-19 18:30:57 +0100 | [diff] [blame] | 30 | fixed maximum size. When the cache is full, i.e. by adding another |
| 31 | item the cache would exceed its maximum size, the cache must choose |
| 32 | which item(s) to discard based on a suitable `cache algorithm`_. In |
| 33 | general, a cache's size is the total size of its items, and an item's |
| 34 | size 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 |
Thomas Kemmer | b6bc350 | 2015-08-28 16:30:38 +0200 | [diff] [blame] | 36 | item counts as ``1``, a cache's size is equal to the number of its |
| 37 | items, or ``len(cache)``. |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 38 | |
Thomas Kemmer | 5c7effc | 2015-09-07 20:21:56 +0200 | [diff] [blame] | 39 | Multiple cache classes based on different caching algorithms are |
| 40 | implemented, and decorators for easily memoizing function and method |
| 41 | calls are provided, too. |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 42 | |
Thomas Kemmer | 13ba795 | 2017-08-11 18:35:58 +0200 | [diff] [blame] | 43 | For more information, please refer to the online documentation_. |
Thomas Kemmer | d5b299c | 2017-08-11 18:26:50 +0200 | [diff] [blame] | 44 | |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 45 | |
| 46 | Installation |
| 47 | ------------------------------------------------------------------------ |
| 48 | |
| 49 | Install cachetools using pip:: |
| 50 | |
| 51 | pip install cachetools |
| 52 | |
| 53 | |
| 54 | Project Resources |
| 55 | ------------------------------------------------------------------------ |
| 56 | |
Thomas Kemmer | 2f95610 | 2014-10-12 15:03:51 +0200 | [diff] [blame] | 57 | .. image:: http://img.shields.io/pypi/v/cachetools.svg?style=flat |
Thomas Kemmer | 4649656 | 2014-10-23 18:44:58 +0200 | [diff] [blame] | 58 | :target: https://pypi.python.org/pypi/cachetools/ |
| 59 | :alt: Latest PyPI version |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 60 | |
Thomas Kemmer | c22a043 | 2014-11-04 20:04:22 +0100 | [diff] [blame] | 61 | .. image:: http://img.shields.io/travis/tkem/cachetools/master.svg?style=flat |
Thomas Kemmer | 4649656 | 2014-10-23 18:44:58 +0200 | [diff] [blame] | 62 | :target: https://travis-ci.org/tkem/cachetools/ |
| 63 | :alt: Travis CI build status |
| 64 | |
Thomas Kemmer | c22a043 | 2014-11-04 20:04:22 +0100 | [diff] [blame] | 65 | .. image:: http://img.shields.io/coveralls/tkem/cachetools/master.svg?style=flat |
Thomas Kemmer | 4649656 | 2014-10-23 18:44:58 +0200 | [diff] [blame] | 66 | :target: https://coveralls.io/r/tkem/cachetools |
| 67 | :alt: Test coverage |
Thomas Kemmer | 2f95610 | 2014-10-12 15:03:51 +0200 | [diff] [blame] | 68 | |
Thomas Kemmer | d5b299c | 2017-08-11 18:26:50 +0200 | [diff] [blame] | 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 | |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 73 | - `Issue Tracker`_ |
| 74 | - `Source Code`_ |
| 75 | - `Change Log`_ |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 76 | |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 77 | |
| 78 | License |
| 79 | ------------------------------------------------------------------------ |
| 80 | |
Thomas Kemmer | 45d9b0d | 2018-05-12 14:41:46 +0200 | [diff] [blame] | 81 | Copyright (c) 2014-2018 Thomas Kemmer. |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 82 | |
| 83 | Licensed under the `MIT License`_. |
| 84 | |
| 85 | |
Thomas Kemmer | 5385445 | 2014-11-12 07:58:59 +0100 | [diff] [blame] | 86 | .. _@lru_cache: http://docs.python.org/3/library/functools.html#functools.lru_cache |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 87 | .. _mutable: http://docs.python.org/dev/glossary.html#term-mutable |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 88 | .. _mapping: http://docs.python.org/dev/glossary.html#term-mapping |
| 89 | .. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 90 | |
Thomas Kemmer | d5b299c | 2017-08-11 18:26:50 +0200 | [diff] [blame] | 91 | .. _Documentation: http://cachetools.readthedocs.io/en/latest/ |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 92 | .. _Issue Tracker: https://github.com/tkem/cachetools/issues/ |
Thomas Kemmer | 78408a1 | 2014-09-18 05:32:16 +0200 | [diff] [blame] | 93 | .. _Source Code: https://github.com/tkem/cachetools/ |
Thomas Kemmer | 101513c | 2014-11-05 19:56:17 +0100 | [diff] [blame] | 94 | .. _Change Log: https://github.com/tkem/cachetools/blob/master/CHANGES.rst |
Thomas Kemmer | 3b9d819 | 2014-03-27 06:23:04 +0100 | [diff] [blame] | 95 | .. _MIT License: http://raw.github.com/tkem/cachetools/master/LICENSE |