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

バージョン 3.5 で追加.

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

注釈

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

このモジュールは PEP 484, PEP 526, PEP 544, PEP 586, PEP 589, PEP 591 によって規定された型ヒントへのランタイムサポートを提供します。 最も基本的なサポートとして `Any`、 `Union`、 `Tuple`、 `Callable`、 `TypeVar` および `Generic` 型を含みます。 完全な仕様は 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

異なる型を作るためには `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` のサブタイプを作ることが出来ないということも意味しています。 `Derived` は実行時には恒等関数になっていて、実際の型ではないからです:

    from typing import NewType

    UserId = NewType('UserId', int)

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

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

    from typing import NewType

    UserId = NewType('UserId', int)

    ProUserId = NewType('ProUserId', UserId)

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

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

注釈

型エイリアスの使用は二つの型が互いに 等価 だと宣言している、ということを思い出してください。 `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

型ヒントの実引数の型を ellipsis で置き換えることで呼び出しシグニチャを指定せずに callable の戻り値の型を宣言することができます: `Callable[..., ReturnType]`。

## ジェネリクス

コンテナ内のオブジェクトについての型情報は一般的な方法では静的に推論できないため、抽象基底クラスを継承したクラスが実装され、期待されるコンテナの要素の型を示すために添字表記をサポートするようになりました。

    from typing import Mapping, Sequence

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

ジェネリクスは、 typing にある `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` クラスが 1 つの型引数 `T` をとる、と定義できます。 この定義により、クラスの本体の中でも `T` が型として有効になります。

基底クラス `Generic` には `LoggedVar[t]` が型として有効になるように `__class_getitem__()` メソッドが定義されています:

    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` を 1 つとります。

型引数を指定せずにジェネリッククラスを使う場合、それぞれの型引数に `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` にあった独自のメタクラスは無くなりました。

ユーザーが定義したジェネリッククラスはメタクラスの衝突を起こすことなく基底クラスに抽象基底クラスをとれます。 ジェネリックメタクラスはサポートされません。 パラメータ化を行うジェネリクスの結果はキャッシュされていて、 typing モジュールのほとんどの型はハッシュ化でき、等価比較できます。

## `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` 型の値をより詳細な型に代入する時に型検査が行われないことに注意してください。例えば、静的型検査器は `a` を `s` に代入する時、`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` はすべての他の型のサブタイプでは ありません。

これは、ある値の型が `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` はある値が動的に型付けられることを示すために使用します。

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

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

