タイピング —タイプヒントのサポート

バージョン3.5の新機能。

ソースコード： ：source： `Lib / typing.py`

ノート

Pythonランタイムは、関数と変数の型注釈を強制しません。これらは、タイプチェッカー、IDE、リンターなどのサードパーティツールで使用できます。

このモジュールは、 PEP 484 、 PEP 526 、で指定されたタイプヒントのランタイムサポートを提供します。 PEP 544 、 PEP 586 、 PEP 589 、 PEP 591 、 PEP 612 および PEP 613 。最も基本的なサポートは、タイプ Any 、 Union 、 Tuple 、 Callable 、 TypeVar 、および[ X148X]汎用。完全な仕様については、 PEP 484 を参照してください。タイプヒントの簡単な紹介については、 PEP 483 を参照してください。

以下の関数は文字列を受け取り、返し、次のように注釈が付けられます。

def greeting(name: str) -> str:
    return 'Hello ' + name

関数greetingでは、引数nameはタイプ str であり、戻りタイプは str であると想定されています。サブタイプは引数として受け入れられます。

タイプエイリアス

タイプエイリアスは、タイプをエイリアスに割り当てることによって定義されます。この例では、Vectorとlist[float]は交換可能な同義語として扱われます。

Vector = list[float]

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

# typechecks; a list of floats qualifies as a Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

型エイリアスは、複雑な型シグネチャを単純化するのに役立ちます。例えば：

from collections.abc import Sequence

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

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

# The static type checker will treat the previous type signature as
# being exactly equivalent to this one.
def broadcast_message(
        message: str,
        servers: Sequence[tuple[tuple[str, int], dict[str, str]]]) -> None:
    ...

タイプヒントとしてのNoneは特殊なケースであり、type(None)に置き換えられることに注意してください。

新しいタイプ

NewType ヘルパークラスを使用して、個別のタイプを作成します。

from typing import NewType

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

静的型チェッカーは、新しい型を元の型のサブクラスであるかのように扱います。これは、論理エラーをキャッチするのに役立ちます。

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

# typechecks
user_a = get_user_name(UserId(42351))

# does not typecheck; an int is not a UserId
user_b = get_user_name(-1)

タイプUserIdの変数に対してすべてのint操作を実行することはできますが、結果は常にタイプintになります。これにより、intが予想される場所であればどこでも、UserIdを渡すことができますが、誤ってUserIdを無効な方法で作成することはありません。

# 'output' is of type 'int', not '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)

# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass

ただし、「派生」NewTypeに基づいて NewType を作成することは可能です。

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

ProUserIdのタイプチェックは期待どおりに機能します。

詳細については、 PEP 484 を参照してください。

ノート

タイプエイリアスを使用すると、2つのタイプが互いに同等であると宣言されることを思い出してください。 Alias = Originalを実行すると、静的型チェッカーはAliasをとOriginalとまったく同じとして扱います。これは、複雑な型の署名を単純化したい場合に役立ちます。

対照的に、NewTypeは、あるタイプを別のタイプのサブタイプとして宣言します。 Derived = NewType('Derived', Original)を実行すると、静的型チェッカーはDerivedをOriginalのサブクラスとして扱います。つまり、型Originalの値は処理できません。タイプDerivedの値が予想される場所で使用されます。これは、最小限のランタイムコストでロジックエラーを防止したい場合に役立ちます。

バージョン3.5.2の新機能。

バージョン3.10で変更： NewTypeは関数ではなくクラスになりました。通常の関数を介してNewTypeを呼び出すと、追加のランタイムコストが発生します。ただし、このコストは3.11.0で削減されます。

呼び出し可能

特定のシグニチャのコールバック関数を期待するフレームワークは、Callable[[Arg1Type, Arg2Type], ReturnType]を使用して型ヒントされる場合があります。

例えば：

from collections.abc import Callable

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

タイプヒントCallable[..., ReturnType]の引数のリストをリテラルの省略記号に置き換えることにより、呼び出しシグネチャを指定せずに呼び出し可能オブジェクトの戻り型を宣言できます。

他の呼び出し可能オブジェクトを引数として取る呼び出し可能オブジェクトは、 ParamSpec を使用してそれらのパラメーター型が相互に依存していることを示している可能性があります。さらに、その呼び出し可能オブジェクトが他の呼び出し可能オブジェクトから引数を追加または削除する場合は、連結演算子を使用できます。それらはそれぞれ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

def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

ジェネリックスは、 TypeVar と呼ばれるタイピングで利用可能な新しいファクトリを使用してパラメータ化できます。

from collections.abc import Sequence
from typing import TypeVar

T = TypeVar('T')      # Declare type variable

def first(l: Sequence[T]) -> T:   # Generic function
    return l[0]

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

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

from typing import TypeVar, Generic
from logging import Logger

T = TypeVar('T')

