`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 バージョンからもその新機能を使うことができます。

参考

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

Python 型システムの仕様¶

最新の正式な Python 型システムの仕様は 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

添字表記には必ず２つの値、すなわち引数のリストと返り値の型を指定する必要があります。引数のリストは型のリスト、ParamSpec、Concatenate、ellipsis (...) のいずれかでなければなりません。返り値の型は単一の型でなければなりません。

もし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)

タプルの長さが可変で、すべての要素が同じ型 T であるということを表すには、リテラルの ellipsis ... を使って tuple[T, ...] と表現します。空のタプルを表すには tuple[()] を使います。型アノテーションとして tuple だけを指定すると 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` 型¶

Any は特殊な型です。静的型チェッカーは、すべての型から Any へ代入でき、Any からすべての型へ代入できるものとして扱います。

これは、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:
    # 型チェックに失敗する。
    # object に 'magic' メソッドはない。
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # 型チェックを通過する
    item.magic()
    ...

# int と str は object のサブクラスなので型チェックを通過する
hash_a(42)
hash_a("foo")

# Any はすべての型へ代入できるので型チェックを通過する
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 は、上記のコードでクラス定義に基底クラスを明示しなくてもよいようにすることで、この問題を解決します。静的型チェッカーは Bucket を暗黙的に Sized と Iterable[int] の両方のサブタイプとみなせます。これを 構造的部分型 (または静的ダックタイピング) と呼びます。

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¶

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

すべての型から Any へ代入できます。
Any からすべての型へ代入できます。

バージョン 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!"

バージョン 3.13 で非推奨、バージョン 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 文への移行が推奨されます。

特殊形式¶

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

class 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型の表現を参照ください。

バージョン 3.14 で変更: types.UnionType は Union のエイリアスとなり、Union[int, str] と int | str は同じクラスのインスタンスを作成するようになりました。実行時にオブジェクトが Union かどうかを調べるには、isinstance(obj, Union) を使ってください。以前のバージョンの Python との互換性を保つには、get_origin(obj) is typing.Union or get_origin(obj) is types.UnionType を使ってください。

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 は Callable や ParamSpec と組み合わせて、他の呼び出し可能オブジェクトのパラメータを追加、削除、変換する高階の呼び出し可能オブジェクトをアノテーションできます。 Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable] の形式で使用します。 Concatenate は、Callable の型ヒント内と、ParamSpec を型引数に持つユーザー定義のジェネリッククラスのインスタンス化で使用できます。 Concatenate の最後の引数は ParamSpec または 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 自体はクラスではなく、isinstance() や issubclass() では使えません。 ClassVar は Python の実行時の動作を変えませんが、静的型チェッカーが利用できます。例えば、型チェッカーは以下のコードをエラーとして報告する場合があります。

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  # 許可される
   m["title"] = "The Matrix"  # 型チェッカーのエラー

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

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

Added in version 3.13.

typing.Annotated¶

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

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

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

アノテーションに Annotated[T, x] を使っても、型チェッカーはメタデータ x を無視するため、T の静的型チェックは引き続き行えます。この点で Annotated は @no_type_check デコレータと異なります。後者も型システムの範囲外のアノテーションを追加するために使えますが、関数やクラスの型チェックを完全に無効にします。

メタデータをどう解釈するかは、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.TypeForm¶

型を表す式を評価した結果の値を表す特殊形式です。

この値は型を表す式で与えられた情報を保持し、その型を表す式が記述する型を表します。

型を表す式で使用した場合、TypeForm は型形式オブジェクトの集合を記述します。型引数を 1 つ受け取り、その引数は有効な型を表す式でなければなりません。 TypeForm[T] は、型 T または T に代入可能な型を表すすべての型形式オブジェクトの集合を記述します。

TypeForm(obj) は単に obj をそのまま返します。静的型チェッカーに対して、値を型形式として明示するのに役立ちます。

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

from typing import Any, TypeForm

def cast[T](typ: TypeForm[T], value: Any) -> T: ...

