タイピング —タイプヒントのサポート
バージョン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 を参照してください。
ジェネリック
コンテナーに保持されているオブジェクトに関するタイプ情報を一般的な方法で静的に推測することはできないため、抽象基本クラスが拡張され、コンテナー要素の予想されるタイプを示すサブスクリプションがサポートされるようになりました。
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__
がない場合があることに注意してください。
ユーザー定義のジェネリッククラスは、メタクラスの競合なしに基本クラスとして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
- 拘束されていないタイプを示す特殊タイプ。
- 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の新機能。
- 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の新機能。
- 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化できます。
- 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の新機能。