前出の必要条件は、`Iterable` などの抽象基底クラスにも当て嵌まります。 この型付け手法の問題は、この手法をサポートするためにクラスに明確な型付けを行う必要があることで、これは pythonic ではなく、普段行っている 慣用的な 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]` 両方のサブタイプだと暗黙的に見なせるようになり、この問題が解決しました。 これは structural subtyping (構造的部分型) (あるいは、静的ダックタイピング) として知られています:

    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>` を使うことで上界を指定することが出来ます。これは、型変数に (明示的または非明示的に) 代入された実際の型が境界の型のサブクラスでなければならないということを意味します、PEP 484 も参照。

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` 、 型変数 あるいは、それらの直和型だけです。 例えば次のようになります:

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

  `Type[Any]` は `Type` と等価で、同様に `Type` は `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`

  抽象メソッド `__int__` を備えた ABC です。

class `typing.``SupportsFloat`

  抽象メソッド `__float__` を備えた ABC です。

class `typing.``SupportsComplex`

  抽象メソッド `__complex__` を備えた ABC です。

class `typing.``SupportsBytes`

  抽象メソッド `__bytes__` を備えた ABC です。

class `typing.``SupportsIndex`

  抽象メソッド `__index__` を備えた ABC です。

  バージョン 3.8 で追加.

class `typing.``SupportsAbs`

  返り値の型と共変な抽象メソッド `__abs__` を備えた ABC です。

class `typing.``SupportsRound`

  返り値の型と共変な抽象メソッド `__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])

  `list` のジェネリック版です。 返り値の型のアノテーションをつけるのに便利です。 引数にアノテーションをつけるためには、 `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'

  typing モジュールの多くの他のジェネリクスと違い `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` は反変的に振る舞います。

  ジェネレータが値を yield するだけなら、`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 のコードの前方互換性を提供するために設けられています: Python 2 では `Text` は `unicode` のエイリアスです。

  `Text` は Python 2 と Python 3 の両方と互換性のある方法で値が 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]` 、 `Match[bytes]` と書くことで具体型にできます。

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

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

  最終的に出来上がるクラスには、フィールド名をフィールド型へ対応付ける辞書を提供する `__annotations__` 属性が追加されています。 (フィールド名は `_fields` 属性に、デフォルト値は `_field_defaults` 属性に格納されていて、両方とも名前付きタプル 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 で変更: デフォルト値、メソッド、ドキュメンテーション文字列への対応が追加されました。

  Deprecated since version 3.8, will be removed in version 3.9: `_field_types` 属性は非推奨となりました。代わりに同じ情報を持つより標準的な `__annotations__` 属性を使ってください。

  バージョン 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})

  By default, all keys must be present in a TypedDict. It is possible to override this by specifying totality. Usage:

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

  This means that a point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body be required.

  他の例や、 `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` については、 `C.__mro__` の逆順に沿って全ての `__annotations__` を合併して構築された辞書を返します。

`typing.``get_origin`(tp)

`typing.``get_args`(tp)

  ジェネリック型や特殊な型付け形式についての基本的な内観を提供します。

  For a typing object of the form `X[Y, Z, ...]` these functions return `X` and `(Y, Z, ...)`. If `X` is a generic alias for a builtin or `collections` class, it gets normalized to the original class. For unsupported objects return `None` and `()` correspondingly. Examples:

      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` 無しの定義が来なければなりません。 `@overload` 付きの定義は型チェッカーのためでしかありません。 というのも、 `@overload` 付きの定義は `@overload` 無しの定義で上書きされるからです。 後者は実行時に使われますが、型チェッカーからは無視されるべきなのです。 実行時には、 `@overload` 付きの関数を直接呼び出すと `NotImplementedError` を送出します。 次のコードはオーバーロードを使うことで直和型や型変数を使うよりもより正確な型が表現できる例です:

      @overload
      def process(response: None) -> None:
          ...
      @overload
      def process(response: int) -> Tuple[int, str]:
          ...
      @overload
      def process(response: bytes) -> str:
          ...
      def process(response):
          <actual implementation>

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

`@``typing.``final`

  A decorator to indicate to type checkers that the decorated method cannot be overridden, and the decorated class cannot be subclassed. For example:

      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`

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

  これはクラス decorator または関数 decorator として動作します。クラス decorator として動作する場合は、そのクラス内に定義されたすべてのメソッドに対して再帰的に適用されます。（ただしスーパークラスやサブクラス内に定義されたメソッドには適用されません。）

  これは関数を適切に変更します。

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

  Mark a protocol class as a runtime protocol.

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

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

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

  Warning: this will check only the presence of the required methods, not their type signatures!

  バージョン 3.8 で追加.

`typing.``Any`

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

  - 任意の型は `Any` と互換です。

  - `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]` のように使います。詳細:

  - 引数は型でなければならず、少なくとも一つ必要です。

  - ユニオン型のユニオン型は平滑化されます。例えば:

        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 で、2つ目の要素の型が Y であるような、2つの要素を持つタプルの型です。 空のタプルの型は `Tuple[()]` と書けます。

  例: `Tuple[T1, T2]` は型変数 T1 と T2 に対応する2つの要素を持つタプルです。`Tuple[int, float, str]` は int と float、 string のタプルです。

  同じ型の任意の長さのタプルを指定するには ellipsis リテラルを用います。例: `Tuple[int, ...]`。ただの `Tuple` は `Tuple[Any, ...]` と等価で、さらに `tuple` と等価です。.

`typing.``Callable`

  呼び出し可能型; `Callable[[int], str]` は (int) -> str の関数です。

  添字表記は常に2つの値とともに使われなければなりません: 実引数のリストと返り値の型です。 実引数のリストは型のリストか ellipsis でなければなりません; 返り値の型は単一の型でなければなりません。

  オプショナル引数やキーワード引数を表すための文法はありません; そのような関数型はコールバックの型として滅多に使われません。 `Callable[..., ReturnType]` (リテラルの Ellipsis) は任意の個数の引数をとり `ReturnType` を返す型ヒントを与えるために使えます。 普通の `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()

  1つ目の型アノテーションは引用符で囲って "前方参照 (forward reference)" にし、インタプリタのランタイムから `expensive_mod` への参照を隠さなければなりません。 ローカル変数への型アノテーションは評価されないので、2つ目のアノテーションは引用符で囲う必要はありません。

  バージョン 3.5.2 で追加.