reveal_type(cast(int, "x"))  # 表示される型は "int"

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

Added in version 3.15.

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 で変更: 型引数構文で作成された型変数では、上限は型変数の作成時には評価されず、属性へのアクセス時に初めて評価されます (遅延評価を参照)。

evaluate_bound()¶: __bound__ 属性に対応する評価関数です。このメソッドを直接呼び出す場合は VALUE 形式だけに対応しており、__bound__ 属性に直接アクセスするのと同じです。ただし、メソッドオブジェクトを annotationlib.call_evaluate_function() に渡すと、別の形式で値を評価できます。

Added in version 3.14.

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

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

evaluate_constraints()¶: __constraints__ 属性に対応する評価関数です。このメソッドを直接呼び出す場合は VALUE 形式だけに対応しており、__constraints__ 属性に直接アクセスするのと同じです。ただし、メソッドオブジェクトを annotationlib.call_evaluate_function() に渡すと、別の形式で値を評価できます。

Added in version 3.14.

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

Added in version 3.13.

evaluate_default()¶: __default__ 属性に対応する評価関数です。このメソッドを直接呼び出す場合は VALUE 形式だけに対応しており、__default__ 属性に直接アクセスするのと同じです。ただし、メソッドオブジェクトを annotationlib.call_evaluate_function() に渡すと、別の形式で値を評価できます。

Added in version 3.14.

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

Added in version 3.13.

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

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

class typing.TypeVarTuple(name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, 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__¶: 型変数タプルの名前です。

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

Added in version 3.15.

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

Added in version 3.15.

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

Added in version 3.15.

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

Added in version 3.13.

evaluate_default()¶: __default__ 属性に対応する評価関数です。このメソッドを直接呼び出す場合は VALUE 形式だけに対応しており、__default__ 属性に直接アクセスするのと同じです。ただし、メソッドオブジェクトを annotationlib.call_evaluate_function() に渡すと、別の形式で値を評価できます。

Added in version 3.14.

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

Added in version 3.13.

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

Added in version 3.11.

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

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

バージョン 3.15 で変更: bound、covariant、contravariant、infer_variance パラメータに対応しました。

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__¶: パラメータ仕様の名前です。

__covariant__¶: パラメータ仕様が明示的に共変と指定されているかどうかです。

__contravariant__¶: パラメータ仕様が明示的に反変と指定されているかどうかです。

__infer_variance__¶: 型チェッカーがパラメータ仕様の変性を推論するかどうかです。

Added in version 3.12.

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

Added in version 3.13.

evaluate_default()¶: __default__ 属性に対応する評価関数です。このメソッドを直接呼び出す場合は VALUE 形式だけに対応しており、__default__ 属性に直接アクセスするのと同じです。ただし、メソッドオブジェクトを annotationlib.call_evaluate_function() に渡すと、別の形式で値を評価できます。

Added in version 3.14.

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=(), qualname=None)¶

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

例:

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

Added in version 3.12.

__name__¶

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

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

__qualname__¶

型エイリアスの修飾名です:

>>> class Class:
...     type Alias = int
...
>>> Class.Alias.__qualname__
'Class.Alias'

Added in version 3.15.

__module__¶

型エイリアスが定義されたモジュールの名前です。

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

この属性には書き込めます。

バージョン 3.15 で変更: この属性に書き込めるようになりました。

__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

evaluate_value()¶

__value__ 属性に対応する評価関数です。このメソッドを直接呼び出す場合は VALUE 形式だけに対応しており、__value__ 属性に直接アクセスするのと同じです。ただし、メソッドオブジェクトを annotationlib.call_evaluate_function() に渡すと、別の形式で値を評価できます:

>>> type Alias = undefined
>>> Alias.__value__
Traceback (most recent call last):
...
NameError: name 'undefined' is not defined
>>> from annotationlib import Format, call_evaluate_function
>>> Alias.evaluate_value(Format.VALUE)
Traceback (most recent call last):
...
NameError: name 'undefined' is not defined
>>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)
ForwardRef('undefined')

