285 lines
10 KiB
Plaintext
285 lines
10 KiB
Plaintext
Metadata-Version: 1.1
|
|
Name: cached-property
|
|
Version: 1.3.0
|
|
Summary: A decorator for caching properties in classes.
|
|
Home-page: https://github.com/pydanny/cached-property
|
|
Author: Daniel Greenfeld
|
|
Author-email: pydanny@gmail.com
|
|
License: BSD
|
|
Description: ===============================
|
|
cached-property
|
|
===============================
|
|
|
|
.. image:: https://img.shields.io/pypi/v/cached-property.svg
|
|
:target: https://pypi.python.org/pypi/cached-property
|
|
|
|
.. image:: https://img.shields.io/travis/pydanny/cached-property/master.svg
|
|
:target: https://travis-ci.org/pydanny/cached-property
|
|
|
|
|
|
A decorator for caching properties in classes.
|
|
|
|
Why?
|
|
-----
|
|
|
|
* Makes caching of time or computational expensive properties quick and easy.
|
|
* Because I got tired of copy/pasting this code from non-web project to non-web project.
|
|
* I needed something really simple that worked in Python 2 and 3.
|
|
|
|
How to use it
|
|
--------------
|
|
|
|
Let's define a class with an expensive property. Every time you stay there the
|
|
price goes up by $50!
|
|
|
|
.. code-block:: python
|
|
|
|
class Monopoly(object):
|
|
|
|
def __init__(self):
|
|
self.boardwalk_price = 500
|
|
|
|
@property
|
|
def boardwalk(self):
|
|
# In reality, this might represent a database call or time
|
|
# intensive task like calling a third-party API.
|
|
self.boardwalk_price += 50
|
|
return self.boardwalk_price
|
|
|
|
Now run it:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> monopoly = Monopoly()
|
|
>>> monopoly.boardwalk
|
|
550
|
|
>>> monopoly.boardwalk
|
|
600
|
|
|
|
Let's convert the boardwalk property into a ``cached_property``.
|
|
|
|
.. code-block:: python
|
|
|
|
from cached_property import cached_property
|
|
|
|
class Monopoly(object):
|
|
|
|
def __init__(self):
|
|
self.boardwalk_price = 500
|
|
|
|
@cached_property
|
|
def boardwalk(self):
|
|
# Again, this is a silly example. Don't worry about it, this is
|
|
# just an example for clarity.
|
|
self.boardwalk_price += 50
|
|
return self.boardwalk_price
|
|
|
|
Now when we run it the price stays at $550.
|
|
|
|
.. code-block:: python
|
|
|
|
>>> monopoly = Monopoly()
|
|
>>> monopoly.boardwalk
|
|
550
|
|
>>> monopoly.boardwalk
|
|
550
|
|
>>> monopoly.boardwalk
|
|
550
|
|
|
|
Why doesn't the value of ``monopoly.boardwalk`` change? Because it's a **cached property**!
|
|
|
|
Invalidating the Cache
|
|
----------------------
|
|
|
|
Results of cached functions can be invalidated by outside forces. Let's demonstrate how to force the cache to invalidate:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> monopoly = Monopoly()
|
|
>>> monopoly.boardwalk
|
|
550
|
|
>>> monopoly.boardwalk
|
|
550
|
|
>>> # invalidate the cache
|
|
>>> del monopoly.__dict__['boardwalk']
|
|
>>> # request the boardwalk property again
|
|
>>> monopoly.boardwalk
|
|
600
|
|
>>> monopoly.boardwalk
|
|
600
|
|
|
|
Working with Threads
|
|
---------------------
|
|
|
|
What if a whole bunch of people want to stay at Boardwalk all at once? This means using threads, which
|
|
unfortunately causes problems with the standard ``cached_property``. In this case, switch to using the
|
|
``threaded_cached_property``:
|
|
|
|
.. code-block:: python
|
|
|
|
from cached_property import threaded_cached_property
|
|
|
|
class Monopoly(object):
|
|
|
|
def __init__(self):
|
|
self.boardwalk_price = 500
|
|
|
|
@threaded_cached_property
|
|
def boardwalk(self):
|
|
"""threaded_cached_property is really nice for when no one waits
|
|
for other people to finish their turn and rudely start rolling
|
|
dice and moving their pieces."""
|
|
|
|
sleep(1)
|
|
self.boardwalk_price += 50
|
|
return self.boardwalk_price
|
|
|
|
Now use it:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> from threading import Thread
|
|
>>> from monopoly import Monopoly
|
|
>>> monopoly = Monopoly()
|
|
>>> threads = []
|
|
>>> for x in range(10):
|
|
>>> thread = Thread(target=lambda: monopoly.boardwalk)
|
|
>>> thread.start()
|
|
>>> threads.append(thread)
|
|
|
|
>>> for thread in threads:
|
|
>>> thread.join()
|
|
|
|
>>> self.assertEqual(m.boardwalk, 550)
|
|
|
|
|
|
Timing out the cache
|
|
--------------------
|
|
|
|
Sometimes you want the price of things to reset after a time. Use the ``ttl``
|
|
versions of ``cached_property`` and ``threaded_cached_property``.
|
|
|
|
.. code-block:: python
|
|
|
|
import random
|
|
from cached_property import cached_property_with_ttl
|
|
|
|
class Monopoly(object):
|
|
|
|
@cached_property_with_ttl(ttl=5) # cache invalidates after 5 seconds
|
|
def dice(self):
|
|
# I dare the reader to implement a game using this method of 'rolling dice'.
|
|
return random.randint(2,12)
|
|
|
|
Now use it:
|
|
|
|
.. code-block:: python
|
|
|
|
>>> monopoly = Monopoly()
|
|
>>> monopoly.dice
|
|
10
|
|
>>> monopoly.dice
|
|
10
|
|
>>> from time import sleep
|
|
>>> sleep(6) # Sleeps long enough to expire the cache
|
|
>>> monopoly.dice
|
|
3
|
|
>>> monopoly.dice
|
|
3
|
|
|
|
**Note:** The ``ttl`` tools do not reliably allow the clearing of the cache. This
|
|
is why they are broken out into seperate tools. See https://github.com/pydanny/cached-property/issues/16.
|
|
|
|
Credits
|
|
--------
|
|
|
|
* Pip, Django, Werkzueg, Bottle, Pyramid, and Zope for having their own implementations. This package uses an implementation that matches the Bottle version.
|
|
* Reinout Van Rees for pointing out the `cached_property` decorator to me.
|
|
* My awesome wife `@audreyr`_ who created `cookiecutter`_, which meant rolling this out took me just 15 minutes.
|
|
* @tinche for pointing out the threading issue and providing a solution.
|
|
* @bcho for providing the time-to-expire feature
|
|
|
|
.. _`@audreyr`: https://github.com/audreyr
|
|
.. _`cookiecutter`: https://github.com/audreyr/cookiecutter
|
|
|
|
|
|
|
|
|
|
History
|
|
-------
|
|
|
|
1.3.0 (2015-11-24)
|
|
++++++++++++++++++
|
|
|
|
* Added official support for Python 3.5, thanks to @pydanny and @audreyr
|
|
* Removed confusingly placed lock from example, thanks to @ionelmc
|
|
* Corrected invalidation cache documentation, thanks to @proofit404
|
|
* Updated to latest Travis-CI environment, thanks to @audreyr
|
|
|
|
1.2.0 (2015-04-28)
|
|
++++++++++++++++++
|
|
|
|
* Overall code and test refactoring, thanks to @gsakkis
|
|
* Allow the del statement for resetting cached properties with ttl instead of del obj._cache[attr], thanks to @gsakkis.
|
|
* Uncovered a bug in PyPy, https://bitbucket.org/pypy/pypy/issue/2033/attributeerror-object-attribute-is-read, thanks to @gsakkis
|
|
* Fixed threaded_cached_property_with_ttl to actually be thread-safe, thanks to @gsakkis
|
|
|
|
1.1.0 (2015-04-04)
|
|
++++++++++++++++++
|
|
|
|
* Regression: As the cache was not always clearing, we've broken out the time to expire feature to its own set of specific tools, thanks to @pydanny
|
|
* Fixed typo in README, thanks to @zoidbergwill
|
|
|
|
1.0.0 (2015-02-13)
|
|
++++++++++++++++++
|
|
|
|
* Added timed to expire feature to ``cached_property`` decorator.
|
|
* **Backwards incompatiblity**: Changed ``del monopoly.boardwalk`` to ``del monopoly['boardwalk']`` in order to support the new TTL feature.
|
|
|
|
0.1.5 (2014-05-20)
|
|
++++++++++++++++++
|
|
|
|
* Added threading support with new ``threaded_cached_property`` decorator
|
|
* Documented cache invalidation
|
|
* Updated credits
|
|
* Sourced the bottle implementation
|
|
|
|
0.1.4 (2014-05-17)
|
|
++++++++++++++++++
|
|
|
|
* Fix the dang-blarged py_modules argument.
|
|
|
|
0.1.3 (2014-05-17)
|
|
++++++++++++++++++
|
|
|
|
* Removed import of package into ``setup.py``
|
|
|
|
0.1.2 (2014-05-17)
|
|
++++++++++++++++++
|
|
|
|
* Documentation fixes. Not opening up a RTFD instance for this because it's so simple to use.
|
|
|
|
0.1.1 (2014-05-17)
|
|
++++++++++++++++++
|
|
|
|
* setup.py fix. Whoops!
|
|
|
|
0.1.0 (2014-05-17)
|
|
++++++++++++++++++
|
|
|
|
* First release on PyPI.
|
|
|
|
Keywords: cached-property
|
|
Platform: UNKNOWN
|
|
Classifier: Development Status :: 5 - Production/Stable
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: License :: OSI Approved :: BSD License
|
|
Classifier: Natural Language :: English
|
|
Classifier: Programming Language :: Python :: 2
|
|
Classifier: Programming Language :: Python :: 2.6
|
|
Classifier: Programming Language :: Python :: 2.7
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Programming Language :: Python :: 3.3
|
|
Classifier: Programming Language :: Python :: 3.4
|
|
Classifier: Programming Language :: Python :: 3.5
|