`typing` --- 型ヒントのサポート¶

Added in version 3.5.

ソースコード: Lib/typing.py

注釈

Python ランタイムは、関数や変数の型アノテーションを強制しません。型アノテーションは、 type checkers や IDE、linterなどのサードパーティーツールで使われます。

このモジュールは型ヒントの実行時サポートを提供します。

以下の関数を例に考えてみます:

def surface_area_of_cube(edge_length: float) -> str:
    return f"The surface area of the cube is {6 * edge_length ** 2}."

surface_area_of_cube 関数は、edge_length: float という type hint で示されているように、引数が float のインスタンスであるという前提です。そして、-> str というヒントにある通り、この関数は str のインスタンスを返すことになっています。

型ヒントは float や str のような単純な型を指定することもできますし、もっと複雑な型も指定できます。 typing モジュールには、より高度な型ヒントを表現するためのいろいろな型が含まれています。

typing モジュールには新しい機能が頻繁に追加されます。 typing_extensions パッケージを使うことで、古い Python バージョンからもその新機能を使うことができます。

参考

Typing cheat sheet: 型ヒントの簡単な概要 (mypy ドキュメンテーション)
Type System Reference section of the mypy docs: Python の型システムの規格は PEP によって定められているので、このレファレンスはほとんどの Python 型チェッカーに適用できるはずです。(mypy のみに適用される部分もあるかもしれません。)
Static Typing with Python: コミュニティーによって書かれた、型システムの機能や便利な型関連のツール、型に関するベストプラクティスを詳しく説明している、特定の型チェッカーに依らないドキュメンテーション。

Python 型システムの仕様¶

The canonical, up-to-date specification of the Python type system can be found at Specification for the Python type system.

型エイリアス¶

型エイリアスは type 文を用いて定義され、これにより TypeAliasType インスタンスが生成されます。以下の例では、 Vector と list[float] は静的型チェッカーによって同じ型とみなされます:

type Vector = list[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

# floatのlistはVectorとして要件を満たすため、型チェックを通過する。
new_vector = scale(2.0, [1.0, -4.2, 5.4])

型エイリアスは複雑な型シグネチャを単純化するのに有用です。例えば:

from collections.abc import Sequence

type ConnectionOptions = dict[str, str]
type Address = tuple[str, int]
type Server = tuple[Address, ConnectionOptions]

def broadcast_message(message: str, servers: Sequence[Server]) -> None:
    ...

# 静的型チェッカーでは、上記の型アノテーションと
# 以下のアノテーションを同等のものとして扱う。
def broadcast_message(
    message: str,
    servers: Sequence[tuple[tuple[str, int], dict[str, str]]]
) -> None:
    ...

type 文はPython 3.12で新しく導入されました。後方互換性のために、単に代入によって型エイリアスを作成することもできます。

Vector = list[float]

あるいは、 TypeAlias でマークすることで、これが通常の変数代入ではなく、型エイリアスであることを明示できます。

from typing import TypeAlias

Vector: TypeAlias = list[float]

NewType¶

異なる型を作るためには NewType ヘルパークラスを使います:

from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

静的型チェッカーは新しい型を元々の型のサブクラスのように扱います。この振る舞いは論理的な誤りを見つける手助けとして役に立ちます。

def get_user_name(user_id: UserId) -> str:
    ...

# 型チェックを通過する
user_a = get_user_name(UserId(42351))

# 型チェックに失敗する。int型はUserId型ではないため。
user_b = get_user_name(-1)

UserId 型の変数も int の全ての演算が行えますが、その結果は常に int 型になります。この振る舞いにより、 int が期待されるところに UserId を渡せますが、不正な方法で UserId を作ってしまうことを防ぎます。

# 'output' は'int'型となる。'UserId'型にはならない。
output = UserId(23413) + UserId(54341)

これらのチェックは静的型チェッカーだけが行うことに注意してください。実行時に Derived = NewType('Derived', Base) を実行すると、渡した引数をそのまま返す呼び出し可能オブジェクト Derived が作成されます。つまり、Derived(some_value) という式は新しいクラスを作成せず、通常の関数呼び出しと比べても大きなオーバーヘッドは生じません。

より正確に言うと、式 some_value is Derived(some_value) は実行時に常に真を返します。

Derived のサブタイプを作成することはできません。

from typing import NewType

UserId = NewType('UserId', int)

# 実行時にエラーとなり、型チェックも通らない
class AdminUserId(UserId): pass

しかし、 'derived' である NewType をもとにした NewType は作ることが出来ます:

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

そして ProUserId に対する型検査は期待通りに動作します。

より詳しくは PEP 484 を参照してください。

注釈

先述の通り、型エイリアスは、2つの型が互いに等価であることを宣言します。 type Alias = Original とすると、静的型チェッカーは Alias を Original と"完全に等価な"ものとして扱います。これは、複雑な型シグネチャを単純化したい場合に便利です。

これに対し、 NewType はある型をもう一方の型の サブタイプ として宣言します。 Derived = NewType('Derived', Original) とすると静的型チェッカーは Derived を Original の サブクラス として扱います。つまり Original 型の値は Derived 型の値が期待される場所で使うことが出来ないということです。これにより、実行パフォーマンスをほとんど犠牲にせずに論理エラーを防ぐことができます。

Added in version 3.5.2.

バージョン 3.10 で変更: NewType は関数ではなくクラスになりました。その結果、通常の関数よりも NewType を呼び出す際に多少の実行時コストが追加されます。

バージョン 3.11 で変更: NewType 呼び出し時のパフォーマンスが Python 3.9 のレベルに戻りました

呼び出し可能オブジェクトのアノテーション¶

関数や他の呼び出し可能オブジェクトには、collections.abc.Callable または非推奨の typing.Callable を使ってアノテーションできます。 Callable[[int], str] は、int 型の引数を 1 つ取り、str を返す関数を表します。

例えば:

from collections.abc import Callable, Awaitable

def feeder(get_next_item: Callable[[], str]) -> None:
    ...  # Body

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    ...  # Body

async def on_update(value: str) -> None:
    ...  # Body

callback: Callable[[str], Awaitable[None]] = on_update

The subscription syntax must always be used with exactly two values: the argument list and the return type. The argument list must be a list of types, a ParamSpec, Concatenate, or an ellipsis (...). The return type must be a single type.

もしellipsisリテラル ... が引数リストとして与えられた場合、それは任意のパラメータリストを持つ呼び出し可能オブジェクトを受け入れることを示します。

def concat(x: str, y: str) -> str:
    return x + y

x: Callable[..., str]
x = str     # OK
x = concat  # これもOK

Callable は可変引数、オーバーロード関数、キーワード専用引数などを含む複雑な型シグネチャを表現することはできません。しかし、Protocol クラスとその __call__() メソッドを定義すれば表現することができます:

from collections.abc import Iterable
from typing import Protocol

class Combiner(Protocol):
    def __call__(self, *vals: bytes, maxlen: int | None = None) -> list[bytes]: ...

def batch_proc(data: Iterable[bytes], cb_results: Combiner) -> bytes:
    for item in data:
        ...

def good_cb(*vals: bytes, maxlen: int | None = None) -> list[bytes]:
    ...
def bad_cb(*vals: bytes, maxitems: int | None) -> list[bytes]:
    ...

batch_proc([], good_cb)  # OK
batch_proc([], bad_cb)   # エラー! コールバックのパラメータ名と種類が異なるため、
                         # 第2引数の型が適合しない

他の呼び出し可能オブジェクトを引数に取る呼び出し可能オブジェクトでは、ParamSpec を使って、それらのパラメータの型が互いに依存することを示せます。さらに、受け取った呼び出し可能オブジェクトの引数を追加または削除する場合は、Concatenate 演算子を使えます。それぞれ Callable[ParamSpecVariable, ReturnType] と Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType] の形式を取ります。

バージョン 3.10 で変更: Callable は ParamSpec と Concatenate をサポートしました。詳細は PEP 612 を参照してください。

参考

ParamSpec と Concatenate のドキュメントに、Callable での使用例が記載されています。

ジェネリクス¶

コンテナに含まれるオブジェクトに関する型情報は、一般的な方法で静的に推論することができないため、標準ライブラリの多くのコンテナクラスは、要素に期待する型を示す添字表記をサポートしています

from collections.abc import Mapping, Sequence

class Employee: ...

# Sequence[Employee] はシーケンスの要素がすべて "Employee" の
# インスタンスでなければならないということを表します。
# Mapping[str, str] は mapping に含まれるキーとバリューが
# すべて文字列である必要があることを表します。
def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

ジェネリック関数およびクラスは以下の通り、型引数構文を使うことでパラメータ化できます:

from collections.abc import Sequence

def first[T](l: Sequence[T]) -> T:  # この関数は型変数 "T" に関してジェネリックです
    return l[0]

もしくは、 TypeVar のコンストラクタを使うこともできます:

from collections.abc import Sequence
from typing import TypeVar

U = TypeVar('U')                  # 型引数 "U" を宣言

def second(l: Sequence[U]) -> U:  # 型引数 "U" に関してジェネリックな関数
    return l[1]

バージョン 3.12 で変更: ジェネリックが構文としてサポートされたのは Python 3.12 が初めてです。

タプルのアノテーション¶

Python のコンテナのほとんどは、すべての要素が同じ型であると型システムが想定するようになっています。例えば:

from collections.abc import Mapping

# ``x`` の要素がすべて int であると型チェッカーが推定する
x: list[int] = []

# 型チェッカーエラー： ``list`` は一つの引数しか受け付けない
y: list[int, str] = [1, 'foo']

# ``z`` のキーはすべて文字列であり、バリューは文字列か int のどちらか
# であると型チェッカーが推定する
z: Mapping[str, str | int] = {}

list は引数に1つの型のみ受け入れるので、型チェッカーは上記の y への代入でエラーを出力します。同様に、Mapping は引数に2つの型のみ受け入れます。1つ目はキーの型を示し、2つ目は値の型を示します。

しかし、他の多くのPythonのコンテナとは異なり、タプルがすべて同じ型ではない要素を持つことは、慣用的なPythonコードでは一般的です。このため、タプルはPythonの型システムの中でも特殊です。 tuple は任意の数の型引数を受け入れます。

# OK: ``x`` に代入されるのは長さ1のタプルで、要素は int
x: tuple[int] = (5,)

# OK: ``y`` に代入されるのは長さ2のタプルで、
# 第１要素は int、第２要素は文字列
y: tuple[int, str] = (5, "foo")

# エラー: 型アノテーションでは長さ1のタプルとなっているが、
# ``z`` には長さ3のタプルが代入されている
z: tuple[int] = (1, 2, 3)

To denote a tuple which could be of any length, and in which all elements are of the same type T, use the literal ellipsis ...: tuple[T, ...]. To denote an empty tuple, use tuple[()]. Using plain tuple as an annotation is equivalent to using tuple[Any, ...]:

x: tuple[int, ...] = (1, 2)
# 以下の再代入は OK: ``tuple[int, ...]`` は x の長さが任意であることを表す
x = (1, 2, 3)
x = ()
# 以下の再代入はエラー: ``x`` のすべての要素が int である必要がある
x = ("foo", "bar")

# ``y`` に代入できるのは空のタプルのみ
y: tuple[()] = ()

z: tuple = ("foo", "bar")
# 以下の再代入は OK: ``tuple`` は ``tuple[Any, ...]`` と等価
z = (1, 2, 3)
z = ()

クラスオブジェクトの型¶

C でアノテーションされた変数には、C 型の値を代入できます。一方、type[C] (または非推奨の typing.Type[C]) でアノテーションされた変数には、クラス自体を値として代入できます。具体的には、C の クラスオブジェクト を受け入れます。例えば次のようになります。

a = 3         # 型は ``int``
b = int       # 型は ``type[int]``
c = type(a)   # これも型は ``type[int]``

type[C] は共変であることに注意してください。

class User: ...
class ProUser(User): ...
class TeamUser(User): ...

def make_new_user(user_class: type[User]) -> User:
    # ...
    return user_class()

make_new_user(User)      # OK
make_new_user(ProUser)   # これも OK: ``type[ProUser]`` は ``type[User]`` のサブタイプ
make_new_user(TeamUser)  # これも問題ない
make_new_user(User())    # エラー: ``type[User]`` が必要だが ``User`` が渡された
make_new_user(int)       # エラー: ``type[int]`` は ``type[User]`` のサブタイプではない

type の型引数として指定できるのは、クラス、Any、型変数、およびこれらの型のユニオンだけです。例えば次のようになります。

def new_non_team_user(user_class: type[BasicUser | ProUser]): ...

new_non_team_user(BasicUser)  # OK
new_non_team_user(ProUser)    # OK
new_non_team_user(TeamUser)   # Error: ``type[TeamUser]`` is not a subtype
                              # of ``type[BasicUser | ProUser]``
new_non_team_user(User)       # Also an error

type[Any] は type と同じで、Python のメタクラス階層の根に当たります。

ジェネレータとコルーチンのアノテーション¶

ジェネレータには、ジェネリック型 Generator[YieldType, SendType, ReturnType] を使ってアノテーションできます。例えば次のようになります。

def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

標準ライブラリの他の多くのジェネリッククラスとは異なり、Generator の SendType は共変や不変ではなく、反変であることに注意してください。

SendType と ReturnType のデフォルトは None です。

def infinite_stream(start: int) -> Generator[int]:
    while True:
        yield start
        start += 1

これらの型を明示的に設定することもできます。

def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1

値を yield するだけの単純なジェネレータでは、戻り値の型を Iterable[YieldType] または Iterator[YieldType] としてアノテーションすることもできます。

