@overload

@overload デコレータは、引数の型の異なる複数の組み合わせをサポートする関数やメソッドを記述することを可能にします。 このパターンは、組み込みモジュールや型で頻繁に使用されます。 例えば、bytes 型の __getitem__() メソッドは次のように記述できます:

from typing import overload

class bytes:
    ...
    @overload
    def __getitem__(self, i: int) -> int: ...
    @overload
    def __getitem__(self, s: slice) -> bytes: ...

この記述は、引数と戻り値の型の関係を表現できないユニオンを使用するよりも正確です:

class bytes:
    ...
    def __getitem__(self, a: int | slice) -> int | bytes: ...

@overload が便利なもう一つの例は、呼び出し可能なオブジェクトの型に応じて異なる数の引数を取る組み込みの map() 関数の型です:

from typing import TypeVar, overload
from collections.abc import Callable, Iterable, Iterator

T1 = TypeVar('T1')
T2 = TypeVar('T2')
S = TypeVar('S')

@overload
def map(func: Callable[[T1], S], iter1: Iterable[T1]) -> Iterator[S]: ...
@overload
def map(func: Callable[[T1, T2], S],
        iter1: Iterable[T1], iter2: Iterable[T2]) -> Iterator[S]: ...
# ... and we could add more items to support more than two iterables

次のようにして map(None, ...) をサポートする項目を簡単に追加することもできます:

@overload
def map(func: None, iter1: Iterable[T1]) -> Iterable[T1]: ...
@overload
def map(func: None,
        iter1: Iterable[T1],
        iter2: Iterable[T2]) -> Iterable[tuple[T1, T2]]: ...

上記のように使用される @overload デコレータは、スタブファイルに適しています。 通常のモジュールでは、一連の @overload デコレータが付けられた定義の後には、必ず1つの @overload デコレータが付けられていない定義（同じ関数/メソッドのため）が続かなければなりません。 @overload デコレータが付けられた定義は型チェッカーのためだけのものであり、非 @overload デコレータが付けられた定義によって上書きされます。後者は実行時に使用されますが、型チェッカーによって無視されるべきです。 実行時に @overload デコレータが付けられた関数を直接呼び出すと NotImplementedError が発生します。 ここに、ユニオンや型変数を使用して簡単に表現できない非スタブのオーバーロードの例があります:

@overload
def utf8(value: None) -> None:
    pass
@overload
def utf8(value: bytes) -> bytes:
    pass
@overload
def utf8(value: unicode) -> bytes:
    pass
def utf8(value):
    <actual implementation>

制約された TypeVar 型は、@overload デコレータを使用する代わりに使用されることがよくあります。 例えば、このスタブファイルの concat1 と concat2 の定義は同等です:

from typing import TypeVar

AnyStr = TypeVar('AnyStr', str, bytes)

def concat1(x: AnyStr, y: AnyStr) -> AnyStr: ...

@overload
def concat2(x: str, y: str) -> str: ...
@overload
def concat2(x: bytes, y: bytes) -> bytes: ...

上記の map や bytes.__getitem__ のように、型変数を使用して正確に表現できない関数もあります。 型変数が十分でない場合にのみ @overload を使用することをお勧めします。

AnyStr のような型変数と @overload を使用することのもう一つの重要な違いは、前者はジェネリッククラスの型パラメータの制約を定義するためにも使用できることです。 例えば、ジェネリッククラス typing.IO の型パラメータは制約されています（IO[str]、IO[bytes]、IO[Any] のみが有効です）:

class IO(Generic[AnyStr]): ...