タイピング —タイプヒントのサポート
バージョン3.5の新機能。
ソースコード: :source: `Lib / typing.py`
ノート
Pythonランタイムは、関数と変数の型注釈を強制しません。 これらは、タイプチェッカー、IDE、リンターなどのサードパーティツールで使用できます。
このモジュールは、 PEP 484 、 PEP 526 、 で指定されたタイプヒントのランタイムサポートを提供します。 PEP 544 、 PEP 586 、 PEP 589 、および PEP 591 [X230X ]。 最も基本的なサポートは、タイプ 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]
は交換可能な同義語として扱われます。
from typing import List
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 typing import Dict, Tuple, 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の新機能。
呼び出し可能
特定のシグニチャのコールバック関数を期待するフレームワークは、Callable[[Arg1Type, Arg2Type], ReturnType]
を使用して型ヒントされる場合があります。
例えば:
from typing 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]
の引数のリストをリテラルの省略記号に置き換えることにより、呼び出しシグネチャを指定せずに呼び出し可能オブジェクトの戻り型を宣言できます。
ジェネリック
コンテナに保持されているオブジェクトに関する型情報を一般的な方法で静的に推測することはできないため、抽象基本クラスが拡張され、コンテナ要素の予想される型を示すサブスクリプションがサポートされるようになりました。
from typing import Mapping, Sequence
def notify_by_email(employees: Sequence[Employee],
overrides: Mapping[str, str]) -> None: ...
ジェネリックスは、 TypeVar と呼ばれるタイピングで利用可能な新しいファクトリを使用してパラメータ化できます。
from typing import Sequence, 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 typing 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 typing import TypeVar, Generic, Sized
T = TypeVar('T')
class LinkedList(Sized, Generic[T]):
...
ジェネリッククラスから継承する場合、いくつかの型変数を修正できます。
from typing import TypeVar, Mapping
T = TypeVar('T')
class MyDict(Mapping[str, T]):
...
この場合、MyDict
にはT
という単一のパラメーターがあります。
タイプパラメータを指定せずにジェネリッククラスを使用すると、各位置に Any が想定されます。 次の例では、MyIterable
はジェネリックではありませんが、Iterable[Any]
から暗黙的に継承します。
from typing import Iterable
class MyIterable(Iterable): # Same as Iterable[Any]
ユーザー定義のジェネリック型エイリアスもサポートされています。 例:
from typing import TypeVar, Iterable, Tuple, Union
S = TypeVar('S')
Response = Union[Iterable[S], int]
# Return type here is same as Union[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 にカスタムメタクラスがなくなりました。
ユーザー定義のジェネリッククラスは、メタクラスの競合なしに基本クラスとして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 typing 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 typing 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 をサブクラス化することにより、ユーザーは新しいカスタムプロトコルを定義して、構造的なサブタイピングを十分に楽しむことができます(以下の例を参照)。
クラス、関数、およびデコレータ
このモジュールは、次のクラス、関数、およびデコレータを定義します。
- 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.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.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の新機能。
- 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[Union[BasicUser, ProUser]]): ...
Type[Any]
はType
と同等であり、type
はPythonのメタクラス階層のルートです。バージョン3.5.2の新機能。
- class typing.Iterable(Generic[T_co])
- collections.abc.Iterable の汎用バージョン。
- class typing.Iterator(Iterable[T_co])
- collections.abc.Iterator の汎用バージョン。
- class typing.Reversible(Iterable[T_co])
- collections.abc.Reversible の汎用バージョン。
- class typing.SupportsInt
- 1つの抽象メソッド
__int__
を持つABC。
- class typing.SupportsFloat
- 1つの抽象メソッド
__float__
を持つABC。
- class typing.SupportsComplex
- 1つの抽象メソッド
__complex__
を持つABC。
- class typing.SupportsBytes
- 1つの抽象メソッド
__bytes__
を持つABC。
- class typing.SupportsIndex
1つの抽象メソッド
__index__
を持つABC。バージョン3.8の新機能。
- class typing.SupportsAbs
- 戻り型が共変である1つの抽象メソッド
__abs__
を持つABC。
- class typing.SupportsRound
- 戻り型が共変である1つの抽象メソッド
__round__
を持つABC。
- class typing.Container(Generic[T_co])
- collections.abc.Container の汎用バージョン。
- class typing.Hashable
- collections.abc.Hashable のエイリアス
- class typing.Sized
- collections.abc.Sized のエイリアス
- class typing.Collection(Sized, Iterable[T_co], Container[T_co])
collections.abc.Collection の汎用バージョン
バージョン3.6.0の新機能。
- class typing.AbstractSet(Sized, Collection[T_co])
- collections.abc.Set の汎用バージョン。
- class typing.MutableSet(AbstractSet[T])
- collections.abc.MutableSet の汎用バージョン。
- 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]
- class typing.MutableMapping(Mapping[KT, VT])
- collections.abc.MutableMapping の汎用バージョン。
- class typing.Sequence(Reversible[T_co], Collection[T_co])
- collections.abc.Sequence の汎用バージョン。
- class typing.MutableSequence(Sequence[T])
- collections.abc.MutableSequence の汎用バージョン。
- class typing.ByteString(Sequence[int])
collections.abc.ByteString の汎用バージョン。
このタイプは、バイトシーケンスのタイプ bytes 、 bytearray 、および memoryview を表します。
このタイプの省略形として、 bytes を使用して、上記のタイプの引数に注釈を付けることができます。
- class typing.Deque(deque, MutableSequence[T])
collections.deque の汎用バージョン。
バージョン3.5.4の新機能。
バージョン3.6.1の新機能。
- 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]
- class typing.Set(set, MutableSet[T])
- builtins.set の汎用バージョン。 リターンタイプに注釈を付けるのに便利です。 引数に注釈を付けるには、 AbstractSet などの抽象コレクションタイプを使用することをお勧めします。
- class typing.FrozenSet(frozenset, AbstractSet[T_co])
- builtins.frozenset の汎用バージョン。
- class typing.MappingView(Sized, Iterable[T_co])
- collections.abc.MappingView の汎用バージョン。
- class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])
- collections.abc.KeysView の汎用バージョン。
- class typing.ItemsView(MappingView, Generic[KT_co, VT_co])
- collections.abc.ItemsView の汎用バージョン。
- class typing.ValuesView(MappingView[VT_co])
- collections.abc.ValuesView の汎用バージョン。
- class typing.Awaitable(Generic[T_co])
collections.abc.Awaitable の汎用バージョン。
バージョン3.5.2の新機能。
- class typing.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])
collections.abc.Coroutine の汎用バージョン。 型変数の分散と順序は、 Generator のものに対応します。次に例を示します。
from typing import List, 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の新機能。
- class typing.AsyncIterable(Generic[T_co])
collections.abc.AsyncIterable の汎用バージョン。
バージョン3.5.2の新機能。
- class typing.AsyncIterator(AsyncIterable[T_co])
collections.abc.AsyncIterator の汎用バージョン。
バージョン3.5.2の新機能。
- class typing.ContextManager(Generic[T_co])
contextlib.AbstractContextManager の汎用バージョン。
バージョン3.5.4の新機能。
バージョン3.6.0の新機能。
- class typing.AsyncContextManager(Generic[T_co])
contextlib.AbstractAsyncContextManager の汎用バージョン。
バージョン3.5.4の新機能。
バージョン3.6.2の新機能。
- class typing.Dict(dict, MutableMapping[KT, VT])
dict の汎用バージョン。 リターンタイプに注釈を付けるのに便利です。 引数に注釈を付けるには、 Mapping などの抽象コレクションタイプを使用することをお勧めします。
このタイプは次のように使用できます。
def count_words(text: str) -> Dict[str, int]: ...
- class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])
collections.defaultdict の汎用バージョン。
バージョン3.5.2の新機能。
- class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])
collections.OrderedDict の汎用バージョン。
バージョン3.7.2の新機能。
- class typing.Counter(collections.Counter, Dict[T, int])
collections.Counter の汎用バージョン。
バージョン3.5.4の新機能。
バージョン3.6.1の新機能。
- class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])
collections.ChainMap の汎用バージョン。
バージョン3.5.4の新機能。
バージョン3.6.1の新機能。
- 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
- 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の新機能。
- 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の新機能。
- 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]。
- 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
のインスタンスではなく、通常の辞書になりました。
- 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__
からアクセスできます。 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
これは、point2DTypedDictで任意のキーを省略できることを意味します。 型チェッカーは、引数の合計の値としてリテラルのFalseまたはTrueのみをサポートすることが期待されています。 Trueがデフォルトであり、クラス本体で定義されているすべての項目が必須になります。
TypedDict
の使用に関するその他の例と詳細なルールについては、 PEP 589 を参照してください。バージョン3.8の新機能。
- class typing.ForwardRef
文字列前方参照の内部型付け表現に使用されるクラス。 たとえば、
List["SomeClass"]
は暗黙的にList[ForwardRef("SomeClass")]
に変換されます。 このクラスはユーザーによってインスタンス化されるべきではありませんが、イントロスペクションツールによって使用される可能性があります。バージョン3.7.4の新機能。
- typing.NewType(name, tp)
タイプチェッカーに個別のタイプを示すヘルパー関数。 NewType を参照してください。 実行時に、引数を返す関数を返します。 使用法:
UserId = NewType('UserId', int) first_user = UserId(1)
バージョン3.5.2の新機能。
- typing.cast(typ, val)
タイプに値をキャストします。
これにより、値は変更されずに返されます。 型チェッカーに対して、これは戻り値が指定された型を持っていることを通知しますが、実行時に意図的に何もチェックしません(これをできるだけ速くしたい)。
- typing.get_type_hints(obj[, globals[, locals]])
関数、メソッド、モジュール、またはクラスオブジェクトの型ヒントを含むディクショナリを返します。
多くの場合、これは
obj.__annotations__
と同じです。 さらに、文字列リテラルとしてエンコードされた前方参照は、globals
およびlocals
名前空間で評価することによって処理されます。 必要に応じて、None
に等しいデフォルト値が設定されている場合、関数およびメソッドのアノテーションにOptional[t]
が追加されます。 クラスC
の場合、すべての__annotations__
をC.__mro__
に沿って逆の順序でマージして作成された辞書を返します。
- typing.get_origin(tp)
- typing.get_args(tp)
ジェネリック型と特殊な型付けフォームの基本的な内省を提供します。
X[Y, Z, ...]
の形式の入力オブジェクトの場合、これらの関数はX
および(Y, Z, ...)
を返します。X
が組み込みクラスまたはコレクションクラスの汎用エイリアスである場合、元のクラスに正規化されます。 サポートされていないオブジェクトの場合、それぞれ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.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.runtime_checkable
プロトコルクラスをランタイムプロトコルとしてマークします。
このようなプロトコルは、 isinstance()および issubclass()で使用できます。 これにより、非プロトコルクラスに適用されると、 TypeError が発生します。 これにより、 Iterable などの collections.abc の「ワントリックポニー」と非常によく似たシンプルな構造チェックが可能になります。 例えば:
@runtime_checkable class Closable(Protocol): def close(self): ... assert isinstance(open('/some/file'), Closable)
警告:これにより、必要なメソッドの存在のみがチェックされ、型シグネチャはチェックされません。
バージョン3.8の新機能。
- typing.Any
- 拘束されていないタイプを示す特殊タイプ。
- typing.NoReturn
関数が戻らないことを示す特殊なタイプ。 例えば:
from typing import NoReturn def stop() -> NoReturn: raise RuntimeError('no way')
バージョン3.5.4の新機能。
バージョン3.6.2の新機能。
- typing.Union
共用体タイプ;
Union[X, Y]
はXまたはYのいずれかを意味します。和集合を定義するには、例えば
Union[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]
ユニオンを比較する場合、引数の順序は無視されます。例:
Union[int, str] == Union[str, int]
ユニオンをサブクラス化またはインスタンス化することはできません。
Union[X][Y]
は書き込めません。Optional[X]
はUnion[X, None]
の省略形として使用できます。
バージョン3.7で変更:実行時にユニオンから明示的なサブクラスを削除しないでください。
- typing.Optional
オプションタイプ。
Optional[X]
はUnion[X, None]
と同等です。これは、デフォルトの引数であるオプションの引数と同じ概念ではないことに注意してください。 デフォルトのオプションの引数は、オプションであるという理由だけで、型注釈に
Optional
修飾子を必要としません。 例えば:def foo(arg: int = 0) -> None: ...
一方、
None
の明示的な値が許可されている場合は、引数がオプションであるかどうかに関係なく、Optional
の使用が適切です。 例えば:def foo(arg: Optional[int] = None) -> None: ...
- 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, ...]
と同等であり、タプルと同等です。
- typing.Callable
呼び出し可能なタイプ。
Callable[[int], str]
は(int)-> strの関数です。サブスクリプション構文は、常に引数リストと戻り型の2つの値で使用する必要があります。 引数リストは、タイプのリストまたは省略記号である必要があります。 戻り型は単一の型である必要があります。
オプションまたはキーワード引数を示す構文はありません。 このような関数型がコールバック型として使用されることはめったにありません。
Callable[..., ReturnType]
(リテラル省略記号)を使用して、任意の数の引数を取り、ReturnType
を返すcallableのヒントを入力できます。 プレーンな Callable は、Callable[..., Any]
と同等であり、 collections.abc.Callable と同等です。
- 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.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
- 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番目の注釈を引用符で囲む必要はありません。バージョン3.5.2の新機能。