def infinite_stream(start: int) -> Iterator[int]:
    while True:
        yield start
        start += 1

非同期ジェネレータも同じように扱えますが、型引数 ReturnType は受け取りません (AsyncGenerator[YieldType, SendType])。 SendType のデフォルトは None なので、以下の定義は同じ意味です。

async def infinite_stream(start: int) -> AsyncGenerator[int]:
    while True:
        yield start
        start = await increment(start)

async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
    while True:
        yield start
        start = await increment(start)

同期ジェネレータの場合と同じように、AsyncIterable[YieldType] と AsyncIterator[YieldType] も使用できます。

async def infinite_stream(start: int) -> AsyncIterator[int]:
    while True:
        yield start
        start = await increment(start)

コルーチンには Coroutine[YieldType, SendType, ReturnType] を使ってアノテーションできます。型引数は Generator の型引数に対応します。例えば次のようになります。

from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # 別の場所で定義されたコルーチン
x = c.send('hi')                   # 'x' の推論された型は list[str]
async def bar() -> None:
    y = await c                    # 'y' の推論された型は int

ユーザー定義のジェネリック型¶

ユーザー定義のクラスを、ジェネリッククラスとして定義できます。

from logging import Logger

class LoggedVar[T]:
    def __init__(self, value: T, name: str, logger: Logger) -> None:
        self.name = name
        self.logger = logger
        self.value = value

    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = new

    def get(self) -> T:
        self.log('Get ' + repr(self.value))
        return self.value

    def log(self, message: str) -> None:
        self.logger.info('%s: %s', self.name, message)

この構文は、クラス LoggedVar が単一の型変数 T でパラメータ化されていることを示します。また、クラス本体で T を型として使用できるようになります。

ジェネリッククラスは暗黙的に Generic を継承します。 Python 3.11 以前との互換性のために、Generic を明示的に継承してジェネリッククラスであることを示す方法も使えます。

from typing import TypeVar, Generic

T = TypeVar('T')

class LoggedVar(Generic[T]):
    ...

ジェネリッククラスは __class_getitem__() メソッドを持つため、実行時にパラメータ化できます (下の LoggedVar[int] など)。

from collections.abc import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)

ジェネリック型は任意の数の型変数を持てます。どの種類の TypeVar も、ジェネリック型の型引数として使用できます。

from typing import TypeVar, Generic, Sequence

class WeirdTrio[T, B: Sequence[bytes], S: (int, str)]:
    ...

OldT = TypeVar('OldT', contravariant=True)
OldB = TypeVar('OldB', bound=Sequence[bytes], covariant=True)
OldS = TypeVar('OldS', int, str)

class OldWeirdTrio(Generic[OldT, OldB, OldS]):
    ...

Generic の引数のそれぞれの型変数は別のものでなければなりません。このため次のクラス定義は無効です:

from typing import TypeVar, Generic
...

class Pair[M, M]:  # SyntaxError
    ...

T = TypeVar('T')

class Pair(Generic[T, T]):   # 無効
    ...

ジェネリッククラスは他のクラスを継承することもできます。

from collections.abc import Sized

class LinkedList[T](Sized):
    ...

ジェネリッククラスを継承するときに、一部の型引数を固定することもできます。

from collections.abc import Mapping

class MyDict[T](Mapping[str, T]):
    ...

この場合では MyDict は仮引数 T を 1 つとります。

型引数を指定せずにジェネリッククラスを使うと、各位置に Any を指定したものとして扱われます。以下の例の MyIterable はジェネリックではなく、暗黙的に Iterable[Any] を継承します:

from collections.abc import Iterable

class MyIterable(Iterable): # Iterable[Any] と同じ
    ...

ユーザー定義のジェネリック型エイリアスにも対応しています。例を示します。

from collections.abc import Iterable

type Response[S] = Iterable[S] | int

# ここの戻り値の型は Iterable[str] | int と同じ
def response(query: str) -> Response[str]:
    ...

type Vec[T] = Iterable[tuple[T, T]]

def inproduct[T: (int, float, complex)](v: Vec[T]) -> T: # Iterable[tuple[T, T]] と同じ
    return sum(x*y for x, y in v)

後方互換性のために、ジェネリック型エイリアスは単純な代入でも作成できます。

from collections.abc import Iterable
from typing import TypeVar

S = TypeVar("S")
Response = Iterable[S] | int

バージョン 3.7 で変更: Generic にあった独自のメタクラスは無くなりました。

バージョン 3.12 で変更: ジェネリックと型エイリアスの構文はバージョン 3.12 で導入されました。それ以前のジェネリッククラスは、Generic を明示的に継承するか、基底クラスのいずれかに型変数を含める必要がありました。

[**P] 形式のパラメータ仕様変数を使い、パラメータ式を受け取るユーザー定義のジェネリックを作成することもできます。 typing モジュールはパラメータ仕様変数を特別な型変数として扱うため、上で説明した型変数と同じように動作します。ただし例外として、ParamSpec には型のリストを代入できます。

>>> class Z[T, **P]: ...  # T は TypeVar、P は ParamSpec
...
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]

Generic を明示的に継承して、ParamSpec を引数とするジェネリッククラスを作成することもできます。この場合は ** を使いません。

from typing import ParamSpec, Generic

P = ParamSpec('P')

class Z(Generic[P]):
    ...

TypeVar と ParamSpec のもう 1 つの違いとして、パラメータ仕様変数が 1 つだけのジェネリックでは、見た目を簡潔にするため、パラメータリストを X[[Type1, Type2, ...]] と X[Type1, Type2, ...] のどちらの形式でも指定できます。内部では後者を前者に変換するため、以下は同じ意味です。

>>> class X[**P]: ...
...
>>> X[int, str]
__main__.X[[int, str]]
>>> X[[int, str]]
__main__.X[[int, str]]

ParamSpec を使うジェネリックは、主に静的型チェックを目的としているため、代入後に正しい __parameters__ を持たない場合があります。

バージョン 3.10 で変更: Generic をパラメータ式でパラメータ化できるようになりました。詳細は ParamSpec と PEP 612 を参照してください。

ユーザー定義のジェネリッククラスは、メタクラスの衝突を起こさずに抽象基底クラス (ABC) を基底クラスにできます。ジェネリックなメタクラスには対応していません。ジェネリックをパラメータ化した結果はキャッシュされます。 typing モジュールのほとんどの型はハッシュ可能で、等価比較もできます。

`Any` 型¶

A special kind of type is Any. A static type checker will treat every type as assignable to Any and Any as assignable to every type.

これは、Any 型の値に対して任意の演算やメソッド呼び出しを行え、どの変数にも代入できることを意味します。

from typing import Any

a: Any = None
a = []          # OK
a = 2           # OK

s: str = ''
s = a           # OK

def foo(item: Any) -> int:
    # 型チェックを通過する。
    # 'item' はどの型でもよく、
    # その型には 'bar' メソッドがあるかもしれない
    item.bar()
    ...

Any 型の値をより詳細な型に代入する時に型検査が行われないことに注意してください。例えば、静的型検査器は a を s に代入する時、s が str 型として宣言されていて実行時に int の値を受け取るとしても、エラーを報告しません。

さらに、戻り値や引数に型アノテーションのない関数は、暗黙的に Any を使います。

def legacy_parser(text):
    ...
    return data

# 静的型チェッカーは上記のシグネチャを
# 次のものと同じように扱う:
def legacy_parser(text: Any) -> Any:
    ...
    return data

この挙動により、動的型付けと静的型付けが混在したコードを書かなければならない時に Any を 非常口 として使用することができます。

Any の挙動と object の挙動を対比しましょう。 Any と同様に、すべての型は object のサブタイプです。しかしながら、 Any と異なり、逆は成り立ちません: object はすべての他の型のサブタイプでは ありません。

これは、ある値の型が object のとき、型検査器はこれについてのほとんどすべての操作を拒否し、これをより特殊化された変数に代入する (または返り値として利用する) ことは型エラーになることを意味します。例えば:

def hash_a(item: object) -> int:
    # Fails type checking; an object does not have a 'magic' method.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Passes type checking
    item.magic()
    ...

# Passes type checking, since ints and strs are subclasses of object
hash_a(42)
hash_a("foo")

# Passes type checking, since Any is assignable to all types
hash_b(42)
hash_b("foo")

値がどの型でもよいことを型安全に表すには object を使います。値が動的に型付けされることを示すには Any を使います。

名前的部分型 vs 構造的部分型¶

初めは PEP 484 は Python の静的型システムを 名前的部分型 を使って定義していました。名前的部分型とは、クラス B が期待されているところにクラス A が許容されるのは A が B のサブクラスの場合かつその場合に限る、ということです。

この要件は以前、Iterable などの抽象基底クラスにも適用されていました。この方法では、抽象基底クラスに対応していることをクラスに明示する必要がある点が問題です。これは Python らしくなく、慣用的な動的型付けの Python コードで通常行うこととも異なります。例えば、次のコードは PEP 484 に従っています。

from collections.abc import Sized, Iterable, Iterator

