デコレータパターン
関数を包むデコレータのあらゆる形 — 基本形、引数を受け取るデコレータ、functools.wraps、クラスデコレータ、ParamSpec までを整理します。
第11章 イテラブル、ジェネレータ、yield from で見た @contextmanager、第8章 dataclass の @dataclass、標準ライブラリの @functools.cache、FastAPI の @app.get(...) — どれもデコレータです。本章はそのパターンを自分で作るすべての方法を整理します。
本章の最後で扱う ParamSpec ベースのシグネチャ保存は、第20章 typing 上級 — Variance、ParamSpec、Self、overload で改めて扱います。デコレータを作る人ではなく ライブラリ作成者 の観点から追加の道具が登場します。
デコレータ = 関数を包む関数 #
def log_calls(fn):
def wrapper(*args, **kwargs):
print(f"呼び出し: {fn.__name__}({args}, {kwargs})")
result = fn(*args, **kwargs)
print(f"戻り値: {result}")
return result
return wrapper
@log_calls
def add(a: int, b: int) -> int:
return a + b
add(2, 3)
# 呼び出し: add((2, 3), {})
# 戻り値: 5@log_calls の上で関数を定義したのは、ただ次のシュガーです。
def add(a: int, b: int) -> int:
return a + b
add = log_calls(add)デコレータは関数を受け取って新しい関数を返します。 その結果、元の名前が新しい関数に束縛されるということです。
最初の落とし穴 — メタデータの喪失 #
上のコードの add はもう add ではありません。
@log_calls
def add(a: int, b: int) -> int:
"""2つの整数を足す。"""
return a + b
print(add.__name__) # 'wrapper' ← !
print(add.__doc__) # Noneこれを解いてくれるのが functools.wraps です。
from functools import wraps
def log_calls(fn):
@wraps(fn)
def wrapper(*args, **kwargs):
print(f"呼び出し: {fn.__name__}")
return fn(*args, **kwargs)
return wrapper
@log_calls
def add(a: int, b: int) -> int:
"""2つの整数を足す。"""
return a + b
print(add.__name__) # 'add'
print(add.__doc__) # '2つの整数を足す。'@wraps(fn) 一行が 名前、docstring、アノテーション、シグネチャ を元から複製してくれます。ユーザーデコレータを作るならほぼ常に付けるべき と考えればよいです。
引数を受け取るデコレータ #
@retry(times=3) のようにデコレータ自体に引数を与えるには、もう1段階追加されます。
@retry
def request(): ...
# 動作: request = retry(request)@retry(times=3)
def request(): ...
# 動作: request = retry(times=3)(request)
# ^^^^^^^^^^^^^^^^ これがデコレータを返さなければならないつまり retry(...) が デコレータを返す関数 にならなければなりません。3段ネスト になります。
from functools import wraps
def retry(times: int): # 1) 引数を受け取る
def decorator(fn): # 2) 関数を受け取る
@wraps(fn)
def wrapper(*args, **kwargs): # 3) 呼び出しを受け取る
last_error = None
for _ in range(times):
try:
return fn(*args, **kwargs)
except Exception as e:
last_error = e
raise last_error
return wrapper
return decorator
@retry(times=3)
def fetch():
...読み方:
- 一番外の
retry(times)— デコレータの引数 - 中間の
decorator(fn)— デコレートする関数 - 一番内の
wrapper(*args, **kwargs)— 実際の呼び出し
3段は不慣れに見えますが すべての引数ありデコレータの標準形 です。
functools.partial トリック
#
@retry() のように引数なしでも、@retry(3) のように引数を与えても動作するようにしたいとき。
from functools import wraps, partial
def retry(fn=None, *, times: int = 3):
if fn is None:
return partial(retry, times=times)
@wraps(fn)
def wrapper(*args, **kwargs):
for _ in range(times):
try:
return fn(*args, **kwargs)
except Exception:
continue
raise
return wrapper
@retry
def a(): ...
@retry(times=5)
def b(): ...複雑なのでよくは使いません。普通は どちらかに統一する のがきれいです。
よく使う標準デコレータ #
@functools.cache / @lru_cache — メモ化
#
from functools import cache
@cache
def fib(n: int) -> int:
if n < 2:
return n
return fib(n - 1) + fib(n - 2)
print(fib(100)) # 354224848179261915075 — 即時返却同じ引数で再度呼び出されると計算せずに結果をそのまま返します。純粋関数だけに使ってください(副作用のある関数には使えません)。
@lru_cache(maxsize=128) はキャッシュサイズ制限のあるバージョン。メモリが無制限に増えるのを防ぎたいとき。
@property — 属性のように呼び出す
#
from dataclasses import dataclass
@dataclass
class Rectangle:
width: float
height: float
@property
def area(self) -> float:
return self.width * self.height
r = Rectangle(3, 4)
print(r.area) # 12.0 ← メソッド呼び出しではなく属性アクセス@property の一般化が第16章 ディスクリプタと __set_name__ のディスクリプタプロトコルです。
@staticmethod / @classmethod
#
class Math:
@staticmethod
def add(a: int, b: int) -> int:
return a + b
@classmethod
def from_pair(cls, pair: tuple[int, int]):
return cls(*pair)staticmethod — self も cls も受け取りません。classmethod — 第一引数としてクラス自身を受け取ります(代替コンストラクタによく使います)。
クラスデコレータ #
デコレータは クラスにも付けられます。 関数と同様に クラスを受け取ってクラスを返す 関数です。
def add_repr(cls):
def __repr__(self):
attrs = ", ".join(f"{k}={v!r}" for k, v in self.__dict__.items())
return f"{cls.__name__}({attrs})"
cls.__repr__ = __repr__
return cls
@add_repr
class User:
def __init__(self, id: int, name: str):
self.id = id
self.name = name
print(User(1, "カーティス"))
# User(id=1, name='カーティス')@dataclass がまさにこのパターンです — クラスを受け取って __init__ / __repr__ / __eq__ が追加されたクラスを返します。
デコレータクラス — 呼び出し時にオブジェクトにする方式 #
関数の代わりに __call__ を持つクラス をデコレータとして使うこともできます。状態が必要なときに合います。
class CallCounter:
def __init__(self, fn):
self.fn = fn
self.count = 0
def __call__(self, *args, **kwargs):
self.count += 1
return self.fn(*args, **kwargs)
@CallCounter
def greet():
print("hi")
greet()
greet()
greet()
print(greet.count) # 3greet は今や CallCounter のインスタンスです。.count のような属性アクセスが自然に可能です。短所: 関数のシグネチャ / メタデータ保存が難しく、静的解析器が扱いにくく見えます。状態が不要なら関数デコレータ の方が優れています。
メソッドにデコレータ — self まで流れる
#
デコレータの中の wrapper が *args, **kwargs の形で受け取るので メソッドの self はただ args[0] として入ってきます。
def log_calls(fn):
@wraps(fn)
def wrapper(*args, **kwargs):
print(f"呼び出し: {fn.__name__}")
return fn(*args, **kwargs)
return wrapper
class Service:
@log_calls
def fetch(self, url: str):
return f"data from {url}"
s = Service()
s.fetch("https://api.example.com")
# 呼び出し: fetch特別な処理は不要です。ちゃんと動きます。
デコレータの型ヒント — ParamSpec
#
デコレータに型を書くと静的解析が正確になります。ところがデコレータは 任意の関数 を包むため、型をそのまま保存するのが難しいです。これを解いてくれる道具が ParamSpec です。
from typing import Callable
from collections.abc import Awaitable
def log_calls[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
@wraps(fn)
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
print(f"呼び出し: {fn.__name__}")
return fn(*args, **kwargs)
return wrapper[**P, R] (3.12+) の意味:
P— 関数のパラメータのシグネチャをそのままR— 戻り値の型
このように書けば デコレートされた関数のシグネチャがそのまま維持 されます。呼び出し側の自動補完と検証が正確になります。旧方式は次のとおり。
from typing import TypeVar, ParamSpec, Callable
from functools import wraps
P = ParamSpec("P")
R = TypeVar("R")
def log_calls(fn: Callable[P, R]) -> Callable[P, R]:
@wraps(fn)
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
return fn(*args, **kwargs)
return wrapper新コードはメソッド横の [**P, R] 形式で。第20章 typing 上級 で ParamSpec の他の使い道(引数の一部だけ受け取るデコレータなど)を改めて扱います。
合成 — デコレータを複数積む #
@log_calls
@retry(times=3)
@cache
def fetch(url): ...上のコードは 下から上に 適用されます。
fetch = log_calls(retry(times=3)(cache(fetch)))順序に意味のある部分なので注意してください。上の例では:
cacheが最初 — キャッシュヒットなら retry も回らないretryが次 — キャッシュミスで実際の呼び出しが起きるときに再試行log_callsが一番外 — 再試行を含むすべての呼び出しをロギング
よく作るパターン — 一か所に #
時間計測 #
import time
from functools import wraps
def timing[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
@wraps(fn)
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
start = time.perf_counter()
result = fn(*args, **kwargs)
elapsed = time.perf_counter() - start
print(f"{fn.__name__}: {elapsed:.3f}s")
return result
return wrapper権限チェック #
def require_admin(fn):
@wraps(fn)
def wrapper(user, *args, **kwargs):
if not user.is_admin:
raise PermissionError("管理者のみ可能")
return fn(user, *args, **kwargs)
return wrapper
@require_admin
def delete_user(actor, target_id): ...ウェブフレームワークの権限処理は普通この構造を取ります。4部 FastAPI では第23章 ルーティング、Pydantic モデル、依存性注入 の Depends システムがこの役割を担います。
結果のキャッシュ (TTL あり) #
from functools import wraps
import time
def ttl_cache(seconds: float):
def decorator(fn):
cache_data: dict = {}
@wraps(fn)
def wrapper(*args, **kwargs):
key = (args, tuple(sorted(kwargs.items())))
now = time.monotonic()
if key in cache_data:
value, ts = cache_data[key]
if now - ts < seconds:
return value
value = fn(*args, **kwargs)
cache_data[key] = (value, now)
return value
return wrapper
return decorator
@ttl_cache(seconds=60)
def get_config(): ...練習問題 #
@timingデコレータを[**P, R]シグネチャで書いてください。呼び出された関数の実行時間をprint(f"{fn.__name__}: {elapsed:.3f}s")形式で出力します。@wraps(fn)適用後にadd.__name__が"add"として残るか確認します。@retry(times=3, delay=0.1)の形で呼び出す、引数ありのデコレータを書いてください。失敗時にdelay秒待ってから再試行し、すべての試行が失敗すれば最後の例外を再度投げます。わざと 1/3 の確率で失敗する関数を作って統計が合うか確認します。- クラスデコレータ
@add_reprを書いて、__dict__のすべてのフィールドを出力する__repr__を自動的に追加してください。同じ仕事を@dataclassがどのようにするか、第8章 dataclass と比較してみます。
一行まとめ: デコレータは関数を受け取って関数を返す関数。
@dはf = d(f)のシュガー。ユーザーデコレータにはほぼ常に@functools.wraps(fn)。引数ありデコレータは3段ネスト。クラスにも付けられ (@dataclass)、クラス形態 (__call__) も可能。シグネチャ保存は[**P, R](3.12+)。複数のデコレータは下から上に適用。
次の章 #
次の 第13章 パターンマッチング深掘り では、第3章 制御フロー で少しだけ見た match-case のあらゆるパターン — クラスパターン、__match_args__、キャプチャ変数、ガードの深さを扱います。