A decorator for caching properties in classes.
Project description
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!
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:
>>> monopoly = Monopoly() >>> monopoly.boardwalk 550 >>> monopoly.boardwalk 600
Let’s convert the boardwalk property into a cached_property.
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.
>>> 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:
>>> 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:
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:
>>> 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.
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:
>>> 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
Support This Project
This project is maintained by volunteers. Support their efforts by spreading the word about:
History
1.3.0 (2015-11-24)
- Drop some non-ASCII characters from HISTORY.rst, thanks to @AdamWill
- 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cached_property-1.3.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8aacd79aa85a793419c76de9662d9a72ad4751eda2a8b8eb94223adc4d8d85f1 |
|
MD5 | 6eed185585787079dd52024a071757f7 |
|
BLAKE2-256 | a970a0e9c2f2d369808843d4b49c9f92f247ce54e50a684cc715d818e866ad30 |