Skip to main content

A decorator for caching properties in classes.

Project description

cached-property

Github Actions status PyPI Code style: ruff

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. (Python 3.8 added a version of this decorator as @functools.cached_property.)

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:

    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:

    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)

Working with async/await

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:

from cached_property import cached_property

class Monopoly:

    def __init__(self):
        self.boardwalk_price = 500

    @cached_property
    async def boardwalk(self):
        self.boardwalk_price += 50
        return self.boardwalk_price

Now use it:

>>> async def print_boardwalk():
...     monopoly = Monopoly()
...     print(await monopoly.boardwalk)
...     print(await monopoly.boardwalk)
...     print(await monopoly.boardwalk)
>>> import asyncio
>>> asyncio.get_event_loop().run_until_complete(print_boardwalk())
550
550
550

Note 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 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, Werkzeug, 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 the cached_property decorator to me.
  • My awesome wife @audreyfeldroy 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

History

2.0.1 (2024-10-25)

  • Via python_requires specifies that cached_property is for Python version 3.8 or higher
  • Officiall drop support for Python 2.6

2.0.0 (2024-10-25)

  • Remove support for Python versions < 3.8
  • Add formal support for Python versions up to 3.13
  • Switch to Markdown for docs
  • Migrate from black to ruff

1.5.2 (2020-09-21)

  • Add formal support for Python 3.8
  • Remove formal support for Python 3.4
  • Switch from Travis to GitHub actions
  • Made tests pass flake8 for Python 2.7

1.5.1 (2018-08-05)

  • Added formal support for Python 3.7
  • Removed formal support for Python 3.3

1.4.3 (2018-06-14)

  • Catch SyntaxError from asyncio import on older versions of Python, thanks to @asottile

1.4.2 (2018-04-08)

  • Really fixed tests, thanks to @pydanny

1.4.1 (2018-04-08)

  • Added conftest.py to manifest so tests work properly off the tarball, thanks to @dotlambda
  • Ensured new asyncio tests didn't break Python 2.7 builds on Debian, thanks to @pydanny
  • Code formatting via black, thanks to @pydanny and @ambv

1.4.0 (2018-02-25)

  • Added asyncio support, thanks to @vbraun
  • Remove Python 2.6 support, whose end of life was 5 years ago, thanks to @pydanny

1.3.1 (2017-09-21)

  • Validate for Python 3.6

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)

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cached_property-2.0.1.tar.gz (10.6 kB view details)

Uploaded Source

Built Distribution

cached_property-2.0.1-py3-none-any.whl (7.4 kB view details)

Uploaded Python 3

File details

Details for the file cached_property-2.0.1.tar.gz.

File metadata

  • Download URL: cached_property-2.0.1.tar.gz
  • Upload date:
  • Size: 10.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.15

File hashes

Hashes for cached_property-2.0.1.tar.gz
Algorithm Hash digest
SHA256 484d617105e3ee0e4f1f58725e72a8ef9e93deee462222dbd51cd91230897641
MD5 a97302dfc447d087676996a84e22cab6
BLAKE2b-256 764b3d870836119dbe9a5e3c9a61af8cc1a8b69d75aea564572e385882d5aefb

See more details on using hashes here.

Provenance

File details

Details for the file cached_property-2.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for cached_property-2.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f617d70ab1100b7bcf6e42228f9ddcb78c676ffa167278d9f730d1c2fba69ccb
MD5 e7625e531c6993c70a5515a4c44f4511
BLAKE2b-256 110e7d8225aab3bc1a0f5811f8e1b557aa034ac04bdf641925b30d3caf586b28

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page