Added in version 3.14.

展開

型エイリアスは *Alias 構文によるアスタリスクでの展開に対応しています。これは Unpack[Alias] を直接使うのと同じです:

>>> type Alias = tuple[int, str]
>>> type Unpacked = tuple[bool, *Alias]
>>> Unpacked.__value__
tuple[bool, typing.Unpack[Alias]]

Added in version 3.14.

その他の特殊な指示¶

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

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

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

作成されたクラスに対して annotationlib.get_annotations() を呼び出すと、各フィールドの型を取得できます。フィールド名は _fields 属性、デフォルト値は _field_defaults 属性に格納されており、どちらも 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 はクラスではなく関数になりました。上で説明したように、引き続き基底クラスとして使えます。

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

バージョン 3.14 で変更: NamedTuple サブクラスのメソッド内での super() (および __class__ クロージャ変数) の使用には対応しておらず、TypeError が発生します。

class typing.NewType(name, tp)¶

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

型チェッカーは NewType を別個の型とみなします。ただし、実行時に NewType を呼び出すと、引数をそのまま返します。

使い方:

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

__module__¶: 新しい型が定義されたモジュールの名前です。

__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.

バージョン 3.15 で非推奨、バージョン 3.20 で削除予定: runtime_checkable() で明示的にデコレートされていないものの、実行時検査可能なプロトコルクラスを継承しているプロトコルクラスに対して、 isinstance() や issubclass() で検査することは非推奨です。 Python 3.20 では TypeError が発生するようになります。

@typing.runtime_checkable¶

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

このようなプロトコルは isinstance() や issubclass() で使えます。これにより、collections.abc の Iterable など、 1 つのメソッドを対象とするクラスとよく似た単純な構造検査ができます。例えば次のようになります。

@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)

Runtime checkability of protocols is not inherited. A subclass of a runtime-checkable protocol is only runtime-checkable if it is explicitly marked as such, regardless of class hierarchy:

@runtime_checkable
class Iterable(Protocol):
    def __iter__(self): ...

# Without @runtime_checkable, Reversible would no longer be runtime-checkable.
@runtime_checkable
class Reversible(Iterable, Protocol):
    def __reversed__(self): ...

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

注釈

@runtime_checkable は必要なメソッドや属性の存在だけを調べ、その型シグネチャや型は調べません。例えば ssl.SSLObject はクラスなので、Callable に対する issubclass() の検査を通過します。しかし、ssl.SSLObject.__init__ メソッドは、より詳しいメッセージを伴う TypeError を送出するためだけに存在するため、 ssl.SSLObject を呼び出す (インスタンス化する) ことはできません。

注釈

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

Added in version 3.8.

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

バージョン 3.12 で変更: 実行時検査可能なプロトコルのメンバーは、実行時にクラスが作成されるとすぐに「凍結」されたものとみなされるようになりました。実行時検査可能なプロトコルにモンキーパッチで属性を追加することは引き続き可能ですが、オブジェクトがそのプロトコルに適合するかを調べる isinstance() の検査には影響しません。詳細は Python 3.12 の新機能を参照してください。

バージョン 3.15 で非推奨、バージョン 3.20 で削除予定: runtime_checkable() で明示的にデコレートされていないものの、実行時検査可能なプロトコルクラスを継承しているプロトコルクラスに対して、 isinstance() や issubclass() で検査することは非推奨です。 Python 3.20 では TypeError が発生するようになります。

class typing.TypedDict(dict)¶

辞書に型ヒントを追加するための特殊な構築子です。実行時には「TypedDict のインスタンス」は単なる dict です。

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 は開いており、実行時にクラス本体で定義したもの以外のキーも持てます。クラスの引数 closed でこの動作を制御できます。 closed=True の場合、TypedDict は追加のキーを持てません。

class ClosedPoint(TypedDict, closed=True):
    x: int
    y: int

class ClosedPoint3D(ClosedPoint):  # 型チェッカーのエラー: 閉じた TypedDict にキーは追加できない
    z: int

closed=False を指定すると、デフォルトの開いた動作を明示的に要求します。この引数を指定しなければ、親クラスの状態を継承します。

TypedDict は、開いているか閉じているかに加え、追加項目を持つように設定することもできます。クラスの引数 extra_items に型を設定すると、TypedDict は任意の追加キーを持てますが、それらのキーの値は指定した型でなければなりません。

class ExtraItemsPoint(TypedDict, extra_items=int):
    x: int
    y: int

point: ExtraItemsPoint = {'x': 1, 'y': 2, 'anything': 3}  # OK

extra_items 引数もサブクラスに継承されます。デフォルトでは未設定で、closed 引数とは併用できません。

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]

TypedDict のイントロスペクションには annotationlib.get_annotations() と以下の属性を使えます (アノテーションのベストプラクティスについてはアノテーションのベストプラクティスを参照):

__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__ に含まれます。

Python 3.10 以前との後方互換性のために、継承を使って同じ TypedDict に必須のキーと必須でないキーを宣言することもできます。まず total 引数にある値を指定した TypedDict を宣言し、それを継承した別の TypedDict で 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__ が利用する実行時のイントロスペクションが正しく機能せず、属性の値が誤っている場合があります。

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

Added in version 3.13.

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

Added in version 3.13.

__closed__¶: クラスの引数 closed の値です。 True、False、None のいずれかです。

__extra_items__¶: クラスの引数 extra_items の値です。有効な型、または NoExtraItems です。

さらに例や詳しい規則を知りたい場合は、型付けのドキュメントの TypedDict の節を参照してください。

Added in version 3.8.

バージョン 3.9 で変更: TypedDict はクラスではなく関数になりました。上で説明したように、引き続き基底クラスとして使えます。

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

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

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

バージョン 3.13 で変更: ReadOnly 修飾子に対応しました。 PEP 705 を参照してください。

バージョン 3.15 で変更: クラスの引数 closed と extra_items に対応しました。 PEP 728 を参照してください。

プロトコル¶

typing モジュールは以下のプロトコルを提供します。すべて @runtime_checkable でデコレートされています。

class typing.SupportsAbs¶: 戻り値の型について共変な、単一の抽象メソッド __abs__ を持つプロトコルです。

class typing.SupportsBytes¶: 単一の抽象メソッド __bytes__ を持つプロトコルです。

class typing.SupportsComplex¶: 単一の抽象メソッド __complex__ を持つプロトコルです。

class typing.SupportsFloat¶: 単一の抽象メソッド __float__ を持つプロトコルです。

class typing.SupportsIndex¶: 単一の抽象メソッド __index__ を持つプロトコルです。

Added in version 3.8.

class typing.SupportsInt¶: 単一の抽象メソッド __int__ を持つプロトコルです。

class typing.SupportsRound¶: 戻り値の型について共変な、単一の抽象メソッド __round__ を持つプロトコルです。

入出力を扱うための抽象基底クラスとプロトコル¶

class typing.IO[AnyStr]¶
class typing.TextIO¶
class typing.BinaryIO¶: ジェネリッククラス IO[AnyStr] と、そのサブクラス TextIO(IO[str]) および BinaryIO(IO[bytes]) は、 open() が返すものなどの入出力ストリームの型を表します。これらのクラスはプロトコルではなく、インターフェースもかなり広い範囲にわたることに注意してください。

read() または write() メソッドだけを使う場合、引数の型には、それぞれ io.Reader や io.Writer のプロトコルをより簡潔な代替手段として使えます。

def read_and_write(reader: Reader[str], writer: Writer[bytes]):
    data = reader.read()
    writer.write(data.encode())

入力ストリームの行を反復処理する場合は、collections.abc.Iterable の使用も検討してください。

def read_config(stream: Iterable[str]):
    for line in stream:
        ...

関数とデコレータ¶

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 は、クラス、メタクラス、またはそれ自体がデコレータである関数をデコレートできます。 @dataclass_transform() は、デコレートしたオブジェクトが、@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