class LoggedVar(Generic[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)

基本クラスとしてのGeneric[T]は、クラスLoggedVarが単一の型パラメーターTを取ることを定義します。これにより、Tがクラス本体内の型として有効になります。

Generic 基本クラスは__class_getitem__()を定義し、LoggedVar[t]がタイプとして有効になるようにします。

from collections.abc import Iterable

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

ジェネリック型は任意の数の型変数を持つことができ、型変数は制約される可能性があります。

from typing import TypeVar, Generic
...

T = TypeVar('T')
S = TypeVar('S', int, str)

class StrangePair(Generic[T, S]):
    ...

Generic への各型変数引数は別個でなければなりません。したがって、これは無効です。

from typing import TypeVar, Generic
...

T = TypeVar('T')

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

Generic で多重継承を使用できます。

from collections.abc import Sized
from typing import TypeVar, Generic

T = TypeVar('T')

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

ジェネリッククラスから継承する場合、いくつかの型変数を修正できます。

from collections.abc import Mapping
from typing import TypeVar

T = TypeVar('T')

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

この場合、MyDictにはTという単一のパラメーターがあります。

タイプパラメータを指定せずにジェネリッククラスを使用すると、各位置に Any が想定されます。次の例では、MyIterableはジェネリックではありませんが、Iterable[Any]から暗黙的に継承します。

from collections.abc import Iterable

class MyIterable(Iterable): # Same as Iterable[Any]

ユーザー定義のジェネリック型エイリアスもサポートされています。例：

from collections.abc import Iterable
from typing import TypeVar
S = TypeVar('S')
Response = Iterable[S] | int

# Return type here is same as Iterable[str] | int
def response(query: str) -> Response[str]:
    ...

T = TypeVar('T', int, float, complex)
Vec = Iterable[tuple[T, T]]

def inproduct(v: Vec[T]) -> T: # Same as Iterable[tuple[T, T]]
    return sum(x*y for x, y in v)

バージョン3.7で変更： Generic にカスタムメタクラスがなくなりました。

パラメータ式のユーザー定義のジェネリックは、Generic[P]の形式のパラメータ指定変数を介してサポートされます。パラメータ仕様変数は型付けモジュールによって特殊な型変数として扱われるため、動作は上記の型変数と一致しています。これに対する1つの例外は、タイプのリストを使用して ParamSpec を置き換えることができることです。

>>> from typing import Generic, ParamSpec, TypeVar

>>> T = TypeVar('T')
>>> P = ParamSpec('P')

>>> class Z(Generic[T, P]): ...
...
>>> Z[int, [dict, float]]
__main__.Z[int, (<class 'dict'>, <class 'float'>)]

さらに、パラメータ指定変数が1つしかないジェネリックは、美的理由からXPython/docs/3.10/library/Type1, Type2, ..およびX[Type1, Type2, ...]の形式のパラメータリストを受け入れます。内部的には、後者は前者に変換されるため、同等です。

>>> class X(Generic[P]): ...
...
>>> X[int, str]
__main__.X[(<class 'int'>, <class 'str'>)]
>>> X[[../int, str]]
__main__.X[(<class 'int'>, <class 'str'>)]

ParamSpec のジェネリックは、主に静的型チェックを目的としているため、置換後に正しい__parameters__がない場合があることに注意してください。

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

ユーザー定義のジェネリッククラスは、メタクラスの競合なしに基本クラスとしてABCを持つことができます。汎用メタクラスはサポートされていません。ジェネリックスのパラメーター化の結果はキャッシュされ、タイピングモジュールのほとんどのタイプはハッシュ可能であり、同等性について比較可能です。

Any タイプ

特別な種類のタイプは Any です。静的型チェッカーは、すべての型を Any と互換性があるものとして扱います。 Any はすべての型と互換性があるものとして扱います。

これは、タイプ Any の値に対して任意の操作またはメソッド呼び出しを実行し、それを任意の変数に割り当てることができることを意味します。

from typing import Any

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

s = ''      # type: str
s = a       # OK

def foo(item: Any) -> int:
    # Typechecks; 'item' could be any type,
    # and that type might have a 'bar' method
    item.bar()
    ...

タイプ Any の値をより正確なタイプに割り当てる場合、タイプチェックは実行されないことに注意してください。たとえば、sが str 型であると宣言され、実行時の int 値！

さらに、戻り型またはパラメーター型のないすべての関数は、暗黙的にデフォルトで Any を使用します。

def legacy_parser(text):
    ...
    return data

# A static type checker will treat the above
# as having the same signature as:
def legacy_parser(text: Any) -> Any:
    ...
    return data

この動作により、動的および静的に型指定されたコードを混合する必要がある場合に、 Any をエスケープハッチとして使用できます。

Any の動作と object の動作を比較してください。 Any と同様に、すべてのタイプは object のサブタイプです。ただし、 Any とは異なり、その逆は当てはまりません。 object は not 他のすべてのタイプのサブタイプです。

つまり、値の型が object の場合、型チェッカーはその値に対するほとんどすべての操作を拒否し、より特殊な型の変数に割り当てる（または戻り値として使用する）ことはタイプエラー。例えば：

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

def hash_b(item: Any) -> int:
    # Typechecks
    item.magic()
    ...

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

# Typechecks, since Any is compatible with all types
hash_b(42)
hash_b("foo")

object を使用して、値がタイプセーフな方法で任意のタイプになり得ることを示します。 Any を使用して、値が動的に型指定されることを示します。

名目上のサブタイピングと構造的なサブタイピング

当初、 PEP 484 は、Python静的型システムを名義サブタイピングを使用するものとして定義していました。これは、AがBのサブクラスである場合にのみ、クラスBが期待されるクラスAが許可されることを意味します。

この要件は、以前は 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:  # Note: no base classes
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Passes type check

さらに、特別なクラス Protocol をサブクラス化することにより、ユーザーは新しいカスタムプロトコルを定義して、構造的なサブタイピングを十分に楽しむことができます（以下の例を参照）。

モジュールの内容

このモジュールは、次のクラス、関数、およびデコレータを定義します。

ノート

このモジュールは、 Generic を拡張して、[]内の型変数をサポートする、既存の標準ライブラリクラスのサブクラスであるいくつかの型を定義します。これらのタイプは、対応する既存のクラスが[]をサポートするように拡張されたときに、Python3.9で冗長になりました。

冗長タイプはPython3.9で非推奨になりましたが、インタープリターから非推奨の警告は発行されません。チェックされたプログラムがPython3.9以降を対象としている場合、タイプチェッカーは非推奨のタイプにフラグを立てることが期待されます。

非推奨の型は、Python3.9.0のリリースから5年後にリリースされた最初のPythonバージョンの typing モジュールから削除されます。詳細については、 PEP 585 — 標準コレクションのタイプヒントジェネリックを参照してください。

特別なタイピングプリミティブ

特殊タイプ

これらは注釈の型として使用でき、[]をサポートしていません。

typing.Any: 拘束されていないタイプを示す特殊タイプ。

すべてのタイプは Any と互換性があります。 Any はすべてのタイプと互換性があります。

typing.NoReturn

関数が戻らないことを示す特殊なタイプ。例えば：

from typing import NoReturn

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

バージョン3.5.4の新機能。

バージョン3.6.2の新機能。

typing.TypeAlias

タイプエイリアスを明示的に宣言するための特別なアノテーション。例えば：

from typing import TypeAlias

Factors: TypeAlias = list[int]

明示的な型エイリアスの詳細については、 PEP 613 を参照してください。

バージョン3.10の新機能。

特別なフォーム

これらは、[]を使用して注釈の型として使用でき、それぞれに固有の構文があります。

typing.Tuple

タプルタイプ; Tuple[X, Y]は、タイプXの最初のアイテムとタイプYの2番目のアイテムを持つ2つのアイテムのタプルのタイプです。空のタプルのタイプは、Tuple[()]と書くことができます。

例：Tuple[T1, T2]は、型変数T1およびT2に対応する2つの要素のタプルです。 Tuple[int, float, str]は、int、float、およびstringのタプルです。

同種タイプの可変長タプルを指定するには、リテラルの省略記号を使用します。 Tuple[int, ...]。プレーンなタプルはTuple[Any, ...]と同等であり、タプルと同等です。

バージョン3.9以降非推奨： builtins.tuple は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

typing.Union

共用体タイプ; Union[X, Y]はX | Yと同等であり、XまたはYのいずれかを意味します。

和集合を定義するには、例えば Union[int, str]または省略形int | str。詳細：

引数は型である必要があり、少なくとも1つ存在する必要があります。
ユニオンのユニオンはフラット化されます。例：
```
Union[Union[int, str], float] == Union[int, str, float]
```

単一の引数の結合は消えます。例：

Union[int] == int  # The constructor actually returns 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と記述できるようになりました。共用体型式を参照してください。

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で変更：オプションをX | Noneと記述できるようになりました。共用体型式を参照してください。

typing.Callable

呼び出し可能なタイプ。 Callable[[int], str]は（int）-> strの関数です。

サブスクリプション構文は、常に引数リストと戻り型の2つの値で使用する必要があります。引数リストは、タイプのリストまたは省略記号である必要があります。戻り型は単一の型である必要があります。

オプションまたはキーワード引数を示す構文はありません。このような関数型がコールバック型として使用されることはめったにありません。 Callable[..., ReturnType]（リテラル省略記号）を使用して、任意の数の引数を取り、ReturnTypeを返すcallableのヒントを入力できます。プレーンな Callable は、Callable[..., Any]と同等であり、 collections.abc.Callable と同等です。

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

バージョン3.9以降非推奨： collections.abc.Callable は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

バージョン3.10で変更： Callableは ParamSpec および Concatenate をサポートするようになりました。詳細については、 PEP 612 を参照してください。

も参照してください

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

typing.Concatenate

Callable および ParamSpec とともに使用して、別の呼び出し可能パラメーターのパラメーターを追加、削除、または変換する高次呼び出し可能に型注釈を付けます。使用法はConcatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]の形式です。 Concatenateは現在、 Callable の最初の引数として使用された場合にのみ有効です。 Concatenateの最後のパラメーターは、 ParamSpec である必要があります。

