Python
PR

Pythonのデコレーター入門|@の仕組みとfunctools.wrapsを実例で解説

Pythonのデコレーター入門|@の仕組みとfunctools.wrapsを実例で解説
hr
記事内に商品プロモーションを含む場合があります

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("田中"))
こんにちは、田中さん!!
@shout を付けた greet の定義は、greet を定義してから greet = shout(greet) と書くのと同じ。shout は元の greet を受け取り、元の greet を中に持つ新しい関数 wrapper を返す。以後、名前 greet を呼ぶと wrapper が動き、結果に感嘆符を足して返す
図 1:@shout は greet = shout(greet) と同じ。名前 greet は wrapper を指すようになる

公式ドキュメントの「関数定義」の節では、デコレーターの式は関数が定義されたときに評価され、その結果(呼び出せるもの)が関数オブジェクトを唯一の引数として呼ばれ、戻り値が関数名に結び付けられる、と説明されています。ポイントは「定義したとき」に動くことです。次のコードで確かめます。

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>
上から @bold、@italic の順に付けた text は text = bold(italic(text)) と同じ。まず italic の wrapper が元の text を包み、その外側を bold の wrapper が包む。呼ぶと外側から順に処理され、結果は b タグの中に i タグが入った hello になる
図 2:重ねたデコレーターは下から順に包み、上のものほど外側になる

包むのは下の 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 は標準で使える

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました