Metadata-Version: 1.1
Name: cacheout
Version: 0.10.0
Summary: A caching library for Python
Home-page: https://github.com/dgilland/cacheout
Author: Derrick Gilland
Author-email: dgilland@gmail.com
License: MIT License
Description: cacheout
        ********
        
        |version| |travis| |coveralls| |license|
        
        
        A caching library for Python.
        
        
        Links
        =====
        
        - Project: https://github.com/dgilland/cacheout
        - Documentation: https://cacheout.readthedocs.io
        - PyPI: https://pypi.python.org/pypi/cacheout/
        - TravisCI: https://travis-ci.org/dgilland/cacheout
        
        
        Features
        ========
        
        - In-memory caching using dictionary backend
        - Cache manager for easily accessing multiple cache objects
        - Reconfigurable cache settings for runtime setup when using module-level cache objects
        - Maximum cache size enforcement
        - Default cache TTL (time-to-live) as well as custom TTLs per cache entry
        - Bulk set, get, and delete operations
        - Bulk get and delete operations filtered by string, regex, or function
        - Memoization decorators
        - Thread safe
        - Multiple cache implementations:
        
          - FIFO (First In, First Out)
          - LIFO (Last In, First Out)
          - LRU (Least Recently Used)
          - MRU (Most Recently Used)
          - LFU (Least Frequently Used)
          - RR (Random Replacement)
        
        
        Roadmap
        =======
        
        - Layered caching (multi-level caching)
        - Cache event listener support (e.g. on-get, on-set, on-delete)
        - Set-on-missing callback support in cache get
        - Cache statistics (e.g. cache hits/misses, cache frequency, etc)
        
        
        Requirements
        ============
        
        - Python >= 3.4
        
        
        Quickstart
        ==========
        
        Install using pip:
        
        
        ::
        
            pip install cacheout
        
        
        Let's start with some basic caching by creating a cache object:
        
        .. code-block:: python
        
            from cacheout import Cache
        
            cache = Cache()
        
        
        By default the ``cache`` object will have a maximum size of ``256`` and default TTL expiration turned off. These values can be set with:
        
        .. code-block:: python
        
            cache = Cache(maxsize=256, ttl=0, timer=time.time)  # defaults
        
        
        Set a cache key using ``cache.set()``:
        
        .. code-block:: python
        
            cache.set(1, 'foobar')
        
        
        Get the value of a cache key with ``cache.get()``:
        
        .. code-block:: python
        
            assert cache.get(1) == 'foobar'
        
        
        Set the TTL (time-to-live) expiration per entry:
        
        .. code-block:: python
        
            cache.set(3, {'data': {}}, ttl=1)
            assert cache.get(3) == {'data': {}}
            time.sleep(1)
            assert cache.get(3) is None
        
        
        Memoize a function where cache keys are generated from the called function parameters:
        
        .. code-block:: python
        
            @cache.memoize()
            def func(a, b):
                pass
        
        
        Provide a TTL for the memoized function and incorporate argument types into generated cache keys:
        
        .. code-block:: python
        
            @cache.memoize(ttl=5, typed=True)
            def func(a, b):
                pass
        
            # func(1, 2) has different cache key than func(1.0, 2.0), whereas,
            # with "typed=False" (the default), they would have the same key
        
        
        Access the original memoized function:
        
        .. code-block:: python
        
            @cache.memoize()
            def func(a, b):
                pass
        
            func.uncached(1, 2)
        
        
        Get a copy of the entire cache with ``cache.copy()``:
        
        .. code-block:: python
        
            assert cache.copy() == {1: 'foobar', 2: ('foo', 'bar', 'baz')}
        
        
        Delete a cache key with ``cache.delete()``:
        
        .. code-block:: python
        
            cache.delete(1)
            assert cache.get(1) is None
        
        
        Clear the entire cache with ``cache.clear()``:
        
        .. code-block:: python
        
            cache.clear()
            assert len(cache) == 0
        
        
        Perform bulk operations with ``cache.set_many()``, ``cache.get_many()``, and ``cache.delete_many()``:
        
        .. code-block:: python
        
            cache.set_many({'a': 1, 'b': 2, 'c': 3})
            assert cache.get_many(['a', 'b', 'c']) == {'a': 1, 'b': 2, 'c': 3}
            cache.delete_many(['a', 'b', 'c'])
            assert cache.count() == 0
        
        
        Use complex filtering in ``cache.get_many()`` and ``cache.delete_many()``:
        
        .. code-block:: python
        
            import re
            cache.set_many({'a_1': 1, 'a_2': 2, '123': 3, 'b': 4})
        
            cache.get_many('a_*') == {'a_1': 1, 'a_2': 2}
            cache.get_many(re.compile(r'\d')) == {'123': 3}
            cache.get_many(lambda key: '2' in key) == {'a_2': 2, '123': 3}
        
            cache.delete_many('a_*')
            assert dict(cache.items()) == {'123': 3, 'b': 4}
        
        
        Reconfigure the cache object after creation with ``cache.configure()``:
        
        .. code-block:: python
        
            cache.configure(maxsize=1000, ttl=5 * 60)
        
        
        Get keys, values, and items from the cache with ``cache.keys()``, ``cache.values()``, and ``cache.items()``:
        
        .. code-block:: python
        
            cache.set_many({'a': 1, 'b': 2, 'c': 3})
            assert list(cache.keys()) == ['a', 'b', 'c']
            assert list(cache.values()) == [1, 2, 3]
            assert list(cache.items()) == [('a', 1), ('b', 2), ('c', 3)]
        
        
        Iterate over cache keys:
        
        .. code-block:: python
        
            for key in cache:
                print(key, cache.get(key))
                # 'a' 1
                # 'b' 2
                # 'c' 3
        
        
        Check if key exists with ``cache.has()`` and ``key in cache``:
        
        .. code-block:: python
        
            assert cache.has('a')
            assert 'a' in cache
        
        
        Manage multiple caches using ``CacheManager``:
        
        .. code-block:: python
        
            from cacheout import CacheManager
        
            cacheman = CacheManager({'a': {'maxsize': 100},
                                     'b': {'maxsize': 200, 'ttl': 900},
                                     'c': {})
        
            cacheman['a'].set('key1', 'value1')
            value = cacheman['a'].get('key')
        
            cacheman['b'].set('key2', 'value2')
            assert cacheman['b'].maxsize == 200
            assert cacheman['b'].ttl == 900
        
            cacheman['c'].set('key3', 'value3')
        
            cacheman.clear_all()
            for name, cache in cacheman:
                assert name in cacheman
                assert len(cache) == 0
        
        
        For more details, see the full documentation at https://cacheout.readthedocs.io.
        
        
        
        .. |version| image:: https://img.shields.io/pypi/v/cacheout.svg?style=flat-square
            :target: https://pypi.python.org/pypi/cacheout/
        
        .. |travis| image:: https://img.shields.io/travis/dgilland/cacheout/master.svg?style=flat-square
            :target: https://travis-ci.org/dgilland/cacheout
        
        .. |coveralls| image:: https://img.shields.io/coveralls/dgilland/cacheout/master.svg?style=flat-square
            :target: https://coveralls.io/r/dgilland/cacheout
        
        .. |license| image:: https://img.shields.io/pypi/l/cacheout.svg?style=flat-square
            :target: https://pypi.python.org/pypi/cacheout/
        
        
        Changelog
        =========
        
        
        v0.10.0 (2018-04-03)
        --------------------
        
        - Modify behavior of ``default`` argument to ``Cache.get()`` so that if ``default`` is a callable and the cache key is missing, then it will be called and its return value will be used as the value for cache key and subsequently be set as the value for the key in the cache. (**breaking change**)
        - Add ``default`` argument to ``Cache()`` that can be used to override the value for ``default`` in ``Cache.get()``.
        
        
        v0.9.0 (2018-03-31)
        -------------------
        
        - Merge functionality of ``Cache.get_many_by()`` into ``Cache.get_many()`` and remove ``Cache.get_many_by()``. (**breaking change**).
        - Merge functionality of ``Cache.delete_many_by()`` into ``Cache.delete_many()`` and remove ``Cache.delete_many_by()``. (**breaking change**).
        
        
        v0.8.0 (2018-03-30)
        -------------------
        
        - Add ``Cache.get_many_by()``.
        - Add ``Cache.delete_many_by()``.
        - Make ``Cache.keys()`` and ``Cache.values()`` return dictionary view objects instead of yielding items. (**breaking change**)
        
        
        v0.7.0 (2018-02-22)
        -------------------
        
        - Changed default cache ``maxsize`` from ``300`` to ``256``. (**breaking change**)
        - Add ``Cache.memoize()`` decorator.
        - Add standalone memoization decorators:
        
          - ``memoize``
          - ``fifo_memoize``
          - ``lfu_memoize``
          - ``lifo_memoize``
          - ``lru_memoize``
          - ``mru_memoize``
          - ``rr_memoize``
        
        
        v0.6.0 (2018-02-05)
        -------------------
        
        - Add ``LIFOCache``
        - Add ``FIFOCache`` as an alias of ``Cache``.
        
        
        v0.5.0 (2018-02-04)
        -------------------
        
        - Add ``LFUCache``
        - Delete expired items before popping an item in ``Cache.popitem()``.
        
        
        v0.4.0 (2018-02-02)
        -------------------
        
        - Add ``MRUCache``
        - Add ``RRCache``
        - Add ``Cache.popitem()``.
        - Rename ``Cache.expirations()`` to ``Cache.expire_times()``. (**breaking change**)
        - Rename ``Cache.count()`` to ``Cache.size()``. (**breaking change**)
        - Remove ``minimum`` arguement from ``Cache.evict()``. (**breaking change**)
        
        
        v0.3.0 (2018-01-31)
        -------------------
        
        - Add ``LRUCache``.
        - Add ``CacheManager.__repr__()``.
        - Make threading lock usage in ``Cache`` more fine-grained and eliminate redundant locking.
        - Fix missing thread-safety in ``Cache.__len__()`` and ``Cache.__contains__()``.
        
        
        v0.2.0 (2018-01-30)
        -------------------
        
        - Rename ``Cache.setup()`` to ``Cache.configure()``. (**breaking change**)
        - Add ``CacheManager`` class.
        
        
        v0.1.0 (2018-01-28)
        -------------------
        
        - Add ``Cache`` class.
        
Keywords: cacheout cache caching memoize memoization fifo lifo lfu lru mru
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Topic :: Database
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