型チェッカーは、上で定義した CustomerModel クラスを @dataclasses.dataclass で作成したクラスと同じように扱います。例えば、これらのクラスには id と name を受け取る __init__ メソッドがあるとみなします。

デコレートしたクラス、メタクラス、関数は、以下のブール値の引数を受け取れます: init、eq、order、unsafe_hash、frozen、match_args、kw_only、slots。型チェッカーは、これらが @dataclasses.dataclass デコレータに渡されたときと同じ効果を持つとみなします。これらの引数の値 (True または False) は静的に評価できなければなりません。

@dataclass_transform デコレータの引数では、デコレートしたクラス、メタクラス、関数のデフォルトの振る舞いをカスタマイズできます:

パラメータ:

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`	フィールドをキーワード専用にするかどうかを示します。 `True` ならキーワード専用となり、`False` ならキーワード専用にはなりません。指定しなければ、`@dataclass_transform` でデコレートされたオブジェクトの `kw_only` パラメータの値を使います。それも指定されていなければ、`@dataclass_transform` の `kw_only_default` の値を使います。
`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)¶

func の @overload 付き定義のシーケンスを返します。

func は、オーバーロードされた関数の実装に当たる関数オブジェクトです。例えば @overload のドキュメントの process の定義では、get_overloads(process) は定義された 3 つのオーバーロードに対応する関数オブジェクト 3 つのシーケンスを返します。オーバーロードのない関数に対して呼び出すと、get_overloads() は空のシーケンスを返します。

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.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.disjoint_base¶

クラスを disjoint base として指定するデコレータです。

型チェッカーは、disjoint base C の子クラスが、C の親クラスでも子クラスでもない別の disjoint base を継承することを許可しません。

例えば:

@disjoint_base
class Disjoint1: pass

@disjoint_base
class Disjoint2: pass

class Disjoint3(Disjoint1, Disjoint2): pass  # 型チェッカーのエラー

型チェッカーは disjoint base の情報を使って、到達不能なコードを検出したり、2 つの型に共通部分があり得るかを判定したりできます。

実行時に対応する概念は solid base です (多重継承を参照)。実行時に solid base であるクラスは、スタブファイル内で @disjoint_base を付けて示せます。それ以外のクラスも disjoint base と指定することで、他の disjoint base との多重継承を許可しない意図を型チェッカーに伝えられます。

solid base の概念は CPython の実装の詳細です。実行時に disjoint base となる標準ライブラリのクラスの正確な範囲は、将来の Python バージョンで変わる可能性があります。

Added in version 3.15.

@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, *, format=Format.VALUE)¶

関数、メソッド、モジュール、クラスオブジェクト、その他の呼び出し可能オブジェクトの型ヒントを格納した辞書を返します。

多くの場合 annotationlib.get_annotations() と同じですが、この関数はアノテーションの辞書に以下の変更を加えます:

文字列リテラルや ForwardRef オブジェクトとして記述された前方参照は、globalns、localns、該当する場合は obj の型引数の名前空間で評価して処理します。 globalns や localns を指定しなければ、obj から適切な名前空間の辞書を推定します。
None を types.NoneType に置き換えます。
obj に @no_type_check が適用されていれば、空の辞書を返します。
obj がクラス C の場合、C に直接付けられたアノテーションと、C の基底クラスのアノテーションを統合した辞書を返します。 C.__mro__ をたどり、各基底クラスのアノテーションを順に統合します。メソッド解決順序で先に現れるクラスのアノテーションは、後に現れるクラスのアノテーションより常に優先されます。
include_extras が True でなければ、Annotated[T, ...]、Required[T]、NotRequired[T]、ReadOnly[T] を、再帰的にすべて T に置き換えます (詳細は Annotated を参照)。

注意

この関数は、アノテーション内の任意のコードを実行する可能性があります。詳細はアノテーションを調べる際のセキュリティへの影響を参照してください。

注釈