たとえば、 threading.Lock をデコレートされた関数に提供するデコレータwith_lockに注釈を付けるには、Concatenateを使用して、with_lockがLockを最初の引数として受け取り、異なる型シグネチャを持つcallableを返すcallable。この場合、 ParamSpec は、返されるcallableのパラメーター型が、渡されるcallableのパラメーター型に依存していることを示します。

from collections.abc import Callable
from threading import Lock
from typing import Any, Concatenate, ParamSpec, TypeVar

P = ParamSpec('P')
R = TypeVar('R')

# Use this lock to ensure that only one thread is executing a function
# at any time.
my_lock = Lock()

def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''A type-safe decorator which provides a lock.'''
    global my_lock
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # Provide the lock as the first argument.
        return f(my_lock, *args, **kwargs)
    return inner

@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''Add a list of numbers together in a thread-safe manner.'''
    with lock:
        return sum(numbers)

# We don't need to pass in the lock ourselves thanks to the decorator.
sum_threadsafe([1.1, 2.2, 3.3])

バージョン3.10の新機能。

も参照してください

PEP 612 –パラメーター仕様変数（ParamSpecおよびConcatenateを導入したPEP）。
ParamSpec および Callable 。

class typing.Type(Generic[CT_co])

Cで注釈が付けられた変数は、タイプCの値を受け入れることができます。対照的に、Type[C]で注釈が付けられた変数は、それ自体がクラスである値を受け入れる場合があります。具体的には、Cのクラスオブジェクトを受け入れます。例えば：

a = 3         # Has type 'int'
b = int       # Has type 'Type[int]'
c = type(a)   # Also has type 'Type[int]'

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

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

# Accepts User, BasicUser, ProUser, TeamUser, ...
def make_new_user(user_class: Type[User]) -> User:
    # ...
    return user_class()

Type[C]が共変であるという事実は、CのすべてのサブクラスがCと同じコンストラクターシグネチャーとクラスメソッドシグネチャーを実装する必要があることを意味します。タイプチェッカーは、この違反にフラグを立てる必要がありますが、指定された基本クラスのコンストラクター呼び出しと一致するサブクラスのコンストラクター呼び出しも許可する必要があります。この特定のケースを処理するためにタイプチェッカーがどのように必要とされるかは、 PEP 484 の将来のリビジョンで変更される可能性があります。

Type の唯一の有効なパラメーターは、クラス、 Any 、 type変数、およびこれらのタイプの和集合です。例えば：

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

Type[Any]はTypeと同等であり、typeはPythonのメタクラス階層のルートです。

バージョン3.5.2の新機能。

バージョン3.9以降非推奨： builtins.type は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

typing.Literal

対応する変数または関数パラメーターが、提供されたリテラル（またはいくつかのリテラルの1つ）と同等の値を持っていることを型チェッカーに示すために使用できる型。例えば：

def validate_simple(data: Any) -> Literal[True]:  # always returns True
    ...

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

open_helper('/some/path', 'r')  # Passes type check
open_helper('/other/path', 'typo')  # Error in type checker

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

バージョン3.8の新機能。

バージョン3.9.1で変更： Literalはパラメーターの重複を排除するようになりました。 Literalオブジェクトの等価比較は、順序に依存しなくなりました。 Literalオブジェクトは、パラメーターの1つが hashable でない場合、等式比較中に TypeError 例外を発生させるようになりました。

typing.ClassVar

クラス変数をマークするための特別な型構文。

PEP 526 で紹介されているように、ClassVarでラップされた変数アノテーションは、特定の属性がクラス変数として使用されることを意図しており、そのクラスのインスタンスに設定されるべきではないことを示します。使用法：

class Starship:
    stats: ClassVar[dict[str, int]] = {} # class variable
    damage: int = 10                     # instance variable

ClassVar はタイプのみを受け入れ、それ以上サブスクライブすることはできません。

ClassVar はクラス自体ではないため、 isinstance（）または issubclass（）と一緒に使用しないでください。 ClassVar はPythonランタイムの動作を変更しませんが、サードパーティのタイプチェッカーで使用できます。たとえば、タイプチェッカーは次のコードにエラーのフラグを立てる場合があります。

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

バージョン3.5.3の新機能。

typing.Final

サブクラスで名前を再割り当てまたはオーバーライドできないことをタイプチェッカーに示すための特別なタイピング構造。例えば：

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # Error reported by type checker

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # Error reported by type checker

これらのプロパティの実行時チェックはありません。詳細については、 PEP 591 を参照してください。

バージョン3.8の新機能。

typing.Annotated

PEP 593 （Flexible function and variable annotations）で導入されたタイプで、既存のタイプをコンテキスト固有のメタデータ（ [X159Xなどの複数の部分）で装飾します。 ]は可変個引数です）。具体的には、タイプTには、タイプヒントAnnotated[T, x]を介してメタデータxの注釈を付けることができます。このメタデータは、静的分析または実行時に使用できます。ライブラリ（またはツール）がタイプヒントAnnotated[T, x]を検出し、メタデータxの特別なロジックがない場合、ライブラリ（またはツール）はそれを無視し、タイプをTとして扱う必要があります。関数またはクラスの型チェックアノテーションを完全に無効にするtypingモジュールに現在存在するno_type_check機能とは異なり、Annotatedタイプでは、T（たとえば、mypyまたはPyreを介して、xを安全に無視できます）と特定のアプリケーション内のxへのランタイムアクセス。

最終的に、注釈をどのように解釈するか（もしあれば）の責任は、Annotatedタイプに遭遇するツールまたはライブラリの責任です。 Annotatedタイプに遭遇したツールまたはライブラリは、注釈をスキャンして、それらが関心があるかどうかを判断できます（たとえば、isinstance()を使用）。

ツールまたはライブラリが注釈をサポートしていない場合、または不明な注釈に遭遇した場合は、それを無視して、注釈付きの型を基になる型として扱う必要があります。

クライアントが1つのタイプに複数の注釈を持つことを許可するかどうか、およびそれらの注釈をマージする方法を決定するのは、注釈を使用するツール次第です。

Annotatedタイプでは、同じ（または異なる）タイプの複数のアノテーションを任意のノードに配置できるため、それらのアノテーションを使用するツールまたはライブラリが、潜在的な重複の処理を担当します。たとえば、値の範囲の分析を行っている場合は、次のことを許可できます。

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

include_extras=Trueを get_type_hints（）に渡すと、実行時に追加のアノテーションにアクセスできます。

構文の詳細：

Annotatedの最初の引数は有効な型である必要があります
複数の型注釈がサポートされています（Annotatedは可変引数をサポートしています）：
```
Annotated[int, ValueRange(3, 10), ctype("char")]
```
Annotatedは、少なくとも2つの引数を指定して呼び出す必要があります（Annotated[int]は無効です）

注釈の順序は保持され、同等性チェックの重要性があります。

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

ネストされたAnnotatedタイプはフラット化され、メタデータは最も内側のアノテーションから順に並べられます。
```
Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
    int, ValueRange(3, 10), ctype("char")
]
```

重複した注釈は削除されません。

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

Annotatedは、ネストされた汎用エイリアスで使用できます。

T = TypeVar('T')
Vec = Annotated[list[tuple[T, T]], MaxLen(10)]
V = Vec[int]

V == Annotated[list[tuple[int, int]], MaxLen(10)]

バージョン3.9の新機能。

typing.TypeGuard

ユーザー定義の型ガード関数の戻り型に注釈を付けるために使用される特別な型指定フォーム。 TypeGuardは、単一の型引数のみを受け入れます。実行時に、このようにマークされた関数はブール値を返す必要があります。

TypeGuardは、型ナローイングの利点を目的としています。これは、静的型チェッカーがプログラムのコードフロー内の式のより正確な型を判別するために使用する手法です。通常、型の絞り込みは、条件付きコードフローを分析し、コードのブロックに絞り込みを適用することによって行われます。ここでの条件式は、「タイプガード」と呼ばれることもあります。

def is_str(val: str | float):
    # "isinstance" type guard
    if isinstance(val, str):
        # Type of ``val`` is narrowed to ``str``
        ...
    else:
        # Else, type of ``val`` is narrowed to ``float``.
        ...

型ガードとしてユーザー定義のブール関数を使用すると便利な場合があります。このような関数は、静的型チェッカーにこの意図を警告するために、戻り型としてTypeGuard[...]を使用する必要があります。

-> TypeGuardを使用すると、静的型チェッカーに特定の関数について次のように通知されます。

戻り値はブール値です。

戻り値がTrueの場合、その引数の型はTypeGuard内の型です。

例えば：

def is_str_list(val: List[object]) -> TypeGuard[List[str]]:
    '''Determines whether all objects in the list are strings'''
    return all(isinstance(x, str) for x in val)

def func1(val: List[object]):
    if is_str_list(val):
        # Type of ``val`` is narrowed to ``List[str]``.
        print(" ".join(val))
    else:
        # Type of ``val`` remains as ``List[object]``.
        print("Not a list of strings!")

is_str_listがクラスまたはインスタンスメソッドの場合、TypeGuardの型は、clsまたはselfの後の2番目のパラメーターの型にマップされます。

