284 lines
9.9 KiB
Plaintext
284 lines
9.9 KiB
Plaintext
Metadata-Version: 1.1
|
||
Name: cached-property
|
||
Version: 1.2.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://badge.fury.io/py/cached-property.png
|
||
:target: http://badge.fury.io/py/cached-property
|
||
|
||
.. image:: https://travis-ci.org/pydanny/cached-property.png?branch=master
|
||
:target: https://travis-ci.org/pydanny/cached-property
|
||
|
||
.. image:: https://pypip.in/d/cached-property/badge.png
|
||
:target: https://pypi.python.org/pypi/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['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
|
||
|
||
import threading
|
||
|
||
from cached_property import threaded_cached_property
|
||
|
||
class Monopoly(object):
|
||
|
||
def __init__(self):
|
||
self.boardwalk_price = 500
|
||
self.lock = threading.Lock()
|
||
|
||
@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)
|
||
# Need to guard this since += isn't atomic.
|
||
with self.lock:
|
||
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.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 it’s 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 :: 4 - Beta
|
||
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
|