| Metadata-Version: 2.0 |
| 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 |
| 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 |
| |
| =============================== |
| 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. |
| |
| |