typing.overload デコレータを使うと、引数の型によって戻り値の型が変わる関数のオーバーロードを型ヒントで表現できます。
問題の背景
引数の型によって戻り値の型が異なる関数があります。
def process(value): if isinstance(value, int): return value * 2 # int を返す elif isinstance(value, str): return value.upper() # str を返す
単純な型ヒントでは、この関係を正確に表現できません。
overload の使い方
overload デコレータで複数のシグネチャを定義し、最後に実装を書きます。
from typing import overload @overload def process(value: int) -> int: ... @overload def process(value: str) -> str: ... def process(value: int | str) -> int | str: if isinstance(value, int): return value * 2 else: return value.upper()
overload で装飾された関数はスタブであり、実行されません。型チェッカーだけが参照します。実際の実装は最後の関数で行います。
型チェッカーの動作
x = process(10) # 型チェッカーは x を int と推論 y = process("hello") # 型チェッカーは y を str と推論
overload を使わない場合、戻り値は int | str と推論され、どちらの型かが曖昧になります。
注意点
overload は型チェック専用で、実行時には効果がない
最後の実装関数には overload を付けない
オーバーロードの順序は特殊なものを先に書く
overload を活用すると、複雑な関数でも呼び出し側で正確な型推論が得られます。