class Bucket(Sized, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

PEP 544 solves this problem by allowing users to write the above code without explicit base classes in the class definition, allowing Bucket to be implicitly considered a subtype of both Sized and Iterable[int] by static type checkers. This is known as structural subtyping (or static duck-typing):

from collections.abc import Iterator, Iterable

class Bucket:  # 注意: 基底クラスの指定はない
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # 型チェックを通過する

さらに、特別なクラス Protocol のサブクラスを作ることで、新しい独自のプロトコルを作って構造的部分型というものを満喫できます。

モジュールの内容¶

typing モジュールは以下のクラス、関数、デコレータを定義します。

特殊型付けプリミティブ¶

特殊型¶

アノテーション内で型として使用できます。 [] を使った添字表記には対応していません。

typing.Any¶

制約のない型であることを示す特別な型です。

Every type is assignable to Any.
Any is assignable to every type.

バージョン 3.11 で変更: Any を基底クラスとして使えるようになりました。あらゆる場面でダックタイピングに対応するクラスや、非常に動的なクラスで型チェッカーのエラーを避けるのに役立ちます。

typing.AnyStr¶

制約付き型変数です。

定義は次のとおりです。

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

AnyStr は、引数として str または bytes を受け取れるものの、両者の混在は許さない関数で使うためのものです。

例えば:

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b

concat("foo", "bar")    # OK、戻り値の型は 'str'
concat(b"foo", b"bar")  # OK、戻り値の型は 'bytes'
concat("foo", b"bar")   # エラー、str と bytes は混在できない

名前から連想されるかもしれませんが、AnyStr は Any 型とは無関係で、「任意の文字列」という意味でもありません。特に、AnyStr と str | bytes は異なるもので、用途も異なります。

# AnyStr の無効な使い方:
# 型変数が関数のシグネチャに 1 回しか現れないため、
# 型チェッカーが型を「解決」できない
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

# この関数のより適切なアノテーション:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"

Deprecated since version 3.13, will be removed in version 3.18: 新しい型引数構文に置き換えられ、非推奨となりました。 AnyStr をインポートする代わりに class A[T: (str, bytes)]: ... を使ってください。詳細は PEP 695 を参照してください。

Python 3.16 では AnyStr が typing.__all__ から削除され、typing からのアクセスやインポート時に実行時の非推奨警告が発生するようになります。 Python 3.18 では AnyStr が typing から削除されます。

typing.LiteralString¶

リテラル文字列だけを含む特殊な型です。

どの文字列リテラルも、また他の LiteralString も、LiteralString と互換性があります。ただし、単に str 型とされたオブジェクトには互換性がありません。 LiteralString 型のオブジェクトを組み合わせて作った文字列も、LiteralString として受け入れられます。

例:

def run_query(sql: LiteralString) -> None:
    ...

def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
    run_query("SELECT * FROM students")  # OK
    run_query(literal_string)  # OK
    run_query("SELECT * FROM " + literal_string)  # OK
    run_query(arbitrary_string)  # 型チェッカーのエラー
    run_query(  # 型チェッカーのエラー
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

LiteralString は、ユーザーが生成した任意の文字列を渡すと問題が生じる可能性のある、注意を要する API で役立ちます。例えば、上の型チェッカーのエラーになる 2 つのケースには、SQL インジェクション攻撃に対する脆弱性があるかもしれません。

より詳しくは PEP 675 を参照してください。

Added in version 3.11.

typing.Never¶

typing.NoReturn¶

Never と NoReturn は、値を 1 つも持たない型であるボトム型を表します。

sys.exit() のように、関数が決して戻らないことを示すために使えます。

from typing import Never  # または NoReturn

def stop() -> Never:
    raise RuntimeError('no way')

また、assert_never() のように、有効な引数が存在しないため決して呼び出されるべきでない関数を定義するためにも使えます。

from typing import Never  # または NoReturn

def never_call_me(arg: Never) -> None:
    pass

def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # 型チェッカーのエラー
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _:
            never_call_me(arg)  # OK、arg の型は Never (または NoReturn)

Never と NoReturn は型システム上で同じ意味を持ち、静的型チェッカーは両者を同じように扱います。

Added in version 3.6.2: NoReturn を追加しました。

Added in version 3.11: Never を追加しました。

typing.Self¶

それを囲む現在のクラスを表す特殊な型です。

例えば:

from typing import Self, reveal_type

class Foo:
    def return_self(self) -> Self:
        ...
        return self

class SubclassOfFoo(Foo): pass

reveal_type(Foo().return_self())  # 表示される型は "Foo"
reveal_type(SubclassOfFoo().return_self())  # 表示される型は "SubclassOfFoo"

このアノテーションは、以下の書き方と同じ意味をより簡潔に表したものです。

from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self

一般に、上の例のように self を返す場合は、戻り値のアノテーションに Self を使うべきです。 Foo.return_self の戻り値を "Foo" とアノテーションすると、型チェッカーは SubclassOfFoo.return_self の戻り値の型を SubclassOfFoo ではなく Foo と推論します。

他によくある用途として、以下があります:

代替コンストラクタとして使われ、cls 引数のインスタンスを返す classmethod。
self を返す __enter__() メソッドのアノテーション。

クラスを継承したときに、メソッドがそのサブクラスのインスタンスを返す保証がなければ、戻り値のアノテーションに Self を使うべきではありません。

class Eggs:
    # サブクラスでも常に Eggs のインスタンスを返すため、
    # ここの戻り値のアノテーションに Self を使うのは
    # 誤りになる
    def returns_eggs(self) -> "Eggs":
        return Eggs()

より詳しくは PEP 673 を参照してください。

Added in version 3.11.

typing.TypeAlias¶

型エイリアスを明示的に宣言するための特殊なアノテーションです。

例えば:

from typing import TypeAlias

Factors: TypeAlias = list[int]

古いバージョンの Python では、型チェッカーが前方参照を使うエイリアスと通常の変数代入を区別しにくい場合があります。そのようなエイリアスのアノテーションには TypeAlias が特に役立ちます:

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Box" はまだ存在しないため、Python 3.12 未満では
# 前方参照をクォートで囲む必要がある。
# ``TypeAlias`` により、文字列を変数に代入するのではなく
# 型エイリアスを宣言していることが型チェッカーに伝わる。
BoxOfStrings: TypeAlias = "Box[str]"

class Box(Generic[T]):
    @classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...

より詳しくは、 PEP 613 をご覧ください。

Added in version 3.10.

バージョン 3.12 で非推奨: TypeAlias は非推奨です。代わりに、TypeAliasType のインスタンスを作成し、前方参照に直接対応している type 文を使ってください。 TypeAlias と TypeAliasType は用途や名前が似ていますが、別のものであり、後者は前者の型ではありません。現時点では TypeAlias の削除予定はありませんが、type 文への移行が推奨されます。

特殊形式¶

これらはアノテーションの型として使用できます。これらは全て [] を使用した添字表記をサポートしますが、それぞれ固有の構文があります。

typing.Union¶

ユニオン型; Union[X, Y] は X | Y と等価で X または Y を表します。

ユニオンを定義するには、例えば Union[int, str] または省略形の int | str を使います。省略形の使用を推奨します。詳細は次のとおりです:

引数は型でなければならず、少なくとも一つ必要です。
ユニオン型のユニオン型は平滑化されます。例えば:
```
Union[Union[int, str], float] == Union[int, str, float]
```
ただし、型エイリアスを介して参照されるユニオンにはこの処理は適用されません。元の TypeAliasType を強制的に評価することを避けるためです。
```
type A = Union[int, str]
Union[A, float] != Union[int, str, float]
```

引数が一つのユニオン型は消えます。例えば:

Union[int] == int  # コンストラクタは実際に int を返す

冗長な実引数は飛ばされます。例えば:

Union[int, str, int] == Union[int, str] == int | str

ユニオン型を比較するとき引数の順序は無視されます。例えば:
```
Union[int, str] == Union[str, int]
```
Union のサブクラスを作成したり、インスタンスを作成することは出来ません。
Union[X][Y] と書くことは出来ません。

バージョン 3.7 で変更: 明示的に書かれているサブクラスを、実行時に直和型から取り除かなくなりました。

バージョン 3.10 で変更: ユニオン型は X | Y のように書けるようになりました。 union型の表現を参照ください。

typing.Optional¶

Optional[X] は X | None (や Union[X, None]) と同等です。

これは、デフォルト値を持つ省略可能な引数とは別の概念です。デフォルト値があり省略可能というだけで、その引数の型アノテーションに Optional が必要になるわけではありません。例えば次のようになります。

def foo(arg: int = 0) -> None:
    ...

それとは逆に、 None という値が許されていることが明示されている場合は、引数がオプションであろうとなかろうと、 Optional を使うのが好ましいです。例えば次のようになります:

def foo(arg: Optional[int] = None) -> None:
    ...

バージョン 3.10 で変更: Optionalは X | None のように書けるようになりました。 union型の表現を参照ください。

typing.Concatenate¶

高階関数をアノテーションするための特殊形式です。

Concatenate can be used in conjunction with Callable and ParamSpec to annotate a higher-order callable which adds, removes, or transforms parameters of another callable. Usage is in the form Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]. Concatenate is valid when used in Callable type hints and when instantiating user-defined generic classes with ParamSpec parameters. The last parameter to Concatenate must be a ParamSpec or ellipsis (...).

例えば、デコレートした関数に threading.Lock を渡すデコレータ with_lock にアノテーションを付ける場合を考えます。 Concatenate を使うと、with_lock が最初の引数に Lock を取る呼び出し可能オブジェクトを受け取り、異なる型シグネチャの呼び出し可能オブジェクトを返すことを示せます。この場合、ParamSpec は、返される呼び出し可能オブジェクトのパラメータの型が、渡された呼び出し可能オブジェクトのパラメータの型に依存することを示します。

from collections.abc import Callable
from threading import Lock
from typing import Concatenate

# このロックを使い、どの時点でも関数を実行するスレッドが
# 1 つだけになるようにする。
my_lock = Lock()

def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''ロックを渡す型安全なデコレータ。'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # 最初の引数としてロックを渡す。
        return f(my_lock, *args, **kwargs)
    return inner

@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''数値のリストをスレッドセーフな方法で合計する。'''
    with lock:
        return sum(numbers)

# デコレータがあるので、ロックを自分で渡す必要はない。
sum_threadsafe([1.1, 2.2, 3.3])

Added in version 3.10.

参考

PEP 612 -- パラメータ仕様変数 (ParamSpec と Concatenate を導入した PEP)
ParamSpec
呼び出し可能オブジェクトのアノテーション

typing.Literal¶

「リテラル型」を定義するための特殊な型付け形式です。

Literal は、アノテーションを付けたオブジェクトの値が、指定したリテラルのいずれかと等しいことを型チェッカーに示すために使えます。

例えば:

def validate_simple(data: Any) -> Literal[True]:  # 常に True を返す
    ...

type Mode = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: Mode) -> str:
    ...

open_helper('/some/path', 'r')      # 型チェックを通過する
open_helper('/other/path', 'typo')  # 型チェッカーのエラー

Literal[...] はサブクラスにはできません。実行時に、任意の値が Literal[...] の型引数として使えますが、型チェッカーが制約を課すことがあります。リテラル型についてより詳しいことは PEP 586 を参照してください。

その他の詳細:

引数はリテラル値でなければならず、少なくとも 1 つ必要です。
入れ子の Literal 型は平坦化されます。例えば次のようになります。
```
assert Literal[Literal[1, 2], 3] == Literal[1, 2, 3]
```
ただし、型エイリアスを介して参照される Literal 型にはこの処理は適用されません。元の TypeAliasType を強制的に評価することを避けるためです。
```
type A = Literal[1, 2]
assert Literal[A, 3] != Literal[1, 2, 3]
```
冗長な実引数は飛ばされます。例えば:
```
assert Literal[1, 2, 1] == Literal[1, 2]
```
リテラル型を比較するとき、引数の順序は無視されます。例えば次のようになります。
```
assert Literal[1, 2] == Literal[2, 1]
```
Literal のサブクラスやインスタンスは作成できません。
Literal[X][Y] とは書けません。

Added in version 3.8.

バージョン 3.9.1 で変更: Literal ではパラメータの重複を解消するようになりました。Literal オブジェクトの等値比較は順序に依存しないようになりました。Literal オブジェクトは、等値比較する際に、パラメータのうち 1 つでも hashable でない場合は TypeError を送出するようになりました。

typing.ClassVar¶

クラス変数であることを示す特別な型構築子です。

PEP 526 で導入された通り、 ClassVar でラップされた変数アノテーションによって、ある属性はクラス変数として使うつもりであり、そのクラスのインスタンスから設定すべきではないということを示せます。使い方は次のようになります:

class Starship:
    stats: ClassVar[dict[str, int]] = {} # クラス変数
    damage: int = 10                     # インスタンス変数

ClassVar は型だけを受け入れ、さらに添字付けすることはできません。

ClassVar is not a class itself, and cannot be used with isinstance() or issubclass(). ClassVar does not change Python runtime behavior, but it can be used by static type checkers. For example, a type checker might flag the following code as an error:

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Error, setting class variable on instance
Starship.stats = {}     # This is OK

Added in version 3.5.3.

バージョン 3.13 で変更: ClassVar を Final の内側に入れることも、その逆も可能になりました。

typing.Final¶

再代入できない名前であることを型チェッカーに示すための特殊な型構築子です。

final とされた名前は、どのスコープでも再代入できません。クラススコープで宣言された final な名前は、サブクラスでオーバーライドできません。

例えば:

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # 型チェッカーがエラーを報告する

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # 型チェッカーがエラーを報告する

この機能は実行時には検査されません。詳細については PEP 591 を参照してください。

Added in version 3.8.

バージョン 3.13 で変更: Final を ClassVar の内側に入れることも、その逆も可能になりました。

typing.Required¶

TypedDict のキーが必須であることを示すための特殊な型構築子です。

主に total=False の TypedDict で役立ちます。詳細は TypedDict と PEP 655 を参照してください。

Added in version 3.11.

typing.NotRequired¶

TypedDict のキーが存在しない場合もあることを示すための特殊な型構築子です。

より詳しくは、 TypedDict と PEP 655 を参照してください。

Added in version 3.11.

typing.ReadOnly¶

TypedDict の項目が読み取り専用であることを示すための特殊な型構築子です。

例えば:

class Movie(TypedDict):
   title: ReadOnly[str]
   year: int

def mutate_movie(m: Movie) -> None:
   m["year"] = 1999  # allowed
   m["title"] = "The Matrix"  # type checker error

この性質は実行時には検査されません。

詳細は TypedDict と PEP 705 を参照してください。

Added in version 3.13.

typing.Annotated¶

アノテーションに文脈固有のメタデータを追加するための特殊な型付け形式です。

Annotated[T, x] というアノテーションを使って、型 T にメタデータ x を追加します。 Annotated で追加したメタデータは、静的解析ツールでも実行時にも利用できます。実行時には、メタデータは __metadata__ 属性に格納されます。

ライブラリやツールが Annotated[T, x] というアノテーションを処理するとき、メタデータに対する特別な処理を持たなければ、メタデータを無視してアノテーションを単に T として扱うべきです。このため、Annotated は Python の静的型システム以外の目的でアノテーションを利用するコードに役立ちます。

Using Annotated[T, x] as an annotation still allows for static typechecking of T, as type checkers will simply ignore the metadata x. In this way, Annotated differs from the @no_type_check decorator, which can also be used for adding annotations outside the scope of the typing system, but completely disables typechecking for a function or class.

メタデータをどう解釈するかは、Annotated アノテーションを処理するツールやライブラリの責任です。 Annotated 型を処理するツールやライブラリは、メタデータの各要素を調べて、自分が扱うべきものかどうかを判定できます (例えば isinstance() を使います)。

Annotated[<type>, <metadata>]

範囲解析を行う場合に、Annotated を使って型アノテーションにメタデータを追加する例を示します:

@dataclass
class ValueRange:
    lo: int
    hi: int

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

Annotated の最初の引数は有効な型でなければなりません。 Annotated は可変長引数に対応しているため、複数のメタデータ要素を指定できます。メタデータ要素の順序は保持され、等価比較の結果にも影響します。

@dataclass
class ctype:
     kind: str

a1 = Annotated[int, ValueRange(3, 10), ctype("char")]
a2 = Annotated[int, ctype("char"), ValueRange(3, 10)]

assert a1 != a2  # 順序が影響する

利用者が 1 つのアノテーションに複数のメタデータ要素を追加してよいかどうかや、それらのアノテーションをどう統合するかは、アノテーションを利用するツールが決めます。

入れ子の Annotated 型は平坦化されます。メタデータ要素は、最も内側のアノテーションから順に並びます。

assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
    int, ValueRange(3, 10), ctype("char")
]

ただし、型エイリアスを介して参照される Annotated 型にはこの処理は適用されません。元の TypeAliasType を強制的に評価することを避けるためです。

type From3To10[T] = Annotated[T, ValueRange(3, 10)]
assert Annotated[From3To10[int], ctype("char")] != Annotated[
   int, ValueRange(3, 10), ctype("char")
]

重複するメタデータ要素は取り除かれません。

assert Annotated[int, ValueRange(3, 10)] != Annotated[
    int, ValueRange(3, 10), ValueRange(3, 10)
]

Annotated は、入れ子のエイリアスやジェネリックなエイリアスで使えます:

@dataclass
class MaxLen:
    value: int

type Vec[T] = Annotated[list[tuple[T, T]], MaxLen(10)]

# 型アノテーションで使うと、型チェッカーは "V" を
# ``Annotated[list[tuple[int, int]], MaxLen(10)]`` と同じように扱う:
type V = Vec[int]

Annotated は、展開された TypeVarTuple では使えません。

type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1]  # 無効

ここで T1、T2、... は TypeVar です。 Annotated に渡す型は 1 つだけでなければならないため、この書き方は無効です。

デフォルトでは get_type_hints() はアノテーションからメタデータを取り除きます。メタデータを保持するには include_extras=True を渡してください:

>>> from typing import Annotated, get_type_hints
>>> def func(x: Annotated[int, "metadata"]) -> None: pass
...
>>> get_type_hints(func)
{'x': <class 'int'>, 'return': <class 'NoneType'>}
>>> get_type_hints(func, include_extras=True)
{'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

実行時には、Annotated 型に関連付けられたメタデータを __metadata__ 属性から取得できます:

>>> from typing import Annotated
>>> X = Annotated[int, "very", "important", "metadata"]
>>> X
typing.Annotated[int, 'very', 'important', 'metadata']
>>> X.__metadata__
('very', 'important', 'metadata')

Annotated でラップされた元の型を取得するには、__origin__ 属性を使ってください:

>>> from typing import Annotated, get_origin
>>> Password = Annotated[str, "secret"]
>>> Password.__origin__
<class 'str'>

get_origin() を使うと Annotated 自体が返されることに注意してください:

>>> get_origin(Password)
typing.Annotated

参考

PEP 593 - 関数と変数の柔軟なアノテーション: Annotated を標準ライブラリに導入した PEP です。

Added in version 3.9.

typing.TypeIs¶

ユーザー定義の型述語関数であることを示すための特殊な型構築子です。

TypeIs は、ユーザー定義の型述語関数の戻り値の型をアノテーションするために使えます。 TypeIs が受け取る型引数は 1 つだけです。このようにアノテーションされた関数は、実行時に少なくとも 1 つの位置引数を受け取り、ブール値を返す必要があります。

TypeIs は 型の絞り込み に役立つように設計されています。これは、静的型チェッカーがプログラムの制御フロー内で式の型をより具体的に特定する手法です。通常は条件分岐を解析し、その結果に基づいてコードブロック内の型を絞り込みます。ここで使われる条件式を「型述語」と呼ぶことがあります。

def is_str(val: str | float):
    # "isinstance" による型述語
    if isinstance(val, str):
        # ``val`` の型を ``str`` に絞り込む
        ...
    else:
        # そうでなければ、``val`` の型を ``float`` に絞り込む。
        ...

ブール値を返すユーザー定義関数を型述語として使うと便利な場合があります。そのような関数では、静的型チェッカーに意図を伝えるため、戻り値の型に TypeIs[...] または TypeGuard を使うべきです。 TypeIs は通常 TypeGuard より直感的に動作しますが、入力の型と絞り込む先の型に互換性がない場合 (list[object] から list[int] など) や、絞り込む先の型のすべてのインスタンスに対して True を返す関数でない場合には使えません。

-> TypeIs[NarrowedType] と指定すると、静的型チェッカーに関数の以下の性質を伝えられます:

戻り値はブール値です。
戻り値が True なら、引数の型は、元の引数の型と NarrowedType の共通部分になります。
戻り値が False なら、引数の型は NarrowedType を除外するように絞り込まれます。

例えば:

from typing import assert_type, final, TypeIs

class Parent: pass
class Child(Parent): pass
@final
class Unrelated: pass

def is_parent(val: object) -> TypeIs[Parent]:
    return isinstance(val, Parent)

def run(arg: Child | Unrelated):
    if is_parent(arg):
        # ``arg`` の型を ``Parent`` と ``Child`` の共通部分に
        # 絞り込む。
        # これは ``Child`` と同じ。
        assert_type(arg, Child)
    else:
        # ``arg`` の型から ``Parent`` を除外するように絞り込むので、
        # ``Unrelated`` だけが残る。
        assert_type(arg, Unrelated)

TypeIs の内側の型は、関数の引数の型と整合していなければなりません。整合していなければ、静的型チェッカーがエラーを報告します。 TypeIs 関数を誤って書くと型システムの健全性が損なわれるおそれがあり、そのような関数を型安全に書くのは利用者の責任です。

TypeIs 関数がクラスメソッドまたはインスタンスメソッドの場合、TypeIs 内の型は (cls または self の後の) 2 番目のパラメータの型に対応します。

つまり、def foo(arg: TypeA) -> TypeIs[TypeB]: ... という形式は、 foo(arg) が True を返したら arg は TypeB のインスタンスであり、 False を返したら TypeB のインスタンスではないことを意味します。

TypeIs は型変数でも使えます。詳細は PEP 742 (TypeIs による型の絞り込み) を参照してください。

Added in version 3.13.

typing.TypeGuard¶

ユーザー定義の型述語関数であることを示すための特殊な型構築子です。

型述語関数は、引数が特定の型のインスタンスであるかどうかを返すユーザー定義関数です。 TypeGuard は TypeIs と同じように動作しますが、型チェックへの効果には細かな違いがあります (下記を参照)。

-> TypeGuard と指定すると、静的型チェッカーに関数の以下の性質を伝えられます:

戻り値はブール値です。
戻り値が True なら、引数の型は TypeGuard 内の型になります。

TypeGuard は型変数でも使えます。詳細は PEP 647 を参照してください。

例えば:

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''リスト内のすべてのオブジェクトが文字列かどうかを判定する'''
    return all(isinstance(x, str) for x in val)

def func1(val: list[object]):
    if is_str_list(val):
        # ``val`` の型を ``list[str]`` に絞り込む。
        print(" ".join(val))
    else:
        # ``val`` の型は ``list[object]`` のまま。
        print("Not a list of strings!")

TypeIs と TypeGuard には以下の違いがあります:

TypeIs は、絞り込む先の型が入力の型のサブタイプであることを要求しますが、TypeGuard は要求しません。主な理由は、list[object] から list[str] への絞り込みなどを可能にするためです。 list は不変なので、後者は前者のサブタイプではありません。
TypeGuard 関数が True を返すと、型チェッカーは変数の型を TypeGuard に指定された型そのものに絞り込みます。 TypeIs 関数が True を返す場合は、変数についてすでに分かっている型と TypeIs に指定された型を組み合わせて、型チェッカーはより具体的な型を推論できます (専門的には交差型と呼びます)。
TypeGuard 関数が False を返した場合、型チェッカーは変数の型をまったく絞り込めません。 TypeIs 関数が False を返した場合は、TypeIs に指定された型を除外するように変数の型を絞り込めます。

Added in version 3.10.

typing.Unpack¶

オブジェクトが展開済みであることを概念的に示すための型付け演算子です。

例えば、型変数タプルに展開演算子 * を適用することは、Unpack を使ってその型変数タプルを展開済みと示すことと同じです。

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# 実質的に次と同じ:
tup: tuple[Unpack[Ts]]

実際、typing.TypeVarTuple や builtins.tuple の型を扱う場合、Unpack と * は互いに置き換えられます。古いバージョンの Python では * を使えない箇所があったため、Unpack を明示的に使う書き方も見られます。

# 古いバージョンの Python では、TypeVarTuple と Unpack は
# バックポート用の `typing_extensions` パッケージに含まれる。
from typing_extensions import TypeVarTuple, Unpack

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Python 3.10 以下では構文エラー!
tup: tuple[Unpack[Ts]]  # 意味は同じで、後方互換性もある

Unpack は typing.TypedDict と組み合わせて、関数シグネチャの **kwargs の型を指定するためにも使えます。

from typing import TypedDict, Unpack

class Movie(TypedDict):
    name: str
    year: int

# この関数は 2 つのキーワード引数を取る。
# `str` 型の `name` と `int` 型の `year`。
def foo(**kwargs: Unpack[Movie]): ...

Unpack で **kwargs の型を指定する方法の詳細は PEP 692 を参照してください。

Added in version 3.11.

ジェネリック型と型エイリアスの構築¶

以下のクラスをアノテーションとして直接使うべきではありません。これらはジェネリック型や型エイリアスを作成するための構成要素として使うものです。

これらのオブジェクトは、専用の構文 (型引数リストと type 文) で作成できます。 Python 3.11 以前との互換性のために、以下で説明するように専用の構文を使わずに作成することもできます。

class typing.Generic¶

ジェネリック型のための抽象基底クラスです。

通常、ジェネリック型はクラス名の後に型引数のリストを追加して宣言します。

class Mapping[KT, VT]:
    def __getitem__(self, key: KT) -> VT:
        ...
        # など。

このようなクラスは暗黙的に Generic を継承します。この構文の実行時の意味は言語リファレンスで説明しています。

このクラスは次のように使用することが出来ます:

def lookup_name[X, Y](mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default

ここでは、関数名の後の角括弧がジェネリック関数であることを示します。

後方互換性のために、Generic を明示的に継承してジェネリッククラスを宣言することもできます。この場合、型引数は別途宣言する必要があります。

KT = TypeVar('KT')
VT = TypeVar('VT')

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # など。

class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)¶

型変数です。

型変数を作成するには、ジェネリック関数、ジェネリッククラス、ジェネリック型エイリアスの専用構文を使う方法が推奨されます。

class Sequence[T]:  # T は TypeVar
    ...

この構文では、上限付きや制約付きの型変数も作成できます。

class StrSequence[S: str]:  # S は `str` を上限とする TypeVar
    ...                     # S は「`str` を上限とする」と言える


class StrOrBytesSequence[A: (str, bytes)]:  # A は str または bytes に制約された TypeVar
    ...

ただし、必要であれば、再利用可能な型変数を以下のように明示的に作成することもできます。

T = TypeVar('T')  # どの型でもよい
S = TypeVar('S', bound=str)  # str の任意のサブタイプ
A = TypeVar('A', str, bytes)  # str または bytes そのものでなければならない

型変数は、主に静的型チェッカーで利用するためのものです。ジェネリック型の型引数や、ジェネリック関数や型エイリアスの定義の型引数として使われます。ジェネリック型の詳細は Generic を参照してください。ジェネリック関数は以下のように動作します。

def repeat[T](x: T, n: int) -> Sequence[T]:
    """x への参照を n 個含むリストを返す。"""
    return [x]*n


def print_capitalized[S: str](x: S) -> S:
    """x の先頭を大文字にして表示し、x を返す。"""
    print(x.capitalize())
    return x


def concatenate[A: (str, bytes)](x: A, y: A) -> A:
    """2 つの文字列または bytes オブジェクトを連結する。"""
    return x + y

型変数には上限を設けるか、制約を設けるか、どちらも設けないかを選べますが、上限と制約の両方を設けることはできません。

型引数構文で作成した型変数や、infer_variance=True を指定した型変数では、型チェッカーが変性を推論します。明示的に作成する型変数は、covariant=True または contravariant=True を渡して共変または反変と指定できます。明示的に作成する型変数は、デフォルトでは不変です。詳細は PEP 484 と PEP 695 を参照してください。

上限付き型変数と制約付き型変数は、意味の面でいくつかの重要な違いがあります。 上限付き 型変数を使うと、TypeVar は可能な限り具体的な型に解決されます。

x = print_capitalized('a string')
reveal_type(x)  # 表示される型は str

class StringSubclass(str):
    pass

y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # 表示される型は StringSubclass

z = print_capitalized(45)  # エラー: int は str のサブタイプではない

型変数の上限には、具象型、抽象型 (ABC やプロトコル)、さらには型のユニオンも指定できます。

# __abs__ メソッドを持つ型なら何でもよい
def print_abs[T: SupportsAbs](arg: T) -> None:
    print("Absolute value:", abs(arg))

U = TypeVar('U', bound=str|bytes)  # ユニオン str|bytes の任意のサブタイプ
V = TypeVar('V', bound=SupportsAbs)  # __abs__ メソッドを持つ型なら何でもよい

一方、制約付き 型変数では、TypeVar は指定した制約のいずれかの型そのものにしか解決されません。

a = concatenate('one', 'two')
reveal_type(a)  # 表示される型は str

b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # StringSubclass を渡しても、表示される型は str

c = concatenate('one', b'two')  # エラー: 1 回の関数呼び出しで型変数 'A' は str か bytes のいずれかであり、両方にはできない

実行時には isinstance(x, T) は TypeError を送出します。

__name__¶: 型変数の名前です。

__covariant__¶: 型変数が明示的に共変と指定されているかどうかです。

__contravariant__¶: 型変数が明示的に反変と指定されているかどうかです。

__infer_variance__¶: 型チェッカーが型変数の変性を推論するかどうかです。

Added in version 3.12.

__bound__¶: 型変数の上限です (設定されている場合)。

バージョン 3.12 で変更: 型引数構文で作成された型変数では、上限は型変数の作成時には評価されず、属性へのアクセス時に初めて評価されます (遅延評価を参照)。

__constraints__¶: 型変数の制約があれば、それらを格納したタプルです。

バージョン 3.12 で変更: 型引数構文で作成された型変数では、制約は型変数の作成時には評価されず、属性へのアクセス時に初めて評価されます (遅延評価を参照)。

__default__¶: 型変数のデフォルト値です。デフォルト値がなければ typing.NoDefault です。

Added in version 3.13.

has_default()¶: 型変数にデフォルト値があるかどうかを返します。 __default__ が typing.NoDefault シングルトンでないことを調べるのと同じですが、遅延評価されるデフォルト値を強制的に評価しません。

Added in version 3.13.

バージョン 3.12 で変更: PEP 695 で導入された型引数構文で型変数を宣言できるようになりました。 infer_variance パラメータが追加されました。

バージョン 3.13 で変更: デフォルト値に対応しました。

class typing.TypeVarTuple(name, *, default=typing.NoDefault)¶

型変数タプルです。 可変長 ジェネリックを可能にする特殊な型変数です。

型引数リスト内で、名前の前にアスタリスクを 1 つ (*) 付けて型変数タプルを宣言できます。

def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

TypeVarTuple コンストラクタを明示的に呼び出すこともできます。

T = TypeVar("T")
Ts = TypeVarTuple("Ts")

def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

通常の型変数は 1 つの型でパラメータ化します。これに対して型変数タプルは、任意の数 の型変数をタプルにまとめたように振る舞い、任意の数 の型でパラメータ化できます。例えば次のようになります。

# T は int に、Ts は () に束縛される
# 戻り値は (1,) で、型は tuple[int]
move_first_element_to_last(tup=(1,))

# T は int に、Ts は (str,) に束縛される
# 戻り値は ('spam', 1) で、型は tuple[str, int]
move_first_element_to_last(tup=(1, 'spam'))

# T は int に、Ts は (str, float) に束縛される
# 戻り値は ('spam', 3.0, 1) で、型は tuple[str, float, int]
move_first_element_to_last(tup=(1, 'spam', 3.0))

# tuple[()] は tuple[T, *Ts] と互換性がないため、
# 型チェックにも実行時にも失敗する
# (少なくとも 1 つの要素が必要)
move_first_element_to_last(tup=())

tuple[T, *Ts] で展開演算子 * を使っている点に注意してください。概念的には、Ts は型変数のタプル (T1, T2, ...) と考えられます。すると tuple[T, *Ts] は tuple[T, *(T1, T2, ...)] となり、tuple[T, T1, T2, ...] と同じ意味です。古いバージョンの Python では、代わりに Unpack を使って Unpack[Ts] と書かれている場合もあります。

型変数タプルは必ず展開しなければなりません。これにより、型変数タプルを通常の型変数と区別しやすくなります。

x: Ts          # 無効
x: tuple[Ts]   # 無効
x: tuple[*Ts]  # 正しい書き方

型変数タプルは、通常の型変数と同じ文脈で使えます。例えばクラス定義、引数、戻り値の型などです。

class Array[*Shape]:
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Array[*Shape]": ...
    def get_shape(self) -> tuple[*Shape]: ...

型変数タプルは通常の型変数と組み合わせて使えます:

class Array[DType, *Shape]:  # これは問題ない
    pass

class Array2[*Shape, DType]:  # これも問題ない
    pass

class Height: ...
class Width: ...

float_array_1d: Array[float, Height] = Array()     # 問題ない
int_array_2d: Array[int, Height, Width] = Array()  # これも問題ない

ただし、型引数を指定または宣言する 1 つのリスト内には、型変数タプルを最大 1 つしか含められません。

x: tuple[*Ts, *Ts]            # 無効
class Array[*Shape, *Shape]:  # 無効
    pass

最後に、展開された型変数タプルは *args の型アノテーションとして使えます。

def call_soon[*Ts](
    callback: Callable[[*Ts], None],
    *args: *Ts
) -> None:
    ...
    callback(*args)

展開しない *args のアノテーション (例えば *args: int は すべての 引数を int と指定します) とは異なり、 *args: *Ts では *args の 個々の 引数の型を参照できます。この例では、call_soon に渡される *args の型と callback の (位置) 引数の型の一致を保証できます。

型変数タプルの詳細は PEP 646 を参照してください。

__name__¶: 型変数タプルの名前です。

__default__¶: 型変数タプルのデフォルト値です。デフォルト値がなければ typing.NoDefault です。

Added in version 3.13.

has_default()¶: 型変数タプルにデフォルト値があるかどうかを返します。 __default__ が typing.NoDefault シングルトンでないことを調べるのと同じですが、遅延評価されるデフォルト値を強制的に評価しません。

Added in version 3.13.

Added in version 3.11.

バージョン 3.12 で変更: PEP 695 で導入された型引数構文で型変数タプルを宣言できるようになりました。

バージョン 3.13 で変更: デフォルト値に対応しました。

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)¶

