Python functools.cached_propertyの使い方|propertyとの違い・キャッシュのクリア・使えないクラス

functools.cached_propertyは、メソッドの計算結果を最初の1回だけ計算し、そのあとはインスタンスの属性として保存して使い回すデコレータです。@propertyと違って毎回計算しないので速くなりますが、元のデータが変わっても値が古いままになるため、キャッシュを消すにはdel obj.属性名を使います。

この記事では、functoolsモジュールのクラスの中でも質問の多いcached_propertyを中心に、@propertyとの違い、キャッシュのクリア方法、使えないクラス(__slots__)、lru_cacheとの使い分けを、実際に動かした結果で解説します。コードはPython 3.12.15で実行しました。仕様は公式ドキュメント(functools — Higher-order functions and operations on callable objects、Python 3.15版、2026年10月18日確認)で確かめています。

functoolsのクラス一覧

functoolsで「クラス」として提供されているのは次の4つです。いずれもtypeのインスタンス(クラス)であることを確認できます。

from functools import partial, partialmethod, singledispatchmethod, cached_property
for c in (partial, partialmethod, singledispatchmethod, cached_property):
    print(c.__name__, type(c).__name__)

実行結果:

partial type
partialmethod type
singledispatchmethod type
cached_property type
クラス 役割 詳しい解説
cached_property プロパティの結果をインスタンスに保存する(Python 3.8以降) この記事
partial 引数の一部を固定した新しい呼び出し口を作る functools.partial()の使い方
partialmethod クラスのメソッド版のpartial 同上
singledispatchmethod 引数の型ごとにメソッドの処理を分ける functools.singledispatch()

lru_cacheやwrapsなどの関数は「Python functools関数一覧」にまとめています。

cached_propertyの基本的な使い方

公式ドキュメントの例と同じく、データの標準偏差を求めるクラスで試します。計算が実行された回数がわかるように、メソッドの中で表示を入れています。

from functools import cached_property
import statistics

class DataSet:
    def __init__(self, numbers):
        self._data = tuple(numbers)

    @cached_property
    def stdev(self):
        print("  計算中…")
        return statistics.stdev(self._data)

ds = DataSet([62, 75, 81, 90, 58])
print(ds.stdev)
print(ds.stdev)
print(ds.__dict__)

実行結果:

  計算中…
13.255187663703596
13.255187663703596
{'_data': (62, 75, 81, 90, 58), 'stdev': 13.255187663703596}

「計算中…」は1回しか出ていません。最後の行を見ると、計算結果がインスタンスの__dict__にstdevという名前で保存されています。2回目以降は、メソッドではなくこの普通の属性が読まれる仕組みです。

公式ドキュメントは、この仕組みを「同じ名前の属性がまだないときだけ動き、結果を同じ名前の属性に書き込む。以降はその属性が優先される」と説明しています。計算が重く、インスタンスの中身が実質的に変わらないときに向いています。

@propertyとcached_propertyの違い

同じ「合計金額」を2通りで書き、元のデータを変えたときの動きを比べます。

from functools import cached_property

class Cart:
    def __init__(self, prices):
        self.prices = list(prices)

    @property
    def total_property(self):
        return sum(self.prices)

    @cached_property
    def total_cached(self):
        return sum(self.prices)

cart = Cart([100, 200])
print(cart.total_property, cart.total_cached)

cart.prices.append(300)
print(cart.total_property, cart.total_cached)   # cachedは古いまま

del cart.total_cached                           # キャッシュを消す
print(cart.total_property, cart.total_cached)

実行結果:

300 300
600 300
600 600

商品を追加したあと、@propertyは600に変わりましたが、cached_propertyは300のままです。これが一番の注意点です。

項目 @property @cached_property
計算する回数 読むたびに毎回 最初の1回だけ
元のデータが変わったとき 新しい値になる 古い値のまま(消すまで)
代入 setterがないとAttributeError できてしまう(普通の属性になる)
保存場所 保存しない インスタンスの__dict__
向いている値 軽い計算、常に最新であるべき値 重い計算で、元データが変わらない値

@propertyのsetterの書き方や読み取り専用にする方法は「Python @propertyの使い方」で解説しています。

キャッシュをクリアする方法

公式ドキュメントのとおり、属性を削除するとキャッシュが消え、次に読んだときにもう一度計算されます。ただし、まだ一度も読んでいない状態でdelするとエラーになります。

from functools import cached_property

class Cart:
    def __init__(self, prices):
        self.prices = list(prices)

    @cached_property
    def total(self):
        return sum(self.prices)

cart = Cart([100, 200])
try:
    del cart.total                  # まだ一度も読んでいない
except AttributeError as e:
    print("AttributeError:", e)

cart.__dict__.pop("total", None)    # 読んだかどうかに関係なく安全に消せる
print(cart.total)

cart.total = 0                      # 代入もできてしまう
print(cart.total)

実行結果:

AttributeError: 'Cart' object has no attribute 'total'
300
0

キャッシュが作られているかどうかわからない場所では、obj.__dict__.pop("属性名", None)と書くとエラーになりません。元データを変更するメソッドの中で、この1行を呼んでおく使い方が実用的です。

    def add(self, price):
        self.prices.append(price)
        self.__dict__.pop("total", None)   # 合計のキャッシュを捨てる

また、最後の例のようにcached_propertyには代入もできます(setterは不要)。読み取り専用にしたい値には向かない点も覚えておきましょう。

