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入門講座)を開いています。
あわせて読みたい
- Python functools.partial()とは?引数を固定した関数を作る方法
- Python functools.lru_cache()とは?計算結果をキャッシュする方法
- Python functools.cache()とは?結果を丸ごとキャッシュする方法
- Python functools.wraps()とは?デコレータで関数情報を保つ方法
- Python functools.total_ordering()とは?比較演算子を自動生成する方法
- Python functools.singledispatch()とは?型ごとに処理を分ける方法
- Python functools関数一覧|使い方をわかりやすく解説
- Python標準ライブラリのクラスとは?関数・メソッドとの違いも解説
- Python標準ライブラリのメソッドとは?関数との違いや使い方を解説
functools の関連記事
functoolsモジュールはメンバー一覧の視点でも整理しています。あわせて読むと、どの名前がどの分類にあたるのかを把握しやすくなります。





