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, |
| 5 | including a variant of the Python 3 Standard Library |
| 6 | `functools.lru_cache` function decorator. |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 7 | |
| 8 | .. code-block:: pycon |
| 9 | |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 10 | >>> from cachetools import LRUCache |
| 11 | >>> cache = LRUCache(maxsize=2) |
Thomas Kemmer | b210c14 | 2014-06-16 20:22:12 +0200 | [diff] [blame^] | 12 | >>> cache.update([('first', 1), ('second', 2)]) |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 13 | >>> cache |
Thomas Kemmer | b210c14 | 2014-06-16 20:22:12 +0200 | [diff] [blame^] | 14 | LRUCache([('second', 2), ('first', 1)], maxsize=2, currsize=2) |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 15 | >>> cache['third'] = 3 |
| 16 | >>> cache |
Thomas Kemmer | b210c14 | 2014-06-16 20:22:12 +0200 | [diff] [blame^] | 17 | LRUCache([('second', 2), ('third', 3)], maxsize=2, currsize=2) |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 18 | >>> cache['second'] |
| 19 | 2 |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 20 | >>> cache['fourth'] = 4 |
Thomas Kemmer | b210c14 | 2014-06-16 20:22:12 +0200 | [diff] [blame^] | 21 | LRUCache([('second', 2), ('fourth', 4)], maxsize=2, currsize=2) |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 22 | |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 23 | |
Thomas Kemmer | b210c14 | 2014-06-16 20:22:12 +0200 | [diff] [blame^] | 24 | For the purpose of this module, a *cache* is a mutable_ mapping_ of a |
| 25 | fixed maximum *size*. When the cache is full, i.e. the current size |
| 26 | of the cache exceeds its maximum size, the cache must choose which |
| 27 | item(s) to discard based on a suitable `cache algorithm`_. |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 28 | |
Thomas Kemmer | b210c14 | 2014-06-16 20:22:12 +0200 | [diff] [blame^] | 29 | In general, a cache's size is the sum of the size of its items. If |
| 30 | the size of each items is :const:`1`, a cache's size is equal to the |
| 31 | number of its items, i.e. :func:`len`. An items's size may also be a |
| 32 | property or function of its value, e.g. the result of |
| 33 | :func:`sys.getsizeof`, or :func:`len` for string and sequence values. |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 34 | |
| 35 | This module provides various cache implementations based on different |
| 36 | cache algorithms, as well as decorators for easily memoizing function |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 37 | and method calls. |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 38 | |
| 39 | |
| 40 | Installation |
| 41 | ------------------------------------------------------------------------ |
| 42 | |
| 43 | Install cachetools using pip:: |
| 44 | |
| 45 | pip install cachetools |
| 46 | |
| 47 | |
| 48 | Project Resources |
| 49 | ------------------------------------------------------------------------ |
| 50 | |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 51 | .. image:: http://img.shields.io/pypi/v/cachetools.svg |
| 52 | :target: https://pypi.python.org/pypi/cachetools/ |
| 53 | :alt: Latest PyPI version |
| 54 | |
| 55 | .. image:: http://img.shields.io/pypi/dm/cachetools.svg |
| 56 | :target: https://pypi.python.org/pypi/cachetools/ |
| 57 | :alt: Number of PyPI downloads |
| 58 | |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 59 | - `Documentation`_ |
| 60 | - `Issue Tracker`_ |
| 61 | - `Source Code`_ |
| 62 | - `Change Log`_ |
Thomas Kemmer | fa0e606 | 2014-03-22 11:09:33 +0100 | [diff] [blame] | 63 | |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 64 | |
| 65 | License |
| 66 | ------------------------------------------------------------------------ |
| 67 | |
Thomas Kemmer | 573b318 | 2014-04-02 20:44:06 +0200 | [diff] [blame] | 68 | Copyright (c) 2014 Thomas Kemmer. |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 69 | |
| 70 | Licensed under the `MIT License`_. |
| 71 | |
| 72 | |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 73 | .. _functools.lru_cache: http://docs.python.org/3.4/library/functools.html#functools.lru_cache |
Thomas Kemmer | bf206e0 | 2014-05-06 20:26:34 +0200 | [diff] [blame] | 74 | .. _mutable: http://docs.python.org/dev/glossary.html#term-mutable |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 75 | .. _mapping: http://docs.python.org/dev/glossary.html#term-mapping |
| 76 | .. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms |
Thomas Kemmer | a34b1fa | 2014-03-22 12:57:39 +0100 | [diff] [blame] | 77 | |
| 78 | .. _Documentation: http://pythonhosted.org/cachetools/ |
| 79 | .. _Source Code: https://github.com/tkem/cachetools/ |
| 80 | .. _Issue Tracker: https://github.com/tkem/cachetools/issues/ |
Thomas Kemmer | 35f85f2 | 2014-03-25 06:44:31 +0100 | [diff] [blame] | 81 | .. _Change Log: http://raw.github.com/tkem/cachetools/master/Changes |
Thomas Kemmer | 3b9d819 | 2014-03-27 06:23:04 +0100 | [diff] [blame] | 82 | .. _MIT License: http://raw.github.com/tkem/cachetools/master/LICENSE |