cached_propertyが使えないクラス

保存先としてインスタンスの__dict__が必要なので、__slots__で__dict__を持たないクラスでは使えません。

from dataclasses import dataclass
from functools import cached_property

@dataclass(frozen=True)
class Point:
    x: float
    y: float

    @cached_property
    def length(self):
        return (self.x ** 2 + self.y ** 2) ** 0.5

p = Point(3, 4)
print(p.length)

class Slotted:
    __slots__ = ("x",)

    def __init__(self, x):
        self.x = x

    @cached_property
    def double(self):
        return self.x * 2

try:
    Slotted(5).double
except TypeError as e:
    print("TypeError:", e)

実行結果:

5.0
TypeError: No '__dict__' attribute on 'Slotted' instance to cache 'double' property.

frozen=Trueのdataclassでは問題なく動きます(__dict__へ直接書き込むため)。一方、@dataclass(slots=True)にしたクラスでも同じTypeErrorになることを確認しました。公式ドキュメントは、メタクラスも__dict__が読み取り専用なので使えないと説明しています。

lru_cacheとの使い分け

メソッドの結果をキャッシュする道具は、cached_propertyとlru_cacheの2つです。公式のFAQ(How do I cache method calls?、2026年10月18日確認)では、次のように違いが説明されています。

項目 cached_property lru_cache(メソッドに付けた場合)
キャッシュの単位 インスタンスごと クラス全体で1つ
引数 取れない(selfだけ) ハッシュ可能な引数なら取れる
インスタンスの寿命 インスタンスが消えればキャッシュも消える キャッシュがインスタンスを参照し続け、消えにくい
キャッシュの上限 なし(インスタンスが増えればその分増える) maxsizeで上限を決められる

引数のない「インスタンスの性質」を表す値はcached_property、日付などの引数で結果が変わるメソッドはlru_cache、と分けるのが基本です。lru_cacheの使い方は「functools.lru_cache()とは?」、上限のないcacheは「functools.cache()とは?」で解説しています。

マルチスレッドでの注意(Python 3.12で変更)

Python 3.11までのcached_propertyには、計算が1回だけになるようにする内部のロックがありました。しかしロックがインスタンスごとではなくプロパティごとだったため待ちが多く発生し、Python 3.12でロックは削除されました(公式ドキュメントの「Changed in version 3.12」)。

そのため現在は、複数のスレッドが同時に初めて読むと、計算が複数回走ることがあります。何度計算されても結果が同じなら問題ありませんが、1回に限りたい場合は、メソッドの中でthreading.Lockを使うなど自分で同期を取る必要があります。

よくある質問

Q. cached_propertyとpropertyはどう使い分けますか?

常に最新の値が必要なものや軽い計算はproperty、計算が重く元のデータが変わらないものはcached_propertyを使います。cached_propertyは最初の値を保存し続けるので、元のデータを変える処理があるなら使わないか、変更時にキャッシュを消します。

Q. cached_propertyのキャッシュを消すにはどうしますか?

del obj.属性名で削除すると、次に読んだときに再計算されます。まだ一度も読んでいないとAttributeErrorになるので、確実に消したいときはobj.__dict__.pop(“属性名”, None)と書きます。

Q. TypeError: No ‘__dict__’ attribute on … instance to cache が出ます。

そのクラスが__slots__を使っていて、インスタンスに__dict__がないためです。dataclass(slots=True)も同じです。__slots__に”__dict__”を加えるか、propertyとlru_cacheを組み合わせる方法を検討します。

Q. cached_propertyはいつから使えますか?

Python 3.8で追加されました。Python 3.12からは内部のロックがなくなったため、マルチスレッドでは計算が複数回走ることがあります。

まとめ

  • @cached_propertyは最初の1回だけ計算し、結果をインスタンスの__dict__に保存する
  • 元データが変わっても値は古いまま。del obj.属性名かobj.__dict__.pop("属性名", None)でクリアする
  • __slots__を使うクラス(dataclass(slots=True)を含む)ではTypeError
  • 引数を取るメソッドのキャッシュはlru_cache。Python 3.12以降はスレッド間の排他は自分で行う

functoolsのほかの道具は「Python functools メンバー一覧」から辿れます。

通学型のプログラミングスクール「テックジム」では、デコレータやクラス設計のような中級の文法も、自分のペースで課題を進めながら、わからないところをトレーナーに質問して身につけられます。東京本校(永田町)では、毎週土曜に無料Python講座(ゼロからはじめるPython入門講座)を開いています。

あわせて読みたい


functools の関連記事

functoolsモジュールはメンバー一覧の視点でも整理しています。あわせて読むと、どの名前がどの分類にあたるのかを把握しやすくなります。

対面・無料|東京・永田町で毎週土曜日13時

この記事のようなコードを、講師に聞きながら動かしてみる

ゼロからはじめるPython入門講座

8年間・累計600回開催/これまで全国で2万人以上が参加

「やはり対面で聞けるのはとても気づきがあり、価値があると思います」

参加者の声

  • 本当に初心者からの講座です。プログラミングに触ったことがなくて大丈夫です
  • 対面だから、その場で聞けます。つまずいた所を持ち帰らずに解決できます
  • 講座は1時間。そのあとも残って学習を続けられ、講師にも質問できます
  • 独学で挫折した方も。糸口が見つかって、講座のあと会員になる方が多くいます

無料で参加する|開催日程を見る

参加費は無料です