つまり、def foo(arg: TypeA) -> TypeGuard[TypeB]: ...の形式は、foo(arg)がTrueを返す場合、argがTypeAからTypeBに絞り込むことを意味します。 ]。

ノート

TypeBはTypeAの幅の狭い形式である必要はなく、幅の広い形式でもかまいません。主な理由は、Listは不変であるため、後者は前者のサブタイプではありませんが、List[object]をList[str]に絞り込むなどのことを可能にするためです。タイプセーフタイプガードを作成する責任はユーザーにあります。

TypeGuardは型変数でも機能します。詳細については、 PEP 647 （ユーザー定義タイプガード）を参照してください。

バージョン3.10の新機能。

ジェネリック型の構築

これらは注釈では使用されません。これらは、ジェネリック型を作成するためのビルディングブロックです。

class typing.Generic

ジェネリック型の抽象基本クラス。

ジェネリック型は通常、1つ以上の型変数を使用してこのクラスのインスタンス化から継承することによって宣言されます。たとえば、一般的なマッピングタイプは次のように定義されます。

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

このクラスは、次のように使用できます。

X = TypeVar('X')
Y = TypeVar('Y')

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

class typing.TypeVar

型変数。

使用法：

T = TypeVar('T')  # Can be anything
A = TypeVar('A', str, bytes)  # Must be str or bytes

型変数は、主に静的型チェッカーの利益のために存在します。これらは、ジェネリック型およびジェネリック関数定義のパラメーターとして機能します。ジェネリック型の詳細については、 Generic を参照してください。ジェネリック関数は次のように機能します。

def repeat(x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n

def longest(x: A, y: A) -> A:
    """Return the longest of two strings."""
    return x if len(x) >= len(y) else y

後者の例の署名は、本質的に(str, str) -> strと(bytes, bytes) -> bytesのオーバーロードです。また、引数が str のサブクラスのインスタンスである場合、戻り値の型はプレーン str のままであることに注意してください。

実行時に、isinstance(x, T)は TypeError を発生させます。一般に、 isinstance（）および issubclass（）は型と一緒に使用しないでください。

型変数は、covariant=Trueまたはcontravariant=Trueを渡すことにより、共変または反変としてマークできます。詳細については、 PEP 484 を参照してください。デフォルトでは、型変数は不変です。あるいは、型変数はbound=<type>を使用して上限を指定することもできます。これは、型変数の代わりに（明示的または暗黙的に）実際の型が境界型のサブクラスでなければならないことを意味します。 PEP484 を参照してください。

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False)

パラメータ指定変数。型変数の特殊バージョン。

使用法：

P = ParamSpec('P')

パラメータ指定変数は、主に静的型チェッカーの利益のために存在します。これらは、ある呼び出し可能オブジェクトのパラメーター型を別の呼び出し可能オブジェクトに転送するために使用されます。これは、高階関数やデコレーターで一般的に見られるパターンです。これらは、Concatenateで使用される場合、Callableの最初の引数として使用される場合、またはユーザー定義のジェネリックスのパラメーターとして使用される場合にのみ有効です。ジェネリック型の詳細については、 Generic を参照してください。

たとえば、関数に基本的なログを追加するには、デコレータadd_loggingを作成して関数呼び出しをログに記録します。パラメータ指定変数は、デコレータに渡されたcallableとそれによって返される新しいcallableが相互に依存する型パラメータを持っていることを型チェッカーに通知します。

from collections.abc import Callable
from typing import TypeVar, ParamSpec
import logging

T = TypeVar('T')
P = ParamSpec('P')

def add_logging(f: Callable[P, T]) -> Callable[P, T]:
    '''A type-safe decorator to add logging to a function.'''
    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:
    '''Add two numbers together.'''
    return x + y

ParamSpecがない場合、これに以前に注釈を付ける最も簡単な方法は、Callable[..., Any]がバインドされた TypeVar を使用することでした。ただし、これにより2つの問題が発生します。

*argsと**kwargsは Any と入力する必要があるため、タイプチェッカーはinner関数をタイプチェックできません。

