Package: 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 itLet’s define a class with an expensive property. Every time you stay there the
price goes up by $50!classMonopoly(object):def__init__(self):self.boardwalk_price=500@propertydefboardwalk(self):# In reality, this might represent a database call or time# intensive task like calling a third-party API.self.boardwalk_price+=50returnself.boardwalk_priceNow run it:>>>monopoly=Monopoly()>>>monopoly.boardwalk550>>>monopoly.boardwalk600Let’s convert the boardwalk property into acached_property.fromcached_propertyimportcached_propertyclassMonopoly(object):def__init__(self):self.boardwalk_price=500@cached_propertydefboardwalk(self):# Again, this is a silly example. Don't worry about it, this is#   just an example for clarity.self.boardwalk_price+=50returnself.boardwalk_priceNow when we run it the price stays at $550.>>>monopoly=Monopoly()>>>monopoly.boardwalk550>>>monopoly.boardwalk550>>>monopoly.boardwalk550Why doesn’t the value ofmonopoly.boardwalkchange? Because it’s acached property!Invalidating the CacheResults of cached functions can be invalidated by outside forces. Let’s demonstrate how to force the cache to invalidate:>>>monopoly=Monopoly()>>>monopoly.boardwalk550>>>monopoly.boardwalk550>>># invalidate the cache>>>delmonopoly.__dict__['boardwalk']>>># request the boardwalk property again>>>monopoly.boardwalk600>>>monopoly.boardwalk600Working with ThreadsWhat if a whole bunch of people want to stay at Boardwalk all at once? This means using threads, which
unfortunately causes problems with the standardcached_property. In this case, switch to using thethreaded_cached_property:fromcached_propertyimportthreaded_cached_propertyclassMonopoly(object):def__init__(self):self.boardwalk_price=500@threaded_cached_propertydefboardwalk(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+=50returnself.boardwalk_priceNow use it:>>>fromthreadingimportThread>>>frommonopolyimportMonopoly>>>monopoly=Monopoly()>>>threads=[]>>>forxinrange(10):>>>thread=Thread(target=lambda:monopoly.boardwalk)>>>thread.start()>>>threads.append(thread)>>>forthreadinthreads:>>>thread.join()>>>self.assertEqual(m.boardwalk,550)Working with async/await (Python 3.5+)The cached property can be async, in which case you have to use await
as usual to get the value. Because of the caching, the value is only
computed once and then cached:fromcached_propertyimportcached_propertyclassMonopoly(object):def__init__(self):self.boardwalk_price=500@cached_propertyasyncdefboardwalk(self):self.boardwalk_price+=50returnself.boardwalk_priceNow use it:>>>asyncdefprint_boardwalk():...monopoly=Monopoly()...print(awaitmonopoly.boardwalk)...print(awaitmonopoly.boardwalk)...print(awaitmonopoly.boardwalk)>>>importasyncio>>>asyncio.get_event_loop().run_until_complete(print_boardwalk())550550550Note that this does not work with threading either, most asyncio
objects are not thread-safe. And if you run separate event loops in
each thread, the cached version will most likely have the wrong event
loop. To summarize, either use cooperative multitasking (event loop)
or threading, but not both at the same time.Timing out the cacheSometimes you want the price of things to reset after a time. Use thettlversions ofcached_propertyandthreaded_cached_property.importrandomfromcached_propertyimportcached_property_with_ttlclassMonopoly(object):@cached_property_with_ttl(ttl=5)# cache invalidates after 5 secondsdefdice(self):# I dare the reader to implement a game using this method of 'rolling dice'.returnrandom.randint(2,12)Now use it:>>>monopoly=Monopoly()>>>monopoly.dice10>>>monopoly.dice10>>>fromtimeimportsleep>>>sleep(6)# Sleeps long enough to expire the cache>>>monopoly.dice3>>>monopoly.dice3Note:Thettltools do not reliably allow the clearing of the cache. This
is why they are broken out into seperate tools. Seehttps://github.com/pydanny/cached-property/issues/16.CreditsPip, Django, Werkzueg, Bottle, Pyramid, and Zope for having their own implementations. This package originally used an implementation that matched the Bottle version.Reinout Van Rees for pointing out thecached_propertydecorator to me.My awesome wife@audreyrwho createdcookiecutter, 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 featureSupport This ProjectThis project is maintained by volunteers. Support their efforts by spreading the word about:Django Crash CourseDjango Crash Course for Django 3.0 and Python 3.8 is the best cheese-themed Django reference in the universe!History1.5.2 (2020-09-21)Add formal support for Python 3.8Remove formal support for Python 3.4Switch from Travis to GitHub actionsMade tests pass flake8 for Python 2.71.5.1 (2018-08-05)Added formal support for Python 3.7Removed formal support for Python 3.31.4.3  (2018-06-14)Catch SyntaxError from asyncio import on older versions of Python, thanks to @asottile1.4.2 (2018-04-08)Really fixed tests, thanks to @pydanny1.4.1 (2018-04-08)Added conftest.py to manifest so tests work properly off the tarball, thanks to @dotlambdaEnsured new asyncio tests didn’t break Python 2.7 builds on Debian, thanks to @pydannyCode formatting via black, thanks to @pydanny and @ambv1.4.0 (2018-02-25)Added asyncio support, thanks to @vbraunRemove Python 2.6 support, whose end of life was 5 years ago, thanks to @pydanny1.3.1 (2017-09-21)Validate for Python 3.61.3.0 (2015-11-24)Drop some non-ASCII characters from HISTORY.rst, thanks to @AdamWillAdded official support for Python 3.5, thanks to @pydanny and @audreyrRemoved confusingly placed lock from example, thanks to @ionelmcCorrected invalidation cache documentation, thanks to @proofit404Updated to latest Travis-CI environment, thanks to @audreyr1.2.0 (2015-04-28)Overall code and test refactoring, thanks to @gsakkisAllow 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 @gsakkisFixed threaded_cached_property_with_ttl to actually be thread-safe, thanks to @gsakkis1.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 @pydannyFixed typo in README, thanks to @zoidbergwill1.0.0 (2015-02-13)Added timed to expire feature tocached_propertydecorator.Backwards incompatiblity: Changeddel monopoly.boardwalktodelmonopoly['boardwalk']in order to support the new TTL feature.0.1.5 (2014-05-20)Added threading support with newthreaded_cached_propertydecoratorDocumented cache invalidationUpdated creditsSourced the bottle implementation0.1.4 (2014-05-17)Fix the dang-blarged py_modules argument.0.1.3 (2014-05-17)Removed import of package intosetup.py0.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.