Pythonのデコレーター入門|@の仕組みとfunctools.wrapsを実例で解説
Python のコードを読んでいると、関数の上に @property や @functools.cache、Web フレームワークなら @app.route("/") のような「@ で始まる行」が出てきます。これがデコレーターです。書くだけで関数の動きが変わるので魔法のように見えますが、仕組みは「関数を受け取って、別の関数を返す関数」というだけです。
この記事では、関数を値として扱うところから始めて、自作のデコレーター、*args・**kwargs による引数の中継、functools.wraps の必要性、時間計測、引数付き、重ねる順番、標準のデコレーターまでを実行結果つきで説明します。載せている出力は、Windows 11・Python 3.12.6 で実際に実行したものです(メモリのアドレスや秒数は実行するたびに変わります)。
コードは sample.py などの名前で保存し、PowerShell でそのフォルダーに移動してから次のコマンドで実行できます。
py sample.py
デコレーターとは
Python の公式ドキュメントの用語集では、デコレーターは「別の関数を返す関数で、通常は @wrapper 構文で関数の変換として適用されるもの」と説明されています。さらに「デコレーターの構文は単なる糖衣構文(シンタックスシュガー)」とあり、次の 2 つは意味が同じだと書かれています。
def f(arg):
...
f = staticmethod(f)
@staticmethod
def f(arg):
...
糖衣構文とは「書きやすくするための別の書き方」です。@〇〇 は「定義したあとで 関数名 = 〇〇(関数名) と置き換える」を 1 行で書いたものにすぎません。
準備:関数は値として渡せる
Python では、関数も数値や文字列と同じく「値(オブジェクト)」です。かっこを付けずに関数名だけを書くと、関数を呼び出さずに関数そのものを扱えます。別の変数に入れたり、ほかの関数の引数に渡したりできます。
def greet(name):
return f"こんにちは、{name}さん"
say = greet
print(say("田中"))
print(say is greet)
こんにちは、田中さん
True
say = greet は「greet を呼んだ結果」ではなく「greet という関数そのもの」を say に入れています。say is greet が True なので、2 つの名前が同じ関数を指していることが分かります。greet と greet() の違い(かっこの有無)が、デコレーターを理解する鍵です。
関数を受け取り、関数を返す関数を書く
次に、関数を受け取って、それを包んだ新しい関数を返す shout を書きます。中で定義した wrapper は、元の関数を呼び、その結果に「!!」を足して返します。
def shout(func):
def wrapper(name):
return func(name) + "!!"
return wrapper
def greet(name):
return f"こんにちは、{name}さん"
print(greet("田中"))
greet = shout(greet)
print(greet("田中"))
print(greet.__name__)
こんにちは、田中さん
こんにちは、田中さん!!
wrapper
greet = shout(greet) のあと、greet という名前は元の関数ではなく wrapper を指しています。最後の行で __name__(関数の名前)を表示すると wrapper になっていることからも分かります。元の greet は消えたわけではなく、wrapper の中から func という名前で参照され続けています(このように内側の関数が外側の変数を覚えている仕組みをクロージャーと呼びます)。
@ 記法は「greet = shout(greet)」の書き換え
上の greet = shout(greet) を、関数定義の直前に @shout と書く形にしたのがデコレーター構文です。
def shout(func):
def wrapper(name):
return func(name) + "!!"
return wrapper
@shout
def greet(name):
return f"こんにちは、{name}さん"
print(greet("田中"))
こんにちは、田中さん!!