[[#typing.cast|]] は、inner関数を返すときに、add_loggingデコレータの本体で必要になる場合があります。または、静的型チェッカーに [を無視するように指示する必要があります。 X168X]。

args

kwargs: ParamSpecは位置パラメーターとキーワードパラメーターの両方をキャプチャするため、P.argsとP.kwargsを使用して、ParamSpecをコンポーネントに分割できます。 P.argsは、特定の呼び出しにおける位置パラメーターのタプルを表し、*argsに注釈を付けるためにのみ使用する必要があります。 P.kwargsは、特定の呼び出しにおけるキーワードパラメータの値へのマッピングを表し、**kwargsに注釈を付けるためにのみ使用する必要があります。どちらの属性でも、注釈付きパラメーターがスコープ内にある必要があります。実行時、P.argsとP.kwargsは、それぞれ ParamSpecArgs と ParamSpecKwargs のインスタンスです。

covariant=Trueまたはcontravariant=Trueで作成されたパラメーター指定変数を使用して、共変または反変のジェネリック型を宣言できます。 TypeVar と同様に、bound引数も受け入れられます。ただし、これらのキーワードの実際のセマンティクスはまだ決定されていません。

バージョン3.10の新機能。

ノート

グローバルスコープで定義されたパラメータ指定変数のみをpickle化できます。

も参照してください

PEP 612 –パラメーター仕様変数（ParamSpecおよびConcatenateを導入したPEP）。
呼び出し可能および連結。

typing.ParamSpecArgs

typing.ParamSpecKwargs

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

これらのオブジェクトのいずれかで get_origin（）を呼び出すと、元のParamSpecが返されます。

P = ParamSpec("P")
get_origin(P.args)  # returns P
get_origin(P.kwargs)  # returns P

バージョン3.10の新機能。

typing.AnyStr

AnyStrは、AnyStr = TypeVar('AnyStr', str, bytes)として定義された型変数です。

これは、さまざまな種類の文字列を混在させることなく、任意の種類の文字列を受け入れることができる関数に使用することを目的としています。例えば：

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

concat(u"foo", u"bar")  # Ok, output has type 'unicode'
concat(b"foo", b"bar")  # Ok, output has type 'bytes'
concat(u"foo", b"bar")  # Error, cannot mix unicode and bytes

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())  # Passes static type check

詳細については、 PEP 544 を参照してください。 runtime_checkable（）（後述）で装飾されたプロトコルクラスは、型署名を無視して、指定された属性の存在のみをチェックする単純なランタイムプロトコルとして機能します。

プロトコルクラスは、次のように汎用にすることができます。

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

バージョン3.8の新機能。

@typing.runtime_checkable

プロトコルクラスをランタイムプロトコルとしてマークします。

このようなプロトコルは、 isinstance（）および issubclass（）で使用できます。これにより、非プロトコルクラスに適用されると、 TypeError が発生します。これにより、 Iterable などの collections.abc の「ワントリックポニー」と非常によく似たシンプルな構造チェックが可能になります。例えば：

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

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

ノート

runtime_checkable（）は、型シグネチャではなく、必要なメソッドの存在のみをチェックします。たとえば、 ssl.SSLObject はクラスであるため、 Callable に対して issubclass（）チェックに合格します。ただし、ssl.SSLObject.__init__()メソッドは、より有益なメッセージで TypeError を発生させるためにのみ存在するため、 ssl.SSLObject を呼び出す（インスタンス化する）ことはできません。

バージョン3.8の新機能。

その他の特別な指令

これらは注釈では使用されません。これらは、型を宣言するための構成要素です。

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

デフォルト値のあるフィールドは、デフォルトのないフィールドの後に来る必要があります。

結果のクラスには、フィールド名をフィールドタイプにマップするdictを与える追加の属性__annotations__があります。（フィールド名は_fields属性にあり、デフォルト値は_field_defaults属性にあり、どちらもnamedtuple APIの一部です。）

NamedTupleサブクラスには、docstringとメソッドを含めることもできます。

class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

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

下位互換性のある使用法：

Employee = NamedTuple('Employee', [('name', str), ('id', int)])

バージョン3.6で変更： PEP 526 変数注釈構文のサポートが追加されました。

バージョン3.6.1で変更：デフォルト値、メソッド、およびdocstringのサポートが追加されました。

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

バージョン3.9で変更： _field_types属性を削除し、同じ情報を持つより標準的な__annotations__属性を採用しました。

class typing.NewType(name, tp)

タイプチェッカーに個別のタイプを示すヘルパークラス。 NewType を参照してください。実行時に、呼び出されたときに引数を返すオブジェクトを返します。使用法：

UserId = NewType('UserId', int)
first_user = UserId(1)

バージョン3.5.2の新機能。

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

class typing.TypedDict(dict)

型ヒントを辞書に追加するための特別な構成。実行時には、プレーンな 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'}           # Fails type check

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

イントロスペクションのタイプ情報には、Point2D.__annotations__、Point2D.__total__、Point2D.__required_keys__、およびPoint2D.__optional_keys__からアクセスできます。 PEP 526 をサポートしない古いバージョンのPythonでこの機能を使用できるようにするために、TypedDictは2つの同等の構文形式をサポートしています。

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

デフォルトでは、すべてのキーがTypedDictに存在する必要があります。全体を指定することでこれを上書きすることができます。使用法：

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

これは、Point2D TypedDictで任意のキーを省略できることを意味します。型チェッカーは、total引数の値としてリテラルFalseまたはTrueのみをサポートすることが期待されています。 Trueがデフォルトであり、クラス本体で定義されているすべてのアイテムが必須になります。

TypedDictの使用に関するその他の例と詳細なルールについては、 PEP 589 を参照してください。

バージョン3.8の新機能。

一般的なコンクリートコレクション

組み込み型に対応

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

dict の汎用バージョン。リターンタイプに注釈を付けるのに便利です。引数に注釈を付けるには、 Mapping などの抽象コレクションタイプを使用することをお勧めします。

このタイプは次のように使用できます。

def count_words(text: str) -> Dict[str, int]:
    ...

バージョン3.9以降非推奨： builtins.dict は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

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

リストの汎用バージョン。リターンタイプに注釈を付けるのに便利です。引数に注釈を付けるには、 Sequence や Iterable などの抽象コレクションタイプを使用することをお勧めします。

このタイプは次のように使用できます。

T = TypeVar('T', int, float)

def vec2(x: T, y: T) -> List[T]:
    return [x, y]

def keep_positives(vector: Sequence[T]) -> List[T]:
    return [item for item in vector if item > 0]

バージョン3.9以降非推奨： builtins.list は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Set(set, MutableSet[T]): builtins.set の汎用バージョン。リターンタイプに注釈を付けるのに便利です。引数に注釈を付けるには、 AbstractSet などの抽象コレクションタイプを使用することをお勧めします。

バージョン3.9以降非推奨： builtins.set は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.FrozenSet(frozenset, AbstractSet[T_co]): builtins.frozenset の汎用バージョン。

バージョン3.9以降非推奨： builtins.frozenset は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

ノート

タプルは特殊なフォームです。

コレクションのタイプに対応

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT]): collections.defaultdict の汎用バージョン。

バージョン3.5.2の新機能。

バージョン3.9以降非推奨： collections.defaultdict は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT]): collections.OrderedDict の汎用バージョン。

バージョン3.7.2の新機能。

バージョン3.9以降非推奨： collections.OrderedDict は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT]): collections.ChainMap の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.1の新機能。

バージョン3.9以降非推奨： collections.ChainMap は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Counter(collections.Counter, Dict[T, int]): collections.Counter の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.1の新機能。

バージョン3.9以降非推奨： collections.Counter は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Deque(deque, MutableSequence[T]): collections.deque の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.1の新機能。

バージョン3.9以降非推奨： collections.deque は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

その他のコンクリートタイプ

class typing.IO

class typing.TextIO
class typing.BinaryIO