Format.VALUE を使用した場合、obj のアノテーション内に解決できない前方参照があると NameError が発生します。例えば if TYPE_CHECKING の下でインポートした名前では、この状況が起こり得ます。より一般的には、アノテーションに無効な Python コードが含まれていれば、あらゆる種類の例外が発生し得ます。

注釈

インスタンスに対する get_type_hints() の呼び出しには対応していません。インスタンスのアノテーションを取得するには、そのインスタンスのクラスに対して get_type_hints() を呼び出してください (例えば get_type_hints(type(obj)))。

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

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

バージョン 3.14 で変更: format パラメータを追加しました。詳細は annotationlib.get_annotations() のドキュメントを参照してください。

バージョン 3.14 で変更: インスタンスに対する get_type_hints() の呼び出しは使えなくなりました。以前のバージョンでは、文書化されていない実装の詳細として一部のインスタンスを受け付けていました。

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)

この関数が真を返すのは Protocol クラスだけで、そのジェネリックエイリアスには真を返しません:

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)

この関数が真を返すのは TypedDict クラスだけで、そのジェネリックエイリアスには真を返しません:

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

assert not is_typeddict(GenericFilm[int])

Added in version 3.10.

class typing.ForwardRef¶

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

例えば、List["SomeClass"] は暗黙的に List[ForwardRef("SomeClass")] に変換されます。利用者が ForwardRef を直接インスタンス化するべきではありませんが、イントロスペクションツールでは利用できます。

注釈

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.

バージョン 3.14 で変更: annotationlib.ForwardRef のエイリアスになりました。このクラスの文書化されていない挙動の一部が変更されています。例えば、ForwardRef を評価した後に、評価結果がキャッシュされなくなりました。

typing.evaluate_forward_ref(forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=annotationlib.Format.VALUE)¶

annotationlib.ForwardRef を型ヒントとして評価します。

annotationlib.ForwardRef.evaluate() の呼び出しに似ていますが、evaluate_forward_ref() はそのメソッドとは異なり、型ヒント内に入れ子になった前方参照も再帰的に評価します。

owner、globals、locals、type_params、format パラメータの意味は、annotationlib.ForwardRef.evaluate() のドキュメントを参照してください。

注意

この関数は、アノテーション内の任意のコードを実行する可能性があります。詳細はアノテーションを調べる際のセキュリティへの影響を参照してください。

Added in version 3.14.

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.NoExtraItems¶

TypedDict にクラスの引数 extra_items が指定されていないことを示す sentinel オブジェクトです。

>>> from typing import TypedDict, NoExtraItems
>>> class Point(TypedDict):
...     x: int
...     y: int
...
>>> Point.__extra_items__ is NoExtraItems
True

定数¶

typing.TYPE_CHECKING¶

静的型チェッカーが True とみなす特殊な定数です。実行時には False です。

インポートのコストが高く、型アノテーションで使う型しか含まないモジュールは、if TYPE_CHECKING: ブロック内で安全にインポートできます。これにより、実行時には実際のインポートを避けられます。アノテーションは即座に評価されないため (PEP 649 を参照)、後でアノテーションを調べない限り、未定義の名前を使っても問題ありません。静的型解析ツールは解析中に TYPE_CHECKING を True とみなすので、そのモジュールは解析時にはインポートされ、型が正しく検査されます。

使い方:

if TYPE_CHECKING:
    import expensive_mod

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

未定義の名前を含むかもしれない型アノテーションを実行時に調べる必要がある場合は、 annotationlib.get_annotations() の format パラメータに annotationlib.Format.STRING または annotationlib.Format.FORWARDREF を指定してください。 NameError を起こさず安全にアノテーションを取得できます。

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 とジェネリックエイリアス型を参照してください。

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

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

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

バージョン 3.9 で非推奨: builtins.list は添字表記 ([]) をサポートするようになりました。PEP 585 とジェネリックエイリアス型を参照してください。

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

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

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

バージョン 3.9 で非推奨: builtins.set は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: builtins.frozenset は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

typing.Tuple¶

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

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