公式ドキュメントの「関数定義」の節では、デコレーターの式は関数が定義されたときに評価され、その結果(呼び出せるもの)が関数オブジェクトを唯一の引数として呼ばれ、戻り値が関数名に結び付けられる、と説明されています。ポイントは「定義したとき」に動くことです。次のコードで確かめます。
def register(func):
print(f"{func.__name__} を登録しました")
return func
@register
def task_a():
print("task_a を実行")
print("ここからメイン処理")
task_a()
task_a を登録しました
ここからメイン処理
task_a を実行
task_a をまだ一度も呼んでいないのに「登録しました」が先に表示されています。デコレーターの本体(register)は def を読んだ時点で 1 回だけ動き、包まれた関数(wrapper)が呼び出しのたびに動く、と区別して覚えてください。register のように関数をそのまま返す「登録するだけ」のデコレーターもあります。
*args・**kwargs でどんな引数でも中継する
さきほどの shout の wrapper は引数を name 1 つしか受け取りません。そのため、引数の形が違う関数に付けるとエラーになります。
def shout(func):
def wrapper(name):
return func(name) + "!!"
return wrapper
@shout
def greet(name, greeting="こんにちは"):
return f"{greeting}、{name}さん"
print(greet("田中", greeting="おはよう"))
Traceback (most recent call last):
...
TypeError: shout.<locals>.wrapper() got an unexpected keyword argument 'greeting'
エラーの関数名が wrapper になっているとおり、実際に呼ばれているのは wrapper です。どんな関数にも付けられるようにするには、wrapper を *args, **kwargs で受け取り、そのまま元の関数に渡します。*args は位置で渡された引数をタプルに、**kwargs は「名前=値」で渡された引数を辞書にまとめて受け取る書き方で、呼び出し側で func(*args, **kwargs) と書くと、まとめたものを元の形に展開して渡せます。
def log_call(func):
def wrapper(*args, **kwargs):
print(f"呼び出し:{func.__name__} args={args} kwargs={kwargs}")
result = func(*args, **kwargs)
print(f"戻り値:{result!r}")
return result
return wrapper
@log_call
def add(a, b):
return a + b
@log_call
def greet(name, greeting="こんにちは"):
return f"{greeting}、{name}さん"
add(2, 3)
greet("田中", greeting="おはよう")
呼び出し:add args=(2, 3) kwargs={}
戻り値:5
呼び出し:greet args=('田中',) kwargs={'greeting': 'おはよう'}
戻り値:'おはよう、田中さん'
引数が 2 つの add にも、キーワード引数のある greet にも、同じ log_call を付けられました。{result!r} の !r は、文字列を引用符付きで表示する指定です。wrapper の最後の return result を忘れると戻り値が消えるので注意してください(後の「よくある間違い」で実演します)。
functools.wraps で元の関数の名前と説明文を残す
デコレーターで包むと、名前 add が指しているのは wrapper です。そのため、関数の名前(__name__)や説明文(docstring、__doc__)も wrapper のものに変わってしまいます。
def log_call(func):
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@log_call
def add(a, b):
"""2 つの数を足す"""
return a + b
print(add.__name__)
print(add.__doc__)
print(add)
help(add)
wrapper
None
<function log_call.<locals>.wrapper at 0x0000019D03968E00>
Help on function wrapper in module __main__:
wrapper(*args, **kwargs)
名前は wrapper、説明文は None(なし)、help() で見ても引数は (*args, **kwargs) としか分からず、「2 つの数を足す」という説明も消えています。ログやエラーに出る関数名も wrapper になり、調べにくくなります。
これを防ぐのが標準ライブラリの functools.wraps です。wrapper の定義の上に @functools.wraps(func) を付けるだけです。
import functools
def log_call(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
@log_call
def add(a, b):
"""2 つの数を足す"""
return a + b
print(add.__name__)
print(add.__doc__)
print(add.__wrapped__)
help(add)
add
2 つの数を足す
<function add at 0x000001E6029B8E00>
Help on function add in module __main__:
add(a, b)
2 つの数を足す
名前・説明文・help() の表示が元の add に戻りました。公式ドキュメントによると、wraps は __module__・__name__・__qualname__・__annotations__・__type_params__・__doc__ を元の関数から写し、さらに元の関数を指す __wrapped__ という属性を付けます。add.__wrapped__ を呼べば、デコレーターを通さずに元の関数を直接呼べます。自作のデコレーターには、必ず functools.wraps を付けると覚えておけば十分です。
実例:実行時間を測るデコレーター
ここまでの内容を使って、関数の実行にかかった時間を表示するデコレーターを作ります。時間の計測には、短い時間を正確に測るための time.perf_counter() を使います。
import functools
import time
def timer(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
start = time.perf_counter()
try:
return func(*args, **kwargs)
finally:
elapsed = time.perf_counter() - start
print(f"{func.__name__}: {elapsed:.3f} 秒")
return wrapper
@timer
def slow_sum(n):
time.sleep(0.5)
return sum(range(n))
print(slow_sum(1_000_000))
slow_sum: 0.507 秒
499999500000
try・finally を使っているので、関数の途中で例外が起きても時間は表示されます(例外の扱いは関連記事の「例外処理入門」で詳しく説明しています)。return が finally より先に書かれていますが、finally の中身が実行されてから値が返されるため、表示の順番は「時間」→「戻り値」になっています。
引数付きデコレーター(3 段の入れ子)
@lru_cache(maxsize=2) や @app.route("/") のように、デコレーターに引数を渡したいことがあります。@repeat(3) は「まず repeat(3) を呼び、その戻り値をデコレーターとして使う」という意味なので、デコレーターを返す関数を作ります。関数が 3 段の入れ子になります。
import functools
def repeat(times):
def decorator(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
result = None
for i in range(times):
result = func(*args, **kwargs)
return result
return wrapper
return decorator
@repeat(3)
def hello(name):
print(f"Hello, {name}")
hello("Python")
Hello, Python
Hello, Python
Hello, Python
それぞれの段の役目は次のとおりです。
| 段 | 受け取るもの | 返すもの | 動くタイミング |
|---|---|---|---|
| repeat | デコレーターの引数(times) | decorator | @repeat(3) の行を読んだとき |
| decorator | 包む関数(func) | wrapper | その直後(def の定義時) |
| wrapper | 関数の引数(*args, **kwargs) | 関数の戻り値 | hello を呼ぶたび |
書き換えると hello = repeat(3)(hello) です。repeat(3) が decorator を返し、それに hello を渡しています。
デコレーターを重ねたときの順番
デコレーターは何個でも重ねられます。公式ドキュメントでは、複数のデコレーターは入れ子の形で適用され、@f1(arg)・@f2 の順に書いた関数 func は、おおよそ func = f1(arg)(f2(func)) と同じだと説明されています。つまり関数に近い(下にある)ものから順に包み、上にあるものほど外側になります。
def bold(func):
print("bold を適用")
def wrapper():
return "<b>" + func() + "</b>"
return wrapper
def italic(func):
print("italic を適用")
def wrapper():
return "<i>" + func() + "</i>"
return wrapper
@bold
@italic
def text():
return "hello"
print(text())
italic を適用
bold を適用
<b><i>hello</i></b>

包むのは下の italic が先、呼び出したときは外側の bold の wrapper から入ります。後で紹介する cache と timer を重ねる場合、timer を外側にするとキャッシュから返したときも測り、内側にすると実際に計算したときだけ測ります。重ねるときは「どれがいちばん外側か」を意識してください。
標準で用意されているデコレーター
自分で書かなくても、よく使うデコレーターは標準で用意されています。
@functools.cache と @functools.lru_cache:結果を覚えて再利用する
同じ引数で何度も呼ばれる関数の結果を覚えておき、2 回目からは計算せずに返します(メモ化と呼びます)。functools.cache は Python 3.9 で追加されたもので、公式ドキュメントでは lru_cache(maxsize=None) と同じ結果を返す、上限なしのキャッシュと説明されています。フィボナッチ数を再帰で計算する関数で比べます。
import functools
@functools.cache
def fib(n):
if n < 2:
return n
return fib(n - 1) + fib(n - 2)
print(fib(100))
print(fib.cache_info())
354224848179261915075
CacheInfo(hits=98, misses=101, maxsize=None, currsize=101)
キャッシュなしの fib(100) は計算回数が爆発的に増えて終わりませんが、cache 付きなら一瞬です。cache_info() を見ると、計算したのは n=0〜100 の 101 回(misses)だけで、残りの 98 回はキャッシュから返した(hits)ことが分かります。この PC で fib(35) の時間を測ると、キャッシュなしでは約 0.74 秒、cache 付きでは 0.00003 秒ほどでした。
メモリの使いすぎを防ぎたいときは、覚える件数に上限がある lru_cache を使います。上限を超えると、いちばん長く使われていないもの(LRU:Least Recently Used)から捨てます。maxsize を省略すると 128 件です。
import functools
@functools.lru_cache(maxsize=2)
def square(n):
print(f"計算します:{n}")
return n * n
square(1)
square(2)
square(1)
square(3)
square(2)
print(square.cache_info())
square.cache_clear()
print(square.cache_info())
計算します:1
計算します:2
計算します:3
計算します:2
CacheInfo(hits=1, misses=4, maxsize=2, currsize=2)
CacheInfo(hits=0, misses=0, maxsize=2, currsize=0)
3 回目の square(1) はキャッシュから返したので「計算します」が出ていません。square(3) を覚えた時点で上限の 2 件を超えるため、いちばん長く使われていない 2 が捨てられ、最後の square(2) はもう一度計算されています。cache_clear() でキャッシュを空にできます。
公式ドキュメントにあるとおり、副作用のある関数や random() のように呼ぶたびに結果が変わる関数には向きません。「同じ引数なら必ず同じ結果」の関数にだけ付けます。
@property:メソッドを属性のように読む
クラスの中のメソッドに @property を付けると、かっこなしの t.fahrenheit で呼べるようになります。さらに @名前.setter を付けたメソッドを用意すると、代入したときに値をチェックできます。
class Temperature:
def __init__(self, celsius):
self._celsius = celsius
@property
def celsius(self):
return self._celsius
@celsius.setter
def celsius(self, value):
if value < -273.15:
raise ValueError("絶対零度より低い温度は設定できません")
self._celsius = value
@property
def fahrenheit(self):
return self._celsius * 9 / 5 + 32
t = Temperature(25)
print(t.celsius, t.fahrenheit)
t.celsius = 100
print(t.celsius, t.fahrenheit)
t.fahrenheit = 0
25 77.0
100 212.0
Traceback (most recent call last):
...
AttributeError: property 'fahrenheit' of 'Temperature' object has no setter
fahrenheit には setter がないので、代入しようとするとエラーになります(読み取り専用の属性)。t.celsius = -300 と代入すると、setter の中のチェックで ValueError: 絶対零度より低い温度は設定できません になることも確かめました。公式ドキュメントにあるとおり、setter のメソッドは元の property と同じ名前(ここでは celsius)にする必要があります。
@staticmethod と @classmethod
通常のメソッドは最初の引数に自分自身(self)を受け取ります。@staticmethod を付けると self を受け取らない、クラスに置いただけの関数になります。@classmethod を付けると、self の代わりにクラスそのもの(慣習で cls と書く)を受け取ります。classmethod は「CSV の 1 行からインスタンスを作る」のような、別の作り方を用意するときによく使います。
class User:
count = 0
def __init__(self, name):
self.name = name
User.count += 1
@staticmethod
def is_valid_name(name):
return 1 <= len(name) <= 20
@classmethod
def from_csv(cls, line):
name = line.split(",")[0]
return cls(name)
print(User.is_valid_name("田中"))
u = User.from_csv("鈴木,30,東京")
print(u.name, User.count)
True
鈴木 1
このほか、クラスに付ける @dataclasses.dataclass もデコレーターです(使い方は関連記事を参照)。
よくある間違い
1. wrapper を return し忘れる
デコレーター本体の最後の return wrapper を忘れると、関数は値を返さないので None が返り、関数名に None が入ります。呼び出した時点で次のエラーになります。
TypeError: 'NoneType' object is not callable
「None は呼び出せない」という意味です。このエラーが出たら、まずデコレーターの return を確認します。
2. wrapper の中で戻り値を return し忘れる
wrapper の中で func(*args, **kwargs) と呼ぶだけで return を付けないと、エラーは出ずに戻り値が黙って None になります。log_call をこの形で書いて print(add(2, 3)) を実行すると、5 ではなく None と表示されました。エラーにならない分、気づきにくい間違いです。
3. かっこの付け忘れ・付けすぎ
引数付きの repeat に @repeat とかっこなしで付けると、hello が times に渡され、hello という名前には decorator が入ります。エラーは出ず、hello("Python") を呼んでも何も表示されません(中の関数を返すだけなので)。print(hello("Python")) とすると、次のように関数が返っていることが分かります。
<function repeat.<locals>.decorator.<locals>.wrapper at 0x00000254035F7880>
逆に、引数のない shout に @shout() とかっこを付けると、定義した時点で TypeError: shout() missing 1 required positional argument: 'func' になります。そのデコレーターが引数を取るか(2 段か 3 段か)を確認してください。なお標準の lru_cache は 3.8 から、かっこなし・かっこ付きの両方に対応しています。
4. 再帰関数に付けると何度も動く
関数の中で自分自身を呼ぶ再帰関数では、中の呼び出しも名前経由なので wrapper を通ります。timer を階乗の関数 fact に付けて fact(3) を呼ぶと、時間の表示が fact(1)・fact(2)・fact(3) の 3 回出ました。全体の時間だけを測るなら、再帰する関数を呼ぶ関数を別に作ってそちらに付けます(fib の cache は逆にこの性質で中の呼び出しもキャッシュされます)。
5. lru_cache・cache にリストや辞書を渡す
キャッシュは辞書で結果を覚えるため、引数はハッシュ可能(変更できない値)である必要があります。@functools.cache を付けた関数に (1, 2, 3)(タプル)を渡すと動きますが、[1, 2, 3](リスト)を渡すと TypeError: unhashable type: 'list' になりました。リストはタプルに変換してから渡します。
よくある質問
デコレーターを付けた関数の、元の関数を呼びたいときは?
デコレーターが functools.wraps を使っていれば、関数名.__wrapped__ で元の関数を取り出せます。lru_cache・cache も同じ仕組みで __wrapped__ を持つので、テストでキャッシュを通さずに呼びたいときなどに使えます。
自分でデコレーターを書くべき場面は?
ログ出力・時間計測・権限チェック・リトライなど、「いろいろな関数の前後に同じ処理を足したい」ときです。1 つの関数でしか使わない処理なら、関数の中に書いたほうが読みやすくなります。
まとめ
- デコレーターは「関数を受け取って関数を返す関数」。
@decoはfunc = deco(func)の書き換え - wrapper は
*args, **kwargsで受けて中継し、戻り値を return する。@functools.wraps(func)を必ず付ける - 引数付きは 3 段の入れ子。重ねたときは下から包み、上ほど外側
- cache・lru_cache・property・staticmethod・classmethod は標準で使える
関連する記事・ツール
- Pythonの例外処理入門|try・except・finally・raiseの使い方
- Pythonのdataclassの使い方|既定値・frozen・asdictを実例で解説
- Pythonのloggingの使い方|printから卒業するログ出力の基本と設定例
- Pythonの型ヒント入門|typingの書き方とmypyで型の間違いを見つける方法
- Pythonのitertools入門|groupby・batchedでループを短く書く