ジェネリック型IO[AnyStr]とそのサブクラスTextIO(IO[str])およびBinaryIO(IO[bytes])は、 open（）によって返されるようなI / Oストリームの型を表します。

class typing.Pattern class typing.Match: これらのタイプエイリアスは、 re.compile（）および re.match（）からの戻りタイプに対応します。これらのタイプ（および対応する関数）はAnyStrでジェネリックであり、Pattern[str]、Pattern[bytes]、Match[str]、または [と書くことで特定できます。 X147X]。

バージョン3.9以降非推奨： re のクラスPatternおよびMatchが[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Text

Textは、strのエイリアスです。 Python 2コードの上位互換パスを提供するために提供されています。Python2では、Textはunicodeのエイリアスです。

Textを使用して、Python2とPython3の両方と互換性のある方法で値にUnicode文字列が含まれている必要があることを示します。

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

バージョン3.5.2の新機能。

抽象基本クラス

collections.abc のコレクションに対応

class typing.AbstractSet(Sized, Collection[T_co]): collections.abc.Set の汎用バージョン。

バージョン3.9以降非推奨： collections.abc.Set は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.ByteString(Sequence[int])

collections.abc.ByteString の汎用バージョン。

このタイプは、バイトシーケンスのタイプ bytes 、 bytearray 、および memoryview を表します。

このタイプの省略形として、 bytes を使用して、上記のタイプの引数に注釈を付けることができます。

バージョン3.9以降非推奨： collections.abc.ByteString は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Collection(Sized, Iterable[T_co], Container[T_co]): collections.abc.Collection の汎用バージョン

バージョン3.6.0の新機能。

バージョン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, Generic[KT_co, VT_co]): collections.abc.ItemsView の汎用バージョン。

バージョン3.9以降非推奨： collections.abc.ItemsView は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co]): collections.abc.KeysView の汎用バージョン。

バージョン3.9以降非推奨： collections.abc.KeysView は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Mapping(Sized, Collection[KT], Generic[VT_co])

collections.abc.Mapping の汎用バージョン。このタイプは次のように使用できます。

def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
    return word_list[word]

バージョン3.9以降非推奨： collections.abc.Mapping は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.MappingView(Sized, Iterable[T_co]): 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[VT_co]): collections.abc.ValuesView の汎用バージョン。

バージョン3.9以降非推奨： collections.abc.ValuesView は[]をサポートするようになりました。 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 および汎用エイリアスタイプを参照してください。

class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])

ジェネレーターには、汎用タイプ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, None, None]:
    while True:
        yield start
        start += 1

または、Iterable[YieldType]またはIterator[YieldType]のいずれかのリターンタイプを持つようにジェネレーターに注釈を付けます。

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

バージョン3.9以降非推奨： collections.abc.Generator は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Hashable: 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 のエイリアス

非同期プログラミング

class typing.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])

collections.abc.Coroutine の汎用バージョン。型変数の分散と順序は、 Generator のものに対応します。次に例を示します。

from collections.abc import Coroutine
c = None # type: Coroutine[list[str], str, int]
...
x = c.send('hi') # type: list[str]
async def bar() -> None:
    x = await c # type: int

バージョン3.5.3の新機能。

バージョン3.9以降非推奨： collections.abc.Coroutine は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])

非同期ジェネレーターには、汎用タイプAsyncGenerator[YieldType, SendType]の注釈を付けることができます。例えば：

async def echo_round() -> AsyncGenerator[int, float]:
    sent = yield 0
    while sent >= 0.0:
        rounded = await round(sent)
        sent = yield rounded

通常のジェネレーターとは異なり、非同期ジェネレーターは値を返すことができないため、ReturnTypeタイプのパラメーターはありません。 Generator と同様に、SendTypeは逆に動作します。

ジェネレーターが値のみを生成する場合は、SendTypeをNoneに設定します。

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)

バージョン3.6.1の新機能。

バージョン3.9以降非推奨： collections.abc.AsyncGenerator は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.AsyncIterable(Generic[T_co]): collections.abc.AsyncIterable の汎用バージョン。

バージョン3.5.2の新機能。

バージョン3.9以降非推奨： collections.abc.AsyncIterable は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.AsyncIterator(AsyncIterable[T_co]): collections.abc.AsyncIterator の汎用バージョン。

バージョン3.5.2の新機能。

バージョン3.9以降非推奨： collections.abc.AsyncIterator は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.Awaitable(Generic[T_co]): collections.abc.Awaitable の汎用バージョン。

バージョン3.5.2の新機能。

バージョン3.9以降非推奨： collections.abc.Awaitable は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

コンテキストマネージャーの種類

class typing.ContextManager(Generic[T_co]): contextlib.AbstractContextManager の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.0の新機能。

バージョン3.9以降非推奨： contextlib.AbstractContextManager は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

class typing.AsyncContextManager(Generic[T_co]): contextlib.AbstractAsyncContextManager の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.2の新機能。

バージョン3.9以降非推奨： contextlib.AbstractAsyncContextManager は[]をサポートするようになりました。 PEP 585 および汎用エイリアスタイプを参照してください。

プロトコル

これらのプロトコルは runtime_checkable（）で装飾されています。

class typing.SupportsAbs: 戻り型が共変である1つの抽象メソッド__abs__を持つABC。

class typing.SupportsBytes: 1つの抽象メソッド__bytes__を持つABC。

class typing.SupportsComplex: 1つの抽象メソッド__complex__を持つABC。

class typing.SupportsFloat: 1つの抽象メソッド__float__を持つABC。

class typing.SupportsIndex: 1つの抽象メソッド__index__を持つABC。

バージョン3.8の新機能。

class typing.SupportsInt: 1つの抽象メソッド__int__を持つABC。

class typing.SupportsRound: 戻り型が共変である1つの抽象メソッド__round__を持つABC。

関数とデコレータ

typing.cast(typ, val)

タイプに値をキャストします。

これにより、値は変更されずに返されます。型チェッカーに対して、これは戻り値が指定された型を持っていることを通知しますが、実行時に意図的に何もチェックしません（これをできるだけ速くしたい）。

@typing.overload