バージョン 3.9 で非推奨: builtins.tuple は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

class typing.Type(Generic[CT_co])¶

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

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

Added in version 3.5.2.

バージョン 3.9 で非推奨: builtins.type は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

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

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.defaultdict は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

Added in version 3.7.2.

バージョン 3.9 で非推奨: collections.OrderedDict は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.ChainMap は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.Counter は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

Added in version 3.6.1.

バージョン 3.9 で非推奨: collections.deque は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

class typing.Pattern¶

class typing.Match¶

re.compile() と re.search() の戻り値の型に対応する非推奨のエイリアスです。

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

バージョン 3.9 で非推奨: re の Pattern クラスと Match クラスが [] に対応しました。 PEP 585 とジェネリックエイリアス型を参照してください。

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 とジェネリックエイリアス型を参照してください。

class typing.ByteString(Sequence[int])¶

collections.abc.ByteString の非推奨のエイリアスです。

実行時に obj がバッファプロトコルを実装しているか調べるには、isinstance(obj, collections.abc.Buffer) を使ってください。型アノテーションには Buffer を使うか、コードが対応する型を明示したユニオン (例えば bytes | bytearray | memoryview) を使ってください。

ByteString は元々、bytes と bytearray の両方のスーパータイプとなる抽象クラスを意図していました。しかし、この抽象基底クラスにはメソッドがなかったため、オブジェクトが ByteString のインスタンスであると分かっても、実際には有用な情報は得られませんでした。 memoryview など、他の一般的なバッファ型も、実行時にも静的型チェッカーでも ByteString のサブタイプとはみなされていませんでした。

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

バージョン 3.9 で非推奨、バージョン 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 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.Container は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.ItemsView は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.KeysView は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.Mapping は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.MappingView は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.MutableMapping は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.MutableSequence は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.MutableSet は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.Sequence は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.ValuesView は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

`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 とジェネリックエイリアス型を参照してください。

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 とジェネリックエイリアス型を参照してください。

バージョン 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 とジェネリックエイリアス型を参照してください。

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

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.AsyncIterator は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

Added in version 3.5.2.

バージョン 3.9 で非推奨: collections.abc.Awaitable は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

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

バージョン 3.9 で非推奨: collections.abc.Iterable は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

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

バージョン 3.9 で非推奨: collections.abc.Iterator は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

typing.Callable¶

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

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

バージョン 3.9 で非推奨: collections.abc.Callable は添字表記 ([]) をサポートするようになりました。 PEP 585 とジェネリックエイリアス型を参照してください。

バージョン 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 とジェネリックエイリアス型を参照してください。

バージョン 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 とジェネリックエイリアス型を参照してください。

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 とジェネリックエイリアス型を参照してください。

バージョン 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 とジェネリックエイリアス型を参照してください。

バージョン 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.AnyStr`	3.13	3.18	gh-105578

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

Python 型システムの仕様¶

型エイリアス¶

NewType¶

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

ジェネリクス¶

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

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

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

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

`Any` 型¶

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

モジュールの内容¶

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

特殊型¶

特殊形式¶

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

その他の特殊な指示¶

プロトコル¶

入出力を扱うための抽象基底クラスとプロトコル¶

関数とデコレータ¶

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

定数¶

非推奨のエイリアス¶

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

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

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

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

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

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

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

メジャーな機能の非推奨時系列¶

目次

前のトピックへ

次のトピックへ

このページ

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

Python 型システムの仕様¶

型エイリアス¶

NewType¶

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

ジェネリクス¶

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

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

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

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

Any 型¶

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

モジュールの内容¶

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

特殊型¶

特殊形式¶

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

その他の特殊な指示¶

プロトコル¶

入出力を扱うための抽象基底クラスとプロトコル¶

関数とデコレータ¶

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

定数¶

非推奨のエイリアス¶

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

collections の型のエイリアス¶

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

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

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

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

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

メジャーな機能の非推奨時系列¶

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

`Any` 型¶

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

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

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

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

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