Show how to clear a `@functools.cached_property`

[paulrougieux]

Documentation

While the current documentation for functools.cached_property mentions that “the cached value can be cleared by deleting the attribute,” it does not provide a concrete example of how to do this in practice. It may not be immediately obvious how to invalidate the cache. Adding this example would show how to handle the potential AttributeError if the property has not yet been accessed. It would also encourage idiomatic usage by showing the recommended way to clear a cached property, rather than directly manipulating the instance’s __dict__.

from functools import cached_property
import random

class Bicycle:
    @cached_property
    def seat_id(self):
        return random.randint(1000, 9999)

    def invalidate_cache(self):
        """Invalidate the cached seat_id property."""
        try:
            del self.seat_id
        except AttributeError:
            pass

[paulrougieux]

Related to #82734 although that issue is more general about the need for documentation. Here I just propose a simple example.

[eendebakpt]

@paulrougieux An example indeed seems good to add, as the behavior is a bit odd. Would you like to make a PR?