@overloadデコレータを使用すると、引数タイプの複数の異なる組み合わせをサポートする関数とメソッドを記述できます。一連の@overloadで装飾された定義の後には、@overloadで装飾されていない定義が1つだけ続く必要があります（同じ関数/メソッドの場合）。 @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):
    <actual implementation>

詳細および他のタイピングセマンティクスとの比較については、 PEP 484 を参照してください。

@typing.final

装飾されたメソッドをオーバーライドできず、装飾されたクラスをサブクラス化できないことをタイプチェッカーに示すデコレータ。例えば：

class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # Error reported by type checker
          ...

@final
class Leaf:
    ...
class Other(Leaf):  # Error reported by type checker
    ...

これらのプロパティの実行時チェックはありません。詳細については、 PEP 591 を参照してください。

バージョン3.8の新機能。

@typing.no_type_check

注釈がタイプヒントではないことを示すデコレータ。

これは、クラスまたは関数デコレータとして機能します。クラスを使用すると、そのクラスで定義されているすべてのメソッドに再帰的に適用されます（ただし、そのスーパークラスまたはサブクラスで定義されているメソッドには適用されません）。

これにより、機能が適切に変更されます。

@typing.no_type_check_decorator

別のデコレータに no_type_check（）効果を与えるデコレータ。

これは、 no_type_check（）のデコレートされた関数をラップするものでデコレータをラップします。

@typing.type_check_only

クラスまたは関数を実行時に使用不可としてマークするデコレータ。

このデコレータ自体は実行時に使用できません。これは主に、実装がプライベートクラスのインスタンスを返す場合に、タイプスタブファイルで定義されているクラスをマークすることを目的としています。

@type_check_only
class Response:  # private or not available at runtime
    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)

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

多くの場合、これはobj.__annotations__と同じです。さらに、文字列リテラルとしてエンコードされた前方参照は、globalsおよびlocals名前空間で評価することによって処理されます。必要に応じて、Noneに等しいデフォルト値が設定されている場合、関数およびメソッドのアノテーションにOptional[t]が追加されます。クラスCの場合、すべての__annotations__をC.__mro__に沿って逆の順序でマージして作成された辞書を返します。

この関数は、include_extrasがTrueに設定されていない限り、すべてのAnnotated[T, ...]をTに再帰的に置き換えます（詳細については、注釈付きを参照）。例えば：

class Student(NamedTuple):
    name: Annotated[str, 'some marker']

get_type_hints(Student) == {'name': str}
get_type_hints(Student, include_extras=False) == {'name': str}
get_type_hints(Student, include_extras=True) == {
    'name': Annotated[str, 'some marker']
}

ノート

get_type_hints（）は、前方参照を含むインポートされたタイプエイリアスでは機能しません。注釈の延期された評価（ PEP 563 ）を有効にすると、ほとんどの前方参照が不要になる場合があります。

バージョン3.9で変更： PEP 593 の一部としてinclude_extrasパラメーターを追加しました。

typing.get_args(tp)

typing.get_origin(tp)

ジェネリック型と特殊な型付けフォームの基本的な内省を提供します。

X[Y, Z, ...]の形式の入力オブジェクトの場合、これらの関数はXおよび(Y, Z, ...)を返します。 Xが組み込みクラスまたはコレクションクラスの汎用エイリアスである場合、元のクラスに正規化されます。 Xがユニオンであるか、リテラルが別のジェネリック型に含まれている場合、(Y, Z, ...)の順序は元の引数[Y, Z, ...]の順序と異なる場合があります。キャッシュを入力します。サポートされていないオブジェクトの場合、それぞれNoneと()を返します。例：

assert get_origin(Dict[str, int]) is dict
assert get_args(Dict[int, str]) == (int, str)

assert get_origin(Union[int, str]) is Union
assert get_args(Union[int, str]) == (int, str)

バージョン3.8の新機能。

typing.is_typeddict(tp)

タイプが TypedDict であるかどうかを確認します。

例えば：

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

is_typeddict(Film)  # => True
is_typeddict(list | str)  # => False

バージョン3.10の新機能。

class typing.ForwardRef: 文字列前方参照の内部型付け表現に使用されるクラス。たとえば、List["SomeClass"]は暗黙的にList[ForwardRef("SomeClass")]に変換されます。このクラスはユーザーによってインスタンス化されるべきではありませんが、イントロスペクションツールによって使用される可能性があります。

ノート

PEP 585 list["SomeClass"]などのジェネリック型は暗黙的にlist[ForwardRef("SomeClass")]に変換されないため、list[SomeClass]に自動的に解決されません。

バージョン3.7.4の新機能。

絶え間ない

typing.TYPE_CHECKING

サードパーティの静的型チェッカーによってTrueと見なされる特別な定数。実行時はFalseです。使用法：

if TYPE_CHECKING:
    import expensive_mod

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

expensive_mod参照をインタープリターランタイムから非表示にするには、最初の型注釈を引用符で囲んで「前方参照」にする必要があります。ローカル変数の型注釈は評価されないため、2番目の注釈を引用符で囲む必要はありません。

ノート

from __future__ import annotationsがPython3.7以降で使用されている場合、アノテーションは関数定義時に評価されません。代わりに、__annotations__に文字列として格納されます。これにより、注釈を引用符で囲む必要がなくなります。（ PEP 563 を参照）。

バージョン3.5.2の新機能。

タイピング—タイプヒントのサポート—Pythonドキュメント

タイピング —タイプヒントのサポート

タイプエイリアス

新しいタイプ

呼び出し可能

ジェネリック

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

Any タイプ

名目上のサブタイピングと構造的なサブタイピング

モジュールの内容

特別なタイピングプリミティブ

特殊タイプ

特別なフォーム

ジェネリック型の構築

その他の特別な指令

一般的なコンクリートコレクション

組み込み型に対応

コレクションのタイプに対応

その他のコンクリートタイプ

抽象基本クラス

collections.abc のコレクションに対応

collections.abc の他のタイプに対応

非同期プログラミング

コンテキストマネージャーの種類

プロトコル

関数とデコレータ

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

絶え間ない

目次