パラメータ仕様変数です。特殊な型変数です。

型引数リスト内で、アスタリスクを 2 つ (**) 付けてパラメータ仕様を宣言できます。

type IntFunc[**P] = Callable[P, int]

Python 3.11 以前との互換性のために、ParamSpec オブジェクトは以下のように作成することもできます。

P = ParamSpec('P')

パラメータ仕様変数は、主に静的型チェッカーで利用するためのものです。ある呼び出し可能オブジェクトのパラメータの型を、別の呼び出し可能オブジェクトへ引き継ぐために使います。これは高階関数やデコレータによく見られるパターンです。パラメータ仕様変数を使えるのは、Concatenate の中、Callable の最初の引数、またはユーザー定義のジェネリックの型引数だけです。ジェネリック型の詳細は Generic を参照してください。

例えば、関数に基本的なログ出力を追加するには、関数の呼び出しを記録するデコレータ add_logging を作れます。パラメータ仕様変数は、デコレータに渡した呼び出し可能オブジェクトと、それが返す新しい呼び出し可能オブジェクトの型引数が互いに依存していることを型チェッカーに伝えます。

from collections.abc import Callable
import logging

def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
    '''関数にログ出力を追加する型安全なデコレータ。'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner

@add_logging
def add_two(x: float, y: float) -> float:
    '''2 つの数値を足し合わせる。'''
    return x + y

ParamSpec がなかった頃、このような関数にアノテーションを付ける最も簡単な方法は、上限を Callable[..., Any] とした TypeVar を使うことでした。ただし、この方法には 2 つの問題があります:

*args と **kwargs の型を Any としなければならないため、型チェッカーは inner 関数の型チェックを行えません。
add_logging デコレータの本体で inner 関数を返すときに cast() が必要になるか、静的型チェッカーに return inner を無視するように指示しなければなりません。

args¶

kwargs¶: Since ParamSpec captures both positional and keyword parameters, P.args and P.kwargs can be used to split a ParamSpec into its components. P.args represents the tuple of positional parameters in a given call and should only be used to annotate *args. P.kwargs represents the mapping of keyword parameters to their values in a given call, and should be only be used to annotate **kwargs. Both attributes require the annotated parameter to be in scope. At runtime, P.args and P.kwargs are instances respectively of ParamSpecArgs and ParamSpecKwargs.

__name__¶: パラメータ仕様の名前です。

__default__¶: パラメータ仕様のデフォルト値です。デフォルト値がなければ typing.NoDefault です。

Added in version 3.13.

has_default()¶: パラメータ仕様にデフォルト値があるかどうかを返します。 __default__ が typing.NoDefault シングルトンでないことを調べるのと同じですが、遅延評価されるデフォルト値を強制的に評価しません。

Added in version 3.13.

covariant=True または contravariant=True を指定して作成したパラメータ仕様変数は、共変または反変のジェネリック型を宣言するために使えます。 TypeVar と同様に bound 引数も受け取れます。ただし、これらのキーワードの実際の意味はまだ決まっていません。

Added in version 3.10.

バージョン 3.12 で変更: PEP 695 で導入された型引数構文でパラメータ仕様を宣言できるようになりました。

バージョン 3.13 で変更: デフォルト値に対応しました。

注釈

pickle 化できるのは、グローバルスコープで定義されたパラメータ仕様変数だけです。

参考

PEP 612 -- パラメータ仕様変数 (ParamSpec と Concatenate を導入した PEP)
Concatenate
呼び出し可能オブジェクトのアノテーション

class typing.ParamSpecArgs¶

class typing.ParamSpecKwargs¶

ParamSpec の位置引数とキーワード引数を表す属性です。 ParamSpec の P.args 属性は ParamSpecArgs のインスタンス、P.kwargs は ParamSpecKwargs のインスタンスです。これらは実行時のイントロスペクション用であり、静的型チェッカーにとって特別な意味はありません。

どちらのオブジェクトでも、get_origin() を呼び出すと元の ParamSpec が返されます:

>>> from typing import ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) is P
True
>>> get_origin(P.kwargs) is P
True

Added in version 3.10.

class typing.TypeAliasType(name, value, *, type_params=())¶

type 文で作成される型エイリアスの型です。

例:

>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>

Added in version 3.12.

__name__¶

型エイリアスの名前です:

>>> type Alias = int
>>> Alias.__name__
'Alias'

__module__¶

The name of the module in which the type alias was defined:

>>> type Alias = int
>>> Alias.__module__
'__main__'

__type_params__¶

型エイリアスの型引数です。ジェネリックでないエイリアスの場合は空のタプルです:

>>> type ListOrSet[T] = list[T] | set[T]
>>> ListOrSet.__type_params__
(T,)
>>> type NotGeneric = int
>>> NotGeneric.__type_params__
()

__value__¶

型エイリアスの値です。遅延評価されるため、エイリアスの定義で使われる名前は __value__ 属性にアクセスするまで解決されません:

>>> type Mutually = Recursive
>>> type Recursive = Mutually
>>> Mutually
Mutually
>>> Recursive
Recursive
>>> Mutually.__value__
Recursive
>>> Recursive.__value__
Mutually

その他の特殊な指示¶

これらの関数やクラスをアノテーションとして直接使うべきではありません。型を作成したり宣言したりするための構成要素として使うものです。

class typing.NamedTuple¶

collections.namedtuple() の型付き版です。

使い方:

class Employee(NamedTuple):
    name: str
    id: int

これは次と等価です:

Employee = collections.namedtuple('Employee', ['name', 'id'])

フィールドにデフォルト値を与えるにはクラス本体で代入してください:

class Employee(NamedTuple):
    name: str
    id: int = 3

employee = Employee('Guido')
assert employee.id == 3

デフォルト値のあるフィールドはデフォルト値のないフィールドの後でなければなりません。

The types for each field name can be retrieved by calling inspect.get_annotations() on the resulting class. (The field names are in the _fields attribute and the default values are in the _field_defaults attribute, both of which are part of the namedtuple() API.)

NamedTuple のサブクラスは docstring やメソッドも持てます:

class Employee(NamedTuple):
    """従業員を表す。"""
    name: str
    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

NamedTuple のサブクラスはジェネリックにもできます。

class Group[T](NamedTuple):
    key: T
    group: list[T]

後方互換な使用法:

# Python 3.11 でジェネリックな NamedTuple を作成する方法
T = TypeVar("T")

class Group(NamedTuple, Generic[T]):
    key: T
    group: list[T]

# 関数呼び出し形式にも対応している
Employee = NamedTuple('Employee', [('name', str), ('id', int)])

バージョン 3.6 で変更: PEP 526 変数アノテーションのシンタックスが追加されました。

バージョン 3.6.1 で変更: デフォルト値、メソッド、ドキュメンテーション文字列への対応が追加されました。

バージョン 3.8 で変更: _field_types 属性および __annotations__ 属性は OrderedDict インスタンスではなく普通の辞書になりました。

バージョン 3.9 で変更: _field_types 属性は削除されました。代わりに同じ情報を持つより標準的な __annotations__ 属性を使ってください。

バージョン 3.9 で変更: NamedTuple is now a function rather than a class. It can still be used as a class base, as described above.

バージョン 3.11 で変更: ジェネリックな名前付きタプルに対応しました。

Deprecated since version 3.13, will be removed in version 3.15: The undocumented keyword argument syntax for creating NamedTuple classes (NT = NamedTuple("NT", x=int)) is deprecated, and will be disallowed in 3.15. Use the class-based syntax or the functional syntax instead.

Deprecated since version 3.13, will be removed in version 3.15: When using the functional syntax to create a NamedTuple class, failing to pass a value to the 'fields' parameter (NT = NamedTuple("NT")) is deprecated. Passing None to the 'fields' parameter (NT = NamedTuple("NT", None)) is also deprecated. Both will be disallowed in Python 3.15. To create a NamedTuple class with 0 fields, use class NT(NamedTuple): pass or NT = NamedTuple("NT", []).

class typing.NewType(name, tp)¶

オーバーヘッドの小さい別個の型を作成するためのヘルパークラスです。

A NewType is considered a distinct type by a type checker. At runtime, however, calling a NewType returns its argument unchanged.

使い方:

UserId = NewType('UserId', int)  # NewType の "UserId" を宣言する
first_user = UserId(1)  # 実行時には "UserId" は引数をそのまま返す

__module__¶: The name of the module in which the new type is defined.

__name__¶: 新しい型の名前です。

__supertype__¶: 新しい型の基になる型です。

Added in version 3.5.2.

バージョン 3.10 で変更: NewType は関数ではなくクラスになりました。

class typing.Protocol(Generic)¶

プロトコルクラスの基底クラスです。

プロトコルクラスは以下のように定義します。

class Proto(Protocol):
    def meth(self) -> int:
        ...

このようなクラスは主に構造的部分型 (静的ダックタイピング) を認識する静的型チェッカーが使います。例えば:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # 静的型チェックを通過する

See PEP 544 for more details. Protocol classes decorated with @runtime_checkable (described later) act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes without this decorator cannot be used as the second argument to isinstance() or issubclass().

プロトコルクラスはジェネリックにもできます。例えば:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

Python 3.11 以前との互換性が必要なコードでは、ジェネリックなプロトコルを以下のように書けます。

T = TypeVar("T")

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...

Added in version 3.8.

@typing.runtime_checkable¶

プロトコルクラスを実行時プロトコルとして指定します。

Such a protocol can be used with isinstance() and issubclass(). This allows a simple-minded structural check, very similar to "one-trick ponies" in collections.abc such as Iterable. For example:

@runtime_checkable
class Closable(Protocol):
    def close(self): ...

assert isinstance(open('/some/file'), Closable)

@runtime_checkable
class Named(Protocol):
    name: str

import threading
assert isinstance(threading.Thread(name='Bob'), Named)

このデコレータをプロトコルでないクラスに適用すると、TypeError が発生します。

注釈

@runtime_checkable will check only the presence of the required methods or attributes, not their type signatures or types. For example, ssl.SSLObject is a class, therefore it passes an issubclass() check against Callable. However, the ssl.SSLObject.__init__ method exists only to raise a TypeError with a more informative message, therefore making it impossible to call (instantiate) ssl.SSLObject.

注釈

実行時検査可能なプロトコルに対する isinstance() の検査は、プロトコルでないクラスに対する isinstance() の検査と比べて著しく遅いことがあります。性能が重要なコードでは、構造検査に hasattr() の呼び出しなど別の方法を使うことを検討してください。

Added in version 3.8.

バージョン 3.12 で変更: 実行時検査可能なプロトコルに対する isinstance() の検査の内部実装は、属性の検索に inspect.getattr_static() を使うようになりました (以前は hasattr() を使っていました)。その結果、以前は実行時検査可能なプロトコルのインスタンスとみなされていたオブジェクトが、Python 3.12 以降ではそうみなされなくなる場合があり、その逆もあります。ほとんどの利用者はこの変更の影響を受けないでしょう。

バージョン 3.12 で変更: The members of a runtime-checkable protocol are now considered "frozen" at runtime as soon as the class has been created. Monkey-patching attributes onto a runtime-checkable protocol will still work, but will have no impact on isinstance() checks comparing objects to the protocol. See What's new in Python 3.12 for more details.

class typing.TypedDict(dict)¶

Special construct to add type hints to a dictionary. At runtime "TypedDict instances" are simply dicts.

TypedDict は、その全てのインスタンスにおいてキーの集合が固定されていて、各キーに対応する値が全てのインスタンスで同じ型を持つことが期待される辞書型を宣言します。この期待は実行時にはチェックされず、型チェッカーでのみ強制されます。使用方法は次の通りです:

class Point2D(TypedDict):
    x: int
    y: int
    label: str

a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
b: Point2D = {'z': 3, 'label': 'bad'}           # 型チェックに失敗する

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')

関数呼び出し形式で TypedDict を作成する方法もあります。 2 番目の引数は dict リテラルでなければなりません。

Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})

この関数呼び出し形式なら、キーワードである、ハイフンを含むなどの理由で有効な識別子ではないキーも定義できます。通常のプライベート名のような名前の変換を避ける必要があるキー名にも使えます。

# SyntaxError が発生する
class Point2D(TypedDict):
    in: int  # 'in' はキーワード
    x-y: int  # ハイフンを含む名前

class Definition(TypedDict):
    __schema: str  # `_Definition__schema` に変換される

# OK、関数呼び出し形式
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})
Definition = TypedDict('Definition', {'__schema': str})  # 名前が変換されない

デフォルトでは TypedDict のすべてのキーが必須です。 NotRequired を使うと、個々のキーを必須でないものとして指定できます。

class Point2D(TypedDict):
    x: int
    y: int
    label: NotRequired[str]

# 別の構文
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

つまり、Point2D TypedDict では label キーを省略できます。

total=False を指定し、デフォルトですべてのキーを必須でなくすることもできます。

class Point2D(TypedDict, total=False):
    x: int
    y: int

# 別の構文
Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)

つまり、Point2D TypedDict ではどのキーも省略できます。型チェッカーが total 引数の値として対応する必要があるのは、リテラルの False と True だけです。デフォルトは True で、クラス本体で定義したすべての項目を必須にします。

Required を使うと、total=False の TypedDict の個々のキーを必須にできます。

class Point2D(TypedDict, total=False):
    x: Required[int]
    y: Required[int]
    label: str

# 別の構文
Point2D = TypedDict('Point2D', {
    'x': Required[int],
    'y': Required[int],
    'label': str
}, total=False)

クラス定義形式では、TypedDict 型は他の 1 つ以上の TypedDict 型を継承できます。使用例を示します。

class Point3D(Point2D):
    z: int

Point3D has three items: x, y and z. It is equivalent to this definition:

class Point3D(TypedDict):
    x: int
    y: int
    z: int

TypedDict は、Generic を除いて TypedDict でないクラスを継承できません。例えば次のようになります。

class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # TypedDict でないクラス

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # TypeError が発生する

TypedDict はジェネリックにもできます。

class Group[T](TypedDict):
    key: T
    group: list[T]

Python 3.11 以前と互換性のあるジェネリックな TypedDict を作成するには、Generic を明示的に継承します:

T = TypeVar("T")

class Group(TypedDict, Generic[T]):
    key: T
    group: list[T]

A TypedDict can be introspected via inspect.get_annotations() (see アノテーションのベストプラクティス for more information on annotations best practices), __total__, __required_keys__, and __optional_keys__.

__total__¶

Point2D.__total__ は total 引数の値を示します。例を示します:

>>> from typing import TypedDict
>>> class Point2D(TypedDict): pass
>>> Point2D.__total__
True
>>> class Point2D(TypedDict, total=False): pass
>>> Point2D.__total__
False
>>> class Point3D(Point2D): pass
>>> Point3D.__total__
True

この属性が反映するのは、現在の TypedDict クラスに渡された total 引数の値だけであり、すべてのキーが実際に必須かどうかではありません。例えば、__total__ が True の TypedDict に NotRequired のキーがあったり、 total=False の別の TypedDict を継承していたりする場合があります。したがって、イントロスペクションには通常 __required_keys__ と __optional_keys__ を使う方が適切です。

__required_keys__¶: Added in version 3.9.

__optional_keys__¶

Point2D.__required_keys__ と Point2D.__optional_keys__ は、それぞれ必須のキーと必須でないキーを含む frozenset オブジェクトを返します。

Required で指定したキーは必ず __required_keys__ に含まれ、NotRequired で指定したキーは必ず __optional_keys__ に含まれます。

For backwards compatibility with Python 3.10 and below, it is also possible to use inheritance to declare both required and non-required keys in the same TypedDict. This is done by declaring a TypedDict with one value for the total argument and then inheriting from it in another TypedDict with a different value for total:

>>> class Point2D(TypedDict, total=False):
...     x: int
...     y: int
...
>>> class Point3D(Point2D):
...     z: int
...
>>> Point3D.__required_keys__ == frozenset({'z'})
True
>>> Point3D.__optional_keys__ == frozenset({'x', 'y'})
True

Added in version 3.9.

注釈

from __future__ import annotations を使っている場合や、アノテーションを文字列で指定した場合は、TypedDict の定義時にアノテーションが評価されません。そのため、__required_keys__ と __optional_keys__ が利用する実行時のイントロスペクションが正しく機能せず、属性の値が誤っている場合があります。

Support for ReadOnly is reflected in the following attributes:

__readonly_keys__¶: すべての読み取り専用のキーの名前を含む frozenset です。 ReadOnly 修飾子を持つキーが読み取り専用です。

Added in version 3.13.

__mutable_keys__¶: すべての変更可能なキーの名前を含む frozenset です。 ReadOnly 修飾子を持たないキーが変更可能です。

Added in version 3.13.

See PEP 589 for more examples and detailed rules of using TypedDict.

Added in version 3.8.

バージョン 3.9 で変更: TypedDict is now a function rather than a class. It can still be used as a class base, as described above.

バージョン 3.11 で変更: 個々のキーを Required または NotRequired と指定できるようになりました。 PEP 655 を参照してください。

バージョン 3.11 で変更: ジェネリックな TypedDict に対応しました。

バージョン 3.13 で変更: キーワード引数で TypedDict を作成する方法は使えなくなりました。

バージョン 3.13 で変更: Support for the ReadOnly qualifier was added.

Deprecated since version 3.13, will be removed in version 3.15: When using the functional syntax to create a TypedDict class, failing to pass a value to the 'fields' parameter (TD = TypedDict("TD")) is deprecated. Passing None to the 'fields' parameter (TD = TypedDict("TD", None)) is also deprecated. Both will be disallowed in Python 3.15. To create a TypedDict class with 0 fields, use class TD(TypedDict): pass or TD = TypedDict("TD", {}).

プロトコル¶

The following protocols are provided by the typing module. All are decorated with @runtime_checkable.

class typing.SupportsAbs¶: A protocol with one abstract method __abs__ that is covariant in its return type.

class typing.SupportsBytes¶: A protocol with one abstract method __bytes__.

class typing.SupportsComplex¶: A protocol with one abstract method __complex__.

class typing.SupportsFloat¶: A protocol with one abstract method __float__.

class typing.SupportsIndex¶: A protocol with one abstract method __index__.

Added in version 3.8.

class typing.SupportsInt¶: A protocol with one abstract method __int__.

class typing.SupportsRound¶: A protocol with one abstract method __round__ that is covariant in its return type.

ABCs for working with IO¶

class typing.IO¶
class typing.TextIO¶
class typing.BinaryIO¶: Generic type IO[AnyStr] and its subclasses TextIO(IO[str]) and BinaryIO(IO[bytes]) represent the types of I/O streams such as returned by open().

関数とデコレータ¶

typing.cast(typ, val)¶

値をある型にキャストします。

この関数は値を変更せずに返します。型検査器に対して、返り値が指定された型を持っていることを通知しますが、実行時には意図的に何も検査しません。 (その理由は、処理をできる限り速くしたかったためです。)

typing.assert_type(val, typ, /)¶

val の推論された型が typ であることを確認するよう、静的型チェッカーに要求します。

実行時には何もしません。引数の実際の型にかかわらず、検査や副作用を伴わずに最初の引数をそのまま返します。

静的型チェッカーは assert_type() の呼び出しを検出すると、値が指定された型でなければエラーを報告します。

def greet(name: str) -> None:
    assert_type(name, str)  # OK、`name` の推論された型は `str`
    assert_type(name, int)  # 型チェッカーのエラー

この関数は、型チェッカーによるスクリプトの解釈が開発者の意図と一致していることを確認するのに役立ちます。

def complex_function(arg: object):
    # 複雑な型の絞り込み処理を行い、
    # その結果、型が `int` と推論されることを期待する
    ...
    # 型チェッカーが関数を正しく理解しているかを検査する
    assert_type(arg, int)

Added in version 3.11.

typing.assert_never(arg, /)¶

あるコード行に到達しないことを確認するよう、静的型チェッカーに要求します。

以下はプログラム例です:

def int_or_str(arg: int | str) -> None:
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _ as unreachable:
            assert_never(unreachable)

この例では、アノテーションによって、型チェッカーは最後の case が決して実行されないと推論できます。 arg は int または str のいずれかで、どちらも前の case で処理されるためです。

型チェッカーが assert_never() の呼び出しに到達可能と判断すると、エラーを報告します。例えば arg の型アノテーションが int | str | float だった場合、型チェッカーは unreachable が float 型であるというエラーを報告します。 assert_never の呼び出しが型チェックを通過するには、渡した引数の推論された型がボトム型の Never でなければならず、他の型ではいけません。

実行時に呼び出すと例外を送出します。

参考

静的型付けによる網羅性検査の詳細は、Unreachable Code and Exhaustiveness Checking を参照してください。

Added in version 3.11.

typing.reveal_type(obj, /)¶

式の推論された型を表示するよう、静的型チェッカーに要求します。

静的型チェッカーは、この関数の呼び出しを検出すると、引数の推論された型を診断メッセージとして出力します。例えば次のようになります。

x: int = 1
reveal_type(x)  # 表示される型は "builtins.int"

型チェッカーが特定のコードをどう扱うかをデバッグしたいときに役立ちます。

実行時には、引数の実際の型を sys.stderr に表示し、引数をそのまま返します (そのため、式の中で呼び出せます)。

x = reveal_type(1)  # prints "Runtime type is int"
print(x)  # prints "1"

実行時の型は、型チェッカーが静的に推論した型と異なる場合があります (より具体的な場合も、より一般的な場合もあります)。

ほとんどの型チェッカーは、typing から名前をインポートしていなくても、どこでも reveal_type() を使えます。ただし、typing からインポートしておくと、実行時エラーを起こさずにコードを実行でき、意図もより明確になります。

Added in version 3.11.

@typing.dataclass_transform(*, eq_default=True, order_default=False, kw_only_default=False, frozen_default=False, field_specifiers=(), **kwargs)¶

オブジェクトが dataclass のような振る舞いを提供することを示すデコレータです。

@dataclass_transform may be used to decorate a class, metaclass, or a function that is itself a decorator. The presence of @dataclass_transform() tells a static type checker that the decorated object performs runtime "magic" that transforms a class in a similar way to @dataclasses.dataclass.

デコレータ関数での使用例:

@dataclass_transform()
def create_model[T](cls: type[T]) -> type[T]:
    ...
    return cls

@create_model
class CustomerModel:
    id: int
    name: str

基底クラスでの使用例です。

@dataclass_transform()
class ModelBase: ...

class CustomerModel(ModelBase):
    id: int
    name: str

メタクラスでの使用例です。

@dataclass_transform()
class ModelMeta(type): ...

class ModelBase(metaclass=ModelMeta): ...

class CustomerModel(ModelBase):
    id: int
    name: str

The CustomerModel classes defined above will be treated by type checkers similarly to classes created with @dataclasses.dataclass. For example, type checkers will assume these classes have __init__ methods that accept id and name.

The decorated class, metaclass, or function may accept the following bool arguments which type checkers will assume have the same effect as they would have on the @dataclasses.dataclass decorator: init, eq, order, unsafe_hash, frozen, match_args, kw_only, and slots. It must be possible for the value of these arguments (True or False) to be statically evaluated.

The arguments to the @dataclass_transform decorator can be used to customize the default behaviors of the decorated class, metaclass, or function:

パラメータ:

eq_default (bool) -- 呼び出し側が eq パラメータを省略したときに、True と False のどちらとみなすかを示します。デフォルトは True です。
order_default (bool) -- 呼び出し側が order パラメータを省略したときに、True と False のどちらとみなすかを示します。デフォルトは False です。
kw_only_default (bool) -- 呼び出し側が kw_only パラメータを省略したときに、True と False のどちらとみなすかを示します。デフォルトは False です。
frozen_default (bool) --
呼び出し側が frozen パラメータを省略したときに、True と False のどちらとみなすかを示します。デフォルトは False です。

Added in version 3.12.
field_specifiers (tuple[Callable[..., Any], ...]) -- dataclasses.field() と同じようにフィールドを記述する、対応可能なクラスや関数の静的なリストを指定します。デフォルトは () です。
**kwargs (Any) -- 将来の拡張を可能にするために、他の任意のキーワード引数も受け取れます。

型チェッカーは、フィールド指定子の以下の省略可能なパラメータを認識します:

**フィールド指定子で認識されるパラメータ**¶
パラメータ名	説明
`init`	自動生成される `__init__` メソッドにフィールドを含めるかどうかを示します。指定しなければ、`init` のデフォルトは `True` です。
`default`	フィールドのデフォルト値を指定します。
`default_factory`	実行時にフィールドのデフォルト値を返すコールバックを指定します。 `default` も `default_factory` も指定しない場合、フィールドにはデフォルト値がないものとみなされ、クラスのインスタンス化時に値を渡す必要があります。
`factory`	フィールド指定子の `default_factory` パラメータのエイリアスです。
`kw_only`	Indicates whether the field should be marked as keyword-only. If `True`, the field will be keyword-only. If `False`, it will not be keyword-only. If unspecified, the value of the `kw_only` parameter on the object decorated with `@dataclass_transform` will be used, or if that is unspecified, the value of `kw_only_default` on `@dataclass_transform` will be used.
`alias`	フィールドの別名を指定します。この別名は、自動生成される `__init__` メソッドで使われます。

実行時には、このデコレータは引数をデコレートしたオブジェクトの __dataclass_transform__ 属性に記録します。それ以外の実行時の効果はありません。

より詳しくは PEP 681 を参照してください。

Added in version 3.11.

@typing.overload¶

オーバーロードされた関数やメソッドを作成するデコレータです。

@overload デコレータは、引数の型の複数の組み合わせに対応する関数やメソッドを記述できます。一連の @overload 付き定義の後には、同じ関数またはメソッドの @overload のない定義を 1 つだけ置く必要があります。

@overload 付きの定義は、その後の @overload のない定義で上書きされるため、型チェッカーのためだけに使われます。一方、@overload のない定義は実行時に使われますが、型チェッカーは呼び出しに対応するシグネチャの判定ではこの定義を使いません。実行時に @overload 付きの関数を直接呼び出すと、NotImplementedError が発生します。

ユニオンや型変数では表現できない、より正確な型をオーバーロードで記述する例です:

@overload
def process(response: None) -> None:
    ...
@overload
def process(response: int) -> tuple[int, str]:
    ...
@overload
def process(response: bytes) -> str:
    ...
def process(response):
    ...  # 実際の実装をここに書く

詳細と他の型付け意味論との比較は PEP 484 を参照してください。

バージョン 3.11 で変更: get_overloads() を使い、実行時にオーバーロードされた関数を調べられるようになりました。

typing.get_overloads(func)¶

Return a sequence of @overload-decorated definitions for func.

func is the function object for the implementation of the overloaded function. For example, given the definition of process in the documentation for @overload, get_overloads(process) will return a sequence of three function objects for the three defined overloads. If called on a function with no overloads, get_overloads() returns an empty sequence.

get_overloads() は、実行時にオーバーロードされた関数を調べるために使えます。

Added in version 3.11.

typing.clear_overloads()¶

内部レジストリに登録されたすべてのオーバーロードを消去します。

レジストリが使用するメモリを解放するために使えます。

Added in version 3.11.

@typing.final¶

メソッドやクラスが final であることを示すデコレータです。

メソッドを @final でデコレートすると、サブクラスでオーバーライドできないことを型チェッカーに伝えます。クラスを @final でデコレートすると、サブクラスを作成できないことを伝えます。

例えば:

class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # 型チェッカーがエラーを報告する
        ...

@final
class Leaf:
    ...
class Other(Leaf):  # 型チェッカーがエラーを報告する
    ...

この機能は実行時には検査されません。詳細については PEP 591 を参照してください。

Added in version 3.8.

バージョン 3.11 で変更: このデコレータは、デコレートしたオブジェクトの __final__ 属性を True に設定しようとするようになりました。そのため、実行時に if getattr(obj, "__final__", False) などの検査で、オブジェクト obj が final と指定されているかどうかを調べられます。デコレートしたオブジェクトが属性の設定に対応していなければ、例外を送出せずにそのオブジェクトをそのまま返します。

@typing.no_type_check¶

アノテーションが型ヒントでないことを示すデコレータです。

クラスまたは関数のデコレータとして使えます。クラスの場合、そのクラス内で定義されたすべてのメソッドとクラスに再帰的に適用されます (スーパークラスやサブクラスで定義されたメソッドには適用されません)。型チェッカーは、このデコレータを付けた関数やクラスのすべてのアノテーションを無視します。

@no_type_check は、デコレートしたオブジェクトをインプレースに変更します。

@typing.no_type_check_decorator¶

別のデコレータに no_type_check() の効果を与えるデコレータです。

これは何かの関数をラップするデコレータを no_type_check() でラップします。

Deprecated since version 3.13, will be removed in version 3.15: No type checker ever added support for @no_type_check_decorator. It is therefore deprecated, and will be removed in Python 3.15.

@typing.override¶

サブクラスのメソッドが、スーパークラスのメソッドや属性をオーバーライドする意図を示すデコレータです。

@override でデコレートされたメソッドが実際には何もオーバーライドしていなければ、型チェッカーはエラーを報告すべきです。これにより、基底クラスを変更したのに子クラスに対応する変更を加えなかった場合のバグを防ぎやすくなります。

例えば:

class Base:
    def log_status(self) -> None:
        ...

class Sub(Base):
    @override
    def log_status(self) -> None:  # OK: Base.log_status をオーバーライドする
        ...

    @override
    def done(self) -> None:  # 型チェッカーがエラーを報告する
        ...

この性質は実行時には検査されません。

このデコレータは、デコレートしたオブジェクトの __override__ 属性を True に設定しようとします。そのため、実行時に if getattr(obj, "__override__", False) などの検査で、オブジェクト obj がオーバーライドと指定されているかどうかを調べられます。デコレートしたオブジェクトが属性の設定に対応していなければ、例外を送出せずにそのオブジェクトをそのまま返します。

詳細は PEP 698 を参照してください。

Added in version 3.12.

@typing.type_check_only¶

クラスや関数が実行時には使えないことを示すデコレータです。

このデコレータ自身は実行時には使えません。このデコレータは主に、実装がプライベートクラスのインスタンスを返す場合に、型スタブファイルに定義されているクラスに対して印を付けるためのものです:

@type_check_only
class Response:  # プライベート、または実行時には利用できない
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...

プライベートクラスのインスタンスを返すのは推奨されません。そのようなクラスは公開クラスにするのが望ましいです。

イントロスペクション用のヘルパー¶

typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False)¶

関数、メソッド、モジュールまたはクラスのオブジェクトの型ヒントを含む辞書を返します。

This is often the same as obj.__annotations__, but this function makes the following changes to the annotations dictionary:

文字列リテラルや ForwardRef オブジェクトとして記述された前方参照は、globalns、localns、該当する場合は obj の型引数の名前空間で評価して処理します。 globalns や localns を指定しなければ、obj から適切な名前空間の辞書を推定します。
None を types.NoneType に置き換えます。
If @no_type_check has been applied to obj, an empty dictionary is returned.
If obj is a class C, the function returns a dictionary that merges annotations from C's base classes with those on C directly. This is done by traversing C.__mro__ and iteratively combining __annotations__ dictionaries. Annotations on classes appearing earlier in the method resolution order always take precedence over annotations on classes appearing later in the method resolution order.
The function recursively replaces all occurrences of Annotated[T, ...], Required[T], NotRequired[T], and ReadOnly[T] with T, unless include_extras is set to True (see Annotated for more information).

See also inspect.get_annotations(), a lower-level function that returns annotations more directly.

注釈

If any forward references in the annotations of obj are not resolvable or are not valid Python code, this function will raise an exception such as NameError. For example, this can happen with imported type aliases that include forward references, or with names imported under if TYPE_CHECKING.

バージョン 3.9 で変更: PEP 593 の一部として include_extras パラメータを追加しました。詳細は Annotated のドキュメントを参照してください。

バージョン 3.11 で変更: 以前は、関数やメソッドの引数に None と等しいデフォルト値が設定されていると、アノテーションに Optional[t] が追加されていました。現在はアノテーションを変更せずに返します。

typing.get_origin(tp)¶

型から添字を取り除いたものを取得します。 X[Y, Z, ...] の形式の型付けオブジェクトに対して X を返します。

X が、組み込みクラスや collections のクラスに対する typing モジュールのエイリアスなら、元のクラスに正規化します。 X が ParamSpecArgs または ParamSpecKwargs のインスタンスなら、元の ParamSpec を返します。対応していないオブジェクトでは None を返します。

例:

assert get_origin(str) is None
assert get_origin(Dict[str, int]) is dict
assert get_origin(Union[int, str]) is Union
assert get_origin(Annotated[str, "metadata"]) is Annotated
P = ParamSpec('P')
assert get_origin(P.args) is P
assert get_origin(P.kwargs) is P

Added in version 3.8.

typing.get_args(tp)¶

すべての代入を適用した型引数を取得します。 X[Y, Z, ...] の形式の型付けオブジェクトに対して (Y, Z, ...) を返します。

X が他のジェネリック型の中に含まれるユニオンまたは Literal の場合、型のキャッシュにより、 (Y, Z, ...) の順序が元の引数 [Y, Z, ...] の順序と異なる場合があります。対応していないオブジェクトでは () を返します。

例:

assert get_args(int) == ()
assert get_args(Dict[int, str]) == (int, str)
assert get_args(Union[int, str]) == (int, str)

Added in version 3.8.

typing.get_protocol_members(tp)¶

Protocol に定義されたメンバーの集合を返します。

>>> from typing import Protocol, get_protocol_members
>>> class P(Protocol):
...     def a(self) -> str: ...
...     b: int
>>> get_protocol_members(P) == frozenset({'a', 'b'})
True

引数がプロトコルでなければ TypeError を送出します。

Added in version 3.13.

typing.is_protocol(tp)¶

型が Protocol であるかどうかを判定します。

例えば:

class P(Protocol):
    def a(self) -> str: ...
    b: int

assert is_protocol(P)
assert not is_protocol(int)

This function only returns true for Protocol classes, not for generic aliases of them:

class GenericP[T](Protocol):
    def a(self) -> T: ...
    b: int

assert not is_protocol(GenericP[int])

Added in version 3.13.

typing.is_typeddict(tp)¶

型が TypedDict であるかどうかを調べます。

例えば:

class Film(TypedDict):
    title: str
    year: int

assert is_typeddict(Film)
assert not is_typeddict(list | str)

# TypedDict は型付き辞書を作成するファクトリであり、
# それ自体が型付き辞書ではない
assert not is_typeddict(TypedDict)

This function only returns true for TypedDict classes, not for generic aliases of them:

class GenericFilm[T](TypedDict):
    title: str
    year: T

assert not is_typeddict(GenericFilm[int])

Added in version 3.10.

class typing.ForwardRef¶

文字列の前方参照を型付けの内部で表現するためのクラスです。

For example, List["SomeClass"] is implicitly transformed into List[ForwardRef("SomeClass")]. ForwardRef should not be instantiated by a user, but may be used by introspection tools.

注釈

PEP 585 generic types such as list["SomeClass"] will not be implicitly transformed into list[ForwardRef("SomeClass")] and thus will not automatically resolve to list[SomeClass].

Added in version 3.7.4.

typing.NoDefault¶

型引数にデフォルト値がないことを示すセンチネルオブジェクトです。例えば次のように使います:

>>> T = TypeVar("T")
>>> T.__default__ is typing.NoDefault
True
>>> S = TypeVar("S", default=None)
>>> S.__default__ is None
True

Added in version 3.13.

定数¶

typing.TYPE_CHECKING¶

A special constant that is assumed to be True by static type checkers. It is False at runtime.

使い方:

if TYPE_CHECKING:
    import expensive_mod

def fun(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()

The first type annotation must be enclosed in quotes, making it a "forward reference", to hide the expensive_mod reference from the interpreter runtime. Type annotations for local variables are not evaluated, so the second annotation does not need to be enclosed in quotes.

注釈

from __future__ import annotations が使われた場合、アノーテーションは関数定義時に評価されません。代わりにアノーテーションは __annotations__ 属性に文字列として保存されます。これによりアノーテーションをシングルクォートで囲む必要がなくなります (PEP 563 を参照してください)。

Added in version 3.5.2.

非推奨のエイリアス¶

このモジュールは、既存の標準ライブラリクラスに対する非推奨のエイリアスをいくつか定義しています。これらは、ジェネリッククラスを [] でパラメータ化できるようにするため、元々 typing モジュールに追加されました。しかし Python 3.9 で、対応する既存クラスが [] に対応したため、エイリアスは不要になりました (PEP 585 を参照)。

これらの不要になった型は Python 3.9 以降、非推奨です。ただし、将来削除される可能性はあるものの、現時点では削除予定はありません。そのため、これらのエイリアスについてインタープリタは現在、非推奨警告を出していません。

将来、これらの非推奨エイリアスを削除すると決まった場合は、削除の少なくとも 2 リリース前からインタープリタが非推奨警告を出すことになります。少なくとも Python 3.14 までは、非推奨警告なしで typing モジュールに残ることが保証されています。

検査対象のプログラムが Python 3.9 以降を最低対応バージョンとしている場合、型チェッカーは非推奨の型の使用を報告することが推奨されます。

組み込み型のエイリアス¶

class typing.Dict(dict, MutableMapping[KT, VT])¶

dict の非推奨なエイリアス。

引数のアノテーションには、dict や typing.Dict よりも、Mapping などの抽象コレクション型を使う方が望ましいことに注意してください。

バージョン 3.9 で非推奨: builtins.dict は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.List(list, MutableSequence[T])¶

list の非推奨なエイリアス。

引数のアノテーションには、list や typing.List よりも、Sequence や Iterable などの抽象コレクション型を使う方が望ましいことに注意してください。

バージョン 3.9 で非推奨: builtins.list は添字表記 ([]) をサポートするようになりました。PEP 585 と Generic Alias Type を参照してください。

class typing.Set(set, MutableSet[T])¶

builtins.set の非推奨のエイリアスです。

引数のアノテーションには、set や typing.Set よりも、collections.abc.Set などの抽象コレクション型を使う方が望ましいことに注意してください。

バージョン 3.9 で非推奨: builtins.set は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.FrozenSet(frozenset, AbstractSet[T_co])¶: builtins.frozenset の非推奨のエイリアスです。

バージョン 3.9 で非推奨: builtins.frozenset は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

typing.Tuple¶

tuple の非推奨なエイリアス。

tuple と Tuple は型システムで特別に扱われます。詳細はタプルのアノテーションを参照してください。

バージョン 3.9 で非推奨: builtins.tuple は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Type(Generic[CT_co])¶

type の非推奨なエイリアス。

型アノテーションで type や typing.Type を使う方法の詳細は、クラスオブジェクトの型を参照してください。

Added in version 3.5.2.

バージョン 3.9 で非推奨: builtins.type は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

`collections` の型のエイリアス¶

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])¶: collections.defaultdict の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.defaultdict は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])¶: collections.OrderedDict の非推奨なエイリアス。

Added in version 3.7.2.

バージョン 3.9 で非推奨: collections.OrderedDict は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])¶: collections.ChainMap の非推奨なエイリアス。

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.ChainMap は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Counter(collections.Counter, Dict[T, int])¶: collections.Counter の非推奨なエイリアス。

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.Counter は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Deque(deque, MutableSequence[T])¶: collections.deque の非推奨なエイリアス。

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.deque は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

その他の具象型のエイリアス¶

class typing.Pattern¶

class typing.Match¶

Deprecated aliases corresponding to the return types from re.compile() and re.match().

これらの型 (および対応する関数) は AnyStr を型引数とするジェネリックです。 Pattern は Pattern[str] または Pattern[bytes] に、Match は Match[str] または Match[bytes] に特殊化できます。

バージョン 3.9 で非推奨: re の Pattern クラスと Match クラスが [] に対応しました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Text¶

str の非推奨のエイリアスです。

Text は Python 2 のコードに前方互換性を持たせるために提供されています。 Python 2 では Text は unicode のエイリアスです。

Python 2 と Python 3 の両方に対応する形で、値が Unicode 文字列でなければならないことを示すには Text を使います。

def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'

Added in version 3.5.2.

バージョン 3.11 で非推奨: Python 2 のサポートは終了しており、ほとんどの型チェッカーも Python 2 コードの型チェックに対応しなくなりました。このエイリアスの削除予定は現時点ではありませんが、Text の代わりに str を使うことが推奨されます。

`collections.abc` のコンテナ抽象基底クラスのエイリアス¶

class typing.AbstractSet(Collection[T_co])¶: collections.abc.Set の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Set は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.ByteString(Sequence[int])¶

Deprecated alias to collections.abc.ByteString.

Use isinstance(obj, collections.abc.Buffer) to test if obj implements the buffer protocol at runtime. For use in type annotations, either use Buffer or a union that explicitly specifies the types your code supports (e.g., bytes | bytearray | memoryview).

ByteString was originally intended to be an abstract class that would serve as a supertype of both bytes and bytearray. However, since the ABC never had any methods, knowing that an object was an instance of ByteString never actually told you anything useful about the object. Other common buffer types such as memoryview were also never understood as subtypes of ByteString (either at runtime or by static type checkers).

See PEP 688 for more details.

Deprecated since version 3.9, will be removed in version 3.17.

class typing.Collection(Sized, Iterable[T_co], Container[T_co])¶: collections.abc.Collection の非推奨なエイリアス。

Added in version 3.6.

バージョン 3.9 で非推奨: collections.abc.Collection は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Container(Generic[T_co])¶: collections.abc.Container の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Container は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])¶: collections.abc.ItemsView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.ItemsView は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.KeysView(MappingView, AbstractSet[KT_co])¶: collections.abc.KeysView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.KeysView は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Mapping(Collection[KT], Generic[KT, VT_co])¶: collections.abc.Mapping の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Mapping は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.MappingView(Sized)¶: collections.abc.MappingView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MappingView は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.MutableMapping(Mapping[KT, VT])¶: collections.abc.MutableMapping の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MutableMapping は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.MutableSequence(Sequence[T])¶: collections.abc.MutableSequence の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MutableSequence は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.MutableSet(AbstractSet[T])¶: collections.abc.MutableSet の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.MutableSet は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Sequence(Reversible[T_co], Collection[T_co])¶: collections.abc.Sequence の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Sequence は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.ValuesView(MappingView, Collection[_VT_co])¶: collections.abc.ValuesView の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.ValuesView は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

`collections.abc` の非同期処理用の抽象基底クラスのエイリアス¶

class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])¶

collections.abc.Coroutine の非推奨なエイリアス。

型アノテーションで collections.abc.Coroutine と typing.Coroutine を使う方法の詳細は、ジェネレータとコルーチンのアノテーションを参照してください。

Added in version 3.5.3.

バージョン 3.9 で非推奨: collections.abc.Coroutine は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])¶

collections.abc.AsyncGenerator の非推奨なエイリアス。

型アノテーションで collections.abc.AsyncGenerator と typing.AsyncGenerator を使う方法の詳細は、ジェネレータとコルーチンのアノテーションを参照してください。

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.abc.AsyncGenerator は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

バージョン 3.13 で変更: SendType 型引数にデフォルト値が追加されました。

class typing.AsyncIterable(Generic[T_co])¶: collections.abc.AsyncIterable の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.AsyncIterable は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.AsyncIterator(AsyncIterable[T_co])¶: collections.abc.AsyncIterator の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.AsyncIterator は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Awaitable(Generic[T_co])¶: collections.abc.Awaitable の非推奨なエイリアス。

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.Awaitable は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

`collections.abc` のその他の抽象基底クラスのエイリアス¶

class typing.Iterable(Generic[T_co])¶: collections.abc.Iterable の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Iterable は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Iterator(Iterable[T_co])¶: collections.abc.Iterator の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Iterator は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

typing.Callable¶

collections.abc.Callable の非推奨なエイリアス。

型アノテーションで collections.abc.Callable と typing.Callable を使う方法の詳細は、呼び出し可能オブジェクトのアノテーションを参照してください。

バージョン 3.9 で非推奨: collections.abc.Callable は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

バージョン 3.10 で変更: Callable は ParamSpec と Concatenate をサポートしました。詳細は PEP 612 を参照してください。

class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])¶

collections.abc.Generator の非推奨なエイリアス。

型アノテーションで collections.abc.Generator と typing.Generator を使う方法の詳細は、ジェネレータとコルーチンのアノテーションを参照してください。

バージョン 3.9 で非推奨: collections.abc.Generator は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

バージョン 3.13 で変更: 送信する値の型と戻り値の型にデフォルト値が追加されました。

class typing.Hashable¶: collections.abc.Hashable の非推奨なエイリアス。

バージョン 3.12 で非推奨: 代わりに collections.abc.Hashable を直接使用してください。

class typing.Reversible(Iterable[T_co])¶: collections.abc.Reversible の非推奨なエイリアス。

バージョン 3.9 で非推奨: collections.abc.Reversible は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

class typing.Sized¶: collections.abc.Sized の非推奨なエイリアス。

バージョン 3.12 で非推奨: 代わりに collections.abc.Sized を直接使用してください。

`contextlib` の抽象基底クラスのエイリアス¶

class typing.ContextManager(Generic[T_co, ExitT_co])¶

contextlib.AbstractContextManager の非推奨なエイリアス。

最初の型引数 T_co は、__enter__() メソッドが返す値の型を表します。省略可能な 2 番目の型引数 ExitT_co は、__exit__() メソッドが返す値の型を表し、デフォルトは bool | None です。

Added in version 3.5.4.

バージョン 3.9 で非推奨: contextlib.AbstractContextManager は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

バージョン 3.13 で変更: 省略可能な 2 番目の型引数 ExitT_co を追加しました。

class typing.AsyncContextManager(Generic[T_co, AExitT_co])¶

contextlib.AbstractAsyncContextManager の非推奨なエイリアス。

最初の型引数 T_co は、__aenter__() メソッドが返す値の型を表します。省略可能な 2 番目の型引数 AExitT_co は、__aexit__() メソッドが返す値の型を表し、デフォルトは bool | None です。

Added in version 3.6.2.

バージョン 3.9 で非推奨: contextlib.AbstractAsyncContextManager は添字表記 ([]) をサポートするようになりました。 PEP 585 と Generic Alias Type を参照してください。

バージョン 3.13 で変更: 省略可能な 2 番目の型引数 AExitT_co を追加しました。

メジャーな機能の非推奨時系列¶

typing の機能の中には非推奨のものがあり、Python の将来のバージョンで削除される可能性があります。以下の表は主な非推奨機能をまとめたものです。これは変更される可能性があり、すべての非推奨機能がリストされているわけではありません。

機能	非推奨となるバージョン	削除予定のバージョン	PEP/issue
標準コレクションのエイリアス	3.9	未定（非推奨のエイリアスを参照）	PEP 585
`typing.ByteString`	3.9	3.17	gh-91896
`typing.Text`	3.11	未定	gh-92332
`typing.Hashable`、`typing.Sized`	3.12	未定	gh-94309
`typing.TypeAlias`	3.12	未定	PEP 695
`@typing.no_type_check_decorator`	3.13	3.15	gh-106309
`typing.AnyStr`	3.13	3.18	gh-105578

`typing` --- 型ヒントのサポート¶

Python 型システムの仕様¶

型エイリアス¶

NewType¶

呼び出し可能オブジェクトのアノテーション¶

ジェネリクス¶

タプルのアノテーション¶

クラスオブジェクトの型¶

ジェネレータとコルーチンのアノテーション¶

ユーザー定義のジェネリック型¶

`Any` 型¶

名前的部分型 vs 構造的部分型¶

モジュールの内容¶

特殊型付けプリミティブ¶

特殊型¶

特殊形式¶

ジェネリック型と型エイリアスの構築¶

その他の特殊な指示¶

プロトコル¶

ABCs for working with IO¶

関数とデコレータ¶

イントロスペクション用のヘルパー¶

定数¶

非推奨のエイリアス¶

組み込み型のエイリアス¶

`collections` の型のエイリアス¶

その他の具象型のエイリアス¶

`collections.abc` のコンテナ抽象基底クラスのエイリアス¶

`collections.abc` の非同期処理用の抽象基底クラスのエイリアス¶

`collections.abc` のその他の抽象基底クラスのエイリアス¶

`contextlib` の抽象基底クラスのエイリアス¶

メジャーな機能の非推奨時系列¶

目次

前のトピックへ

次のトピックへ

このページ

typing --- 型ヒントのサポート¶

Python 型システムの仕様¶

型エイリアス¶

NewType¶

呼び出し可能オブジェクトのアノテーション¶

ジェネリクス¶

タプルのアノテーション¶

クラスオブジェクトの型¶

ジェネレータとコルーチンのアノテーション¶

ユーザー定義のジェネリック型¶

Any 型¶

名前的部分型 vs 構造的部分型¶

モジュールの内容¶

特殊型付けプリミティブ¶

特殊型¶

特殊形式¶

ジェネリック型と型エイリアスの構築¶

その他の特殊な指示¶

プロトコル¶

ABCs for working with IO¶

関数とデコレータ¶

イントロスペクション用のヘルパー¶

定数¶

非推奨のエイリアス¶

組み込み型のエイリアス¶

collections の型のエイリアス¶

その他の具象型のエイリアス¶

collections.abc のコンテナ抽象基底クラスのエイリアス¶

collections.abc の非同期処理用の抽象基底クラスのエイリアス¶

collections.abc のその他の抽象基底クラスのエイリアス¶

contextlib の抽象基底クラスのエイリアス¶

メジャーな機能の非推奨時系列¶

`typing` --- 型ヒントのサポート¶

`Any` 型¶

`collections` の型のエイリアス¶

`collections.abc` のコンテナ抽象基底クラスのエイリアス¶

`collections.abc` の非同期処理用の抽象基底クラスのエイリアス¶

`collections.abc` のその他の抽象基底クラスのエイリアス¶

`contextlib` の抽象基底クラスのエイリアス¶