Leveraging functools.cached_property for Expensive Calculations in Python Classes

Introduction

When I first started using Python in production, I often found myself recomputing the same derived values over and over. Whether it was formatting a date for display, normalizing a string, or calculating a checksum, the logic lived inside a class method, and each access forced a fresh calculation. The performance hit wasn’t noticeable in small scripts, but in a web service handling thousands of requests it added up quickly. That’s when I discovered functools.cached_property and realized how much cleaner and faster my code could be.

The Problem: Repeating Heavy Work

Consider a simple User model that needs to expose a read‑only property called display_name. The property concatenates first and last names, applies a title case transformation, and then strips any extra whitespace. In a typical request handler you might write:

class User:
    def __init__(self, first, last):
        self.first = first
        self.last = last

    @property
    def display_name(self):
        # Simulate an expensive operation
        name = f"{self.first} {self.last}".title().strip()
        # In real code this could involve database lookups, regex, etc.
        return name

Every time user.display_name is accessed, the function runs again. If the same user object is rendered in a template, API response, and log entry, the work is repeated three times. The overhead becomes obvious when the transformation grows more complex, especially when the property is accessed from multiple threads or inside loops.

A Simple Solution: functools.cached_property

Python’s standard library provides functools.cached_property exactly for this scenario. It caches the result of the first call and returns the stored value on subsequent accesses. The decorator works like a regular property but adds an internal cache that lives on the instance.

Here’s how the same example looks with caching:

from functools import cached_property

class User:
    def __init__(self, first, last):
        self.first = first
        self.last = last

    @cached_property
    def display_name(self):
        # This runs only once per instance
        name = f"{self.first} {self.last}".title().strip()
        return name

Now the expensive computation happens just once, regardless of how many times display_name is read. The cache is tied to the instance, so different User objects each have their own cached value.

Why It Works: The Magic Behind the Cache

Under the hood, cached_property stores the computed value in a private attribute whose name is derived from the property name (e.g., _display_name). When the property is first accessed, the descriptor’s __get__ method computes the value, sets it on the instance, and returns it. Subsequent accesses bypass the computation and retrieve the stored value directly.

Because the cache is instance‑specific, it also respects mutability of other attributes. If first or last change, the cached display_name becomes stale. That’s usually fine for read‑only derived fields, but if you need invalidation you can either delete the cached attribute manually or use a custom descriptor that watches for changes.

Production‑Ready Example: Caching a Complex Calculation

In a real‑world service I once worked on, we needed to generate a SHA‑256 hash of a user’s email address after lower‑casing it and removing whitespace. The hash was used for generating a deterministic user ID. The calculation involved a call to a third‑party email validation library, which added latency. Using cached_property eliminated the repeated validation:

import hashlib
from functools import cached_property

class Customer:
    def __init__(self, email):
        self.email = email
        # Optional: store raw email for debugging
        self.raw_email = email

    @cached_property
    def normalized_email(self):
        # Perform expensive normalization (strip, lower, validation)
        normalized = self.email.strip().lower()
        # Here we could call validation library, but for demo we skip it
        return normalized

    @cached_property
    def user_id(self):
        # Derive a deterministic ID from normalized email
        return hashlib.sha256(self.normalized_email.encode()).hexdigest()

    def __repr__(self):
        return f"Customer(email={self.email!r}, id={self.user_id})"