"typing" --- 型ヒントのサポート
*******************************

Added in version 3.5.

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

注釈:

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

======================================================================

このモジュールは型ヒントの実行時サポートを提供します。

以下の関数を例に考えてみます:

   def surface_area_of_cube(edge_length: float) -> str:
       return f"The surface area of the cube is {6 * edge_length ** 2}."

"surface_area_of_cube" 関数は、"edge_length: float" という *type hint*
で示されているように、引数が "float" のインスタンスであるという前提で
す。 そして、"-> str" というヒントにある通り、この関数は "str" のイン
スタンスを返すことになっています。

型ヒントは "float" や "str" のような単純な型を指定することもできますし
、もっと複雑な型も指定できます。 "typing" モジュールには、より高度な型
ヒントを表現するためのいろいろな型が含まれています。

"typing" モジュールには新しい機能が頻繁に追加されます。
typing_extensions パッケージを使うことで、古い Python バージョンからも
その新機能を使うことができます。

参考:

  型ヒントの早見表
     型ヒントの簡単な概要 (mypy ドキュメンテーション)

  mypy のドキュメント の Type System Reference の節
     Python の型システムの規格は PEP によって定められているので、この
     レファレンスはほとんどの Python 型チェッカーに適用できるはずです
     。(mypy のみに適用される部分もあるかもしれません。)

  Static Typing with Python
     コミュニティーによって書かれた、型システムの機能や便利な型関連の
     ツール、型に関するベストプラクティスを詳しく説明している、特定の
     型チェッカーに依らないドキュメンテーション。


Python 型システムの仕様
=======================

最新の正式な Python 型システムの仕様は Specification for the Python
type system を参照してください。


型エイリアス
============

型エイリアスは "type" 文を用いて定義され、これにより "TypeAliasType"
インスタンスが生成されます。 以下の例では、 "Vector" と "list[float]"
は静的型チェッカーによって同じ型とみなされます:

   type Vector = list[float]

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

   # floatのlistはVectorとして要件を満たすため、型チェックを通過する。
   new_vector = scale(2.0, [1.0, -4.2, 5.4])

型エイリアスは複雑な型シグネチャを単純化するのに有用です。例えば:

   from collections.abc import Sequence

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

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

   # 静的型チェッカーでは、上記の型アノテーションと
   # 以下のアノテーションを同等のものとして扱う。
   def broadcast_message(
       message: str,
       servers: Sequence[tuple[tuple[str, int], dict[str, str]]]
   ) -> None:
       ...

"type" 文はPython 3.12で新しく導入されました。 後方互換性のために、単
に代入によって型エイリアスを作成することもできます。

   Vector = list[float]

あるいは、 "TypeAlias" でマークすることで、これが通常の変数代入ではな
く、型エイリアスであることを明示できます。

   from typing import TypeAlias

   Vector: TypeAlias = list[float]


NewType
=======

異なる型を作るためには "NewType" ヘルパークラスを使います:

   from typing import NewType

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

静的型チェッカーは新しい型を元々の型のサブクラスのように扱います。 こ
の振る舞いは論理的な誤りを見つける手助けとして役に立ちます。

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

   # 型チェックを通過する
   user_a = get_user_name(UserId(42351))

   # 型チェックに失敗する。int型はUserId型ではないため。
   user_b = get_user_name(-1)

"UserId" 型の変数も "int" の全ての演算が行えますが、その結果は常に
"int" 型になります。 この振る舞いにより、 "int" が期待されるところに
"UserId" を渡せますが、不正な方法で "UserId" を作ってしまうことを防ぎ
ます。

   # 'output' は'int'型となる。'UserId'型にはならない。
   output = UserId(23413) + UserId(54341)

これらのチェックは静的型チェッカーだけが行うことに注意してください。
実行時に "Derived = NewType('Derived', Base)" を実行すると、渡した引数
をそのまま返す呼び出し可能オブジェクト "Derived" が作成されます。 つま
り、"Derived(some_value)" という式は新しいクラスを作成せず、通常の関数
呼び出しと比べても大きなオーバーヘッドは生じません。

より正確に言うと、式 "some_value is Derived(some_value)" は実行時に常
に真を返します。

"Derived" のサブタイプを作成することはできません。

   from typing import NewType

   UserId = NewType('UserId', int)

   # 実行時にエラーとなり、型チェックも通らない
   class AdminUserId(UserId): pass

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

   from typing import NewType

   UserId = NewType('UserId', int)

   ProUserId = NewType('ProUserId', UserId)

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

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

注釈:

  先述の通り、型エイリアスは、2つの型が互いに等価であることを宣言しま
  す。 "type Alias = Original" とすると、静的型チェッカーは "Alias" を
  "Original" と"完全に等価な"ものとして扱います。これは、複雑な型シグ
  ネチャを単純化したい場合に便利です。これに対し、 "NewType" はある型
  をもう一方の型の *サブタイプ* として宣言します。 "Derived =
  NewType('Derived', Original)" とすると静的型チェッカーは "Derived"
  を "Original" の *サブクラス* として扱います。つまり "Original" 型の
  値は "Derived" 型の値が期待される場所で使うことが出来ないということ
  です。これにより、実行パフォーマンスをほとんど犠牲にせずに論理エラー
  を防ぐことができます。

Added in version 3.5.2.

バージョン 3.10 で変更: "NewType" は関数ではなくクラスになりました。そ
の結果、通常の関数よりも "NewType" を呼び出す際に多少の実行時コストが
追加されます。

バージョン 3.11 で変更: "NewType" 呼び出し時のパフォーマンスが Python
3.9 のレベルに戻りました


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

関数や他の *呼び出し可能* オブジェクトには、"collections.abc.Callable"
または非推奨の "typing.Callable" を使ってアノテーションできます。
"Callable[[int], str]" は、"int" 型の引数を 1 つ取り、"str" を返す関数
を表します。

例えば:

   from collections.abc import Callable, Awaitable

   def feeder(get_next_item: Callable[[], str]) -> None:
       ...  # Body

   def async_query(on_success: Callable[[int], None],
                   on_error: Callable[[int, Exception], None]) -> None:
       ...  # Body

   async def on_update(value: str) -> None:
       ...  # Body

   callback: Callable[[str], Awaitable[None]] = on_update

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

もしellipsisリテラル "..." が引数リストとして与えられた場合、それは任
意のパラメータリストを持つ呼び出し可能オブジェクトを受け入れることを示
します。

   def concat(x: str, y: str) -> str:
       return x + y

   x: Callable[..., str]
   x = str     # OK
   x = concat  # これもOK

"Callable" は可変引数、オーバーロード関数、キーワード専用引数などを含
む複雑な型シグネチャを表現することはできません。 しかし、"Protocol" ク
ラスとその "__call__()" メソッドを定義すれば表現することができます:

   from collections.abc import Iterable
   from typing import Protocol

   class Combiner(Protocol):
       def __call__(self, *vals: bytes, maxlen: int | None = None) -> list[bytes]: ...

   def batch_proc(data: Iterable[bytes], cb_results: Combiner) -> bytes:
       for item in data:
           ...

   def good_cb(*vals: bytes, maxlen: int | None = None) -> list[bytes]:
       ...
   def bad_cb(*vals: bytes, maxitems: int | None) -> list[bytes]:
       ...

   batch_proc([], good_cb)  # OK
   batch_proc([], bad_cb)   # エラー! コールバックのパラメータ名と種類が異なるため、
                            # 第2引数の型が適合しない

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

バージョン 3.10 で変更: "Callable" は "ParamSpec" と "Concatenate" を
サポートしました。詳細は **PEP 612** を参照してください。

参考: "ParamSpec" と "Concatenate" のドキュメントに、"Callable" での使用例
    が記載されています。


ジェネリクス
============

コンテナに含まれるオブジェクトに関する型情報は、一般的な方法で静的に推
論することができないため、標準ライブラリの多くのコンテナクラスは、要素
に期待する型を示す添字表記をサポートしています

   from collections.abc import Mapping, Sequence

   class Employee: ...

   # Sequence[Employee] はシーケンスの要素がすべて "Employee" の
   # インスタンスでなければならないということを表します。
   # Mapping[str, str] は mapping に含まれるキーとバリューが
   # すべて文字列である必要があることを表します。
   def notify_by_email(employees: Sequence[Employee],
                       overrides: Mapping[str, str]) -> None: ...

ジェネリック関数およびクラスは以下の通り、 型引数構文 を使うことでパラ
メータ化できます:

   from collections.abc import Sequence

   def first[T](l: Sequence[T]) -> T:  # この関数は型変数 "T" に関してジェネリックです
       return l[0]

もしくは、 "TypeVar" のコンストラクタを使うこともできます:

   from collections.abc import Sequence
   from typing import TypeVar

   U = TypeVar('U')                  # 型引数 "U" を宣言

   def second(l: Sequence[U]) -> U:  # 型引数 "U" に関してジェネリックな関数
       return l[1]

バージョン 3.12 で変更: ジェネリックが構文としてサポートされたのは
Python 3.12 が初めてです。


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

Python のコンテナのほとんどは、すべての要素が同じ型であると型システム
が想定するようになっています。例えば:

   from collections.abc import Mapping

   # ``x`` の要素がすべて int であると型チェッカーが推定する
   x: list[int] = []

   # 型チェッカーエラー： ``list`` は一つの引数しか受け付けない
   y: list[int, str] = [1, 'foo']

   # ``z`` のキーはすべて文字列であり、バリューは文字列か int のどちらか
   # であると型チェッカーが推定する
   z: Mapping[str, str | int] = {}

"list" は引数に1つの型のみ受け入れるので、型チェッカーは上記の "y" へ
の代入でエラーを出力します。同様に、"Mapping" は引数に2つの型のみ受け
入れます。1つ目はキーの型を示し、2つ目は値の型を示します。

しかし、他の多くのPythonのコンテナとは異なり、タプルがすべて同じ型では
ない要素を持つことは、慣用的なPythonコードでは一般的です。 このため、
タプルはPythonの型システムの中でも特殊です。 "tuple" は任意の数の型引
数を受け入れます。

   # OK: ``x`` に代入されるのは長さ1のタプルで、要素は int
   x: tuple[int] = (5,)

   # OK: ``y`` に代入されるのは長さ2のタプルで、
   # 第１要素は int、第２要素は文字列
   y: tuple[int, str] = (5, "foo")

   # エラー: 型アノテーションでは長さ1のタプルとなっているが、
   # ``z`` には長さ3のタプルが代入されている
   z: tuple[int] = (1, 2, 3)

タプルの長さが可変で、すべての要素が同じ型 "T" であるということを表す
には、リテラルの ellipsis "..." を使って "tuple[T, ...]" と表現します
。空のタプルを表すには "tuple[()]" を使います。型アノテーションとして
"tuple" だけを指定すると "tuple[Any, ...]" と同じ意味になります:

   x: tuple[int, ...] = (1, 2)
   # 以下の再代入は OK: ``tuple[int, ...]`` は x の長さが任意であることを表す
   x = (1, 2, 3)
   x = ()
   # 以下の再代入はエラー: ``x`` のすべての要素が int である必要がある
   x = ("foo", "bar")

   # ``y`` に代入できるのは空のタプルのみ
   y: tuple[()] = ()

   z: tuple = ("foo", "bar")
   # 以下の再代入は OK: ``tuple`` は ``tuple[Any, ...]`` と等価
   z = (1, 2, 3)
   z = ()


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

"C" でアノテーションされた変数には、"C" 型の値を代入できます。 一方、
"type[C]" (または非推奨の "typing.Type[C]") でアノテーションされた変数
には、クラス自体を値として代入できます。 具体的には、"C" の *クラスオ
ブジェクト* を受け入れます。 例えば次のようになります。

   a = 3         # 型は ``int``
   b = int       # 型は ``type[int]``
   c = type(a)   # これも型は ``type[int]``

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

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

   def make_new_user(user_class: type[User]) -> User:
       # ...
       return user_class()

   make_new_user(User)      # OK
   make_new_user(ProUser)   # これも OK: ``type[ProUser]`` は ``type[User]`` のサブタイプ
   make_new_user(TeamUser)  # これも問題ない
   make_new_user(User())    # エラー: ``type[User]`` が必要だが ``User`` が渡された
   make_new_user(int)       # エラー: ``type[int]`` は ``type[User]`` のサブタイプではない

"type" の型引数として指定できるのは、クラス、"Any"、型変数、およびこれ
らの型のユニオンだけです。 例えば次のようになります。

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

   new_non_team_user(BasicUser)  # OK
   new_non_team_user(ProUser)    # OK
   new_non_team_user(TeamUser)   # Error: ``type[TeamUser]`` is not a subtype
                                 # of ``type[BasicUser | ProUser]``
   new_non_team_user(User)       # Also an error

"type[Any]" は "type" と同じで、Python の メタクラス階層 の根に当たり
ます。


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

ジェネレータには、ジェネリック型 "Generator[YieldType, SendType,
ReturnType]" を使ってアノテーションできます。 例えば次のようになります
。

   def echo_round() -> Generator[int, float, str]:
       sent = yield 0
       while sent >= 0:
           sent = yield round(sent)
       return 'Done'

標準ライブラリの他の多くのジェネリッククラスとは異なり、"Generator" の
"SendType" は共変や不変ではなく、反変であることに注意してください。

"SendType" と "ReturnType" のデフォルトは "None" です。

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

これらの型を明示的に設定することもできます。

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

値を yield するだけの単純なジェネレータでは、戻り値の型を
"Iterable[YieldType]" または "Iterator[YieldType]" としてアノテーショ
ンすることもできます。

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

非同期ジェネレータも同じように扱えますが、型引数 "ReturnType" は受け取
りません ("AsyncGenerator[YieldType, SendType]")。 "SendType" のデフォ
ルトは "None" なので、以下の定義は同じ意味です。

   async def infinite_stream(start: int) -> AsyncGenerator[int]:
       while True:
           yield start
           start = await increment(start)

   async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
       while True:
           yield start
           start = await increment(start)

同期ジェネレータの場合と同じように、"AsyncIterable[YieldType]" と
"AsyncIterator[YieldType]" も使用できます。

   async def infinite_stream(start: int) -> AsyncIterator[int]:
       while True:
           yield start
           start = await increment(start)

コルーチンには "Coroutine[YieldType, SendType, ReturnType]" を使ってア
ノテーションできます。 型引数は "Generator" の型引数に対応します。 例
えば次のようになります。

   from collections.abc import Coroutine
   c: Coroutine[list[str], str, int]  # 別の場所で定義されたコルーチン
   x = c.send('hi')                   # 'x' の推論された型は list[str]
   async def bar() -> None:
       y = await c                    # 'y' の推論された型は int


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

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

   from logging import Logger

   class LoggedVar[T]:
       def __init__(self, value: T, name: str, logger: Logger) -> None:
           self.name = name
           self.logger = logger
           self.value = value

       def set(self, new: T) -> None:
           self.log('Set ' + repr(self.value))
           self.value = new

       def get(self) -> T:
           self.log('Get ' + repr(self.value))
           return self.value

       def log(self, message: str) -> None:
           self.logger.info('%s: %s', self.name, message)

この構文は、クラス "LoggedVar" が単一の 型変数 "T" でパラメータ化され
ていることを示します。 また、クラス本体で "T" を型として使用できるよう
になります。

ジェネリッククラスは暗黙的に "Generic" を継承します。 Python 3.11 以前
との互換性のために、"Generic" を明示的に継承してジェネリッククラスであ
ることを示す方法も使えます。

   from typing import TypeVar, Generic

   T = TypeVar('T')

   class LoggedVar(Generic[T]):
       ...

ジェネリッククラスは "__class_getitem__()" メソッドを持つため、実行時
にパラメータ化できます (下の "LoggedVar[int]" など)。

   from collections.abc import Iterable

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

ジェネリック型は任意の数の型変数を持てます。 どの種類の "TypeVar" も、
ジェネリック型の型引数として使用できます。

   from typing import TypeVar, Generic, Sequence

   class WeirdTrio[T, B: Sequence[bytes], S: (int, str)]:
       ...

   OldT = TypeVar('OldT', contravariant=True)
   OldB = TypeVar('OldB', bound=Sequence[bytes], covariant=True)
   OldS = TypeVar('OldS', int, str)

   class OldWeirdTrio(Generic[OldT, OldB, OldS]):
       ...

"Generic" の引数のそれぞれの型変数は別のものでなければなりません。この
ため次のクラス定義は無効です:

   from typing import TypeVar, Generic
   ...

   class Pair[M, M]:  # SyntaxError
       ...

   T = TypeVar('T')

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

ジェネリッククラスは他のクラスを継承することもできます。

   from collections.abc import Sized

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

ジェネリッククラスを継承するときに、一部の型引数を固定することもできま
す。

   from collections.abc import Mapping

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

この場合では "MyDict" は仮引数 "T" を 1 つとります。

型引数を指定せずにジェネリッククラスを使うと、各位置に "Any" を指定し
たものとして扱われます。 以下の例の "MyIterable" はジェネリックではな
く、暗黙的に "Iterable[Any]" を継承します:

   from collections.abc import Iterable

   class MyIterable(Iterable): # Iterable[Any] と同じ
       ...

ユーザー定義のジェネリック型エイリアスにも対応しています。 例を示しま
す。

   from collections.abc import Iterable

   type Response[S] = Iterable[S] | int

   # ここの戻り値の型は Iterable[str] | int と同じ
   def response(query: str) -> Response[str]:
       ...

   type Vec[T] = Iterable[tuple[T, T]]

   def inproduct[T: (int, float, complex)](v: Vec[T]) -> T: # Iterable[tuple[T, T]] と同じ
       return sum(x*y for x, y in v)

後方互換性のために、ジェネリック型エイリアスは単純な代入でも作成できま
す。

   from collections.abc import Iterable
   from typing import TypeVar

   S = TypeVar("S")
   Response = Iterable[S] | int

バージョン 3.7 で変更: "Generic" にあった独自のメタクラスは無くなりま
した。

バージョン 3.12 で変更: ジェネリックと型エイリアスの構文はバージョン
3.12 で導入されました。 それ以前のジェネリッククラスは、"Generic" を明
示的に継承するか、基底クラスのいずれかに型変数を含める必要がありました
。

"[**P]" 形式のパラメータ仕様変数を使い、パラメータ式を受け取るユーザー
定義のジェネリックを作成することもできます。 "typing" モジュールはパラ
メータ仕様変数を特別な型変数として扱うため、上で説明した型変数と同じよ
うに動作します。 ただし例外として、"ParamSpec" には型のリストを代入で
きます。

   >>> class Z[T, **P]: ...  # T は TypeVar、P は ParamSpec
   ...
   >>> Z[int, [dict, float]]
   __main__.Z[int, [dict, float]]

"Generic" を明示的に継承して、"ParamSpec" を引数とするジェネリッククラ
スを作成することもできます。 この場合は "**" を使いません。

   from typing import ParamSpec, Generic

   P = ParamSpec('P')

   class Z(Generic[P]):
       ...

"TypeVar" と "ParamSpec" のもう 1 つの違いとして、パラメータ仕様変数が
1 つだけのジェネリックでは、 見た目を簡潔にするため、パラメータリスト
を "X[[Type1, Type2, ...]]" と "X[Type1, Type2, ...]" のどちらの形式で
も指定できます。 内部では後者を前者に変換するため、以下は同じ意味です
。

   >>> class X[**P]: ...
   ...
   >>> X[int, str]
   __main__.X[[int, str]]
   >>> X[[int, str]]
   __main__.X[[int, str]]

"ParamSpec" を使うジェネリックは、主に静的型チェックを目的としているた
め、代入後に正しい "__parameters__" を持たない場合があります。

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

ユーザー定義のジェネリッククラスは、メタクラスの衝突を起こさずに抽象基
底クラス (ABC) を基底クラスにできます。 ジェネリックなメタクラスには対
応していません。 ジェネリックをパラメータ化した結果はキャッシュされま
す。 "typing" モジュールのほとんどの型は *ハッシュ可能* で、等価比較も
できます。


"Any" 型
========

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

これは、"Any" 型の値に対して任意の演算やメソッド呼び出しを行え、どの変
数にも代入できることを意味します。

   from typing import Any

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

   s: str = ''
   s = a           # OK

   def foo(item: Any) -> int:
       # 型チェックを通過する。
       # 'item' はどの型でもよく、
       # その型には 'bar' メソッドがあるかもしれない
       item.bar()
       ...

"Any" 型の値をより詳細な型に代入する時に型検査が行われないことに注意し
てください。例えば、静的型検査器は "a" を "s" に代入する時、"s" が
"str" 型として宣言されていて実行時に "int" の値を受け取るとしても、エ
ラーを報告しません。

さらに、戻り値や引数に型アノテーションのない関数は、暗黙的に "Any" を
使います。

   def legacy_parser(text):
       ...
       return data

   # 静的型チェッカーは上記のシグネチャを
   # 次のものと同じように扱う:
   def legacy_parser(text: Any) -> Any:
       ...
       return data

この挙動により、動的型付けと静的型付けが混在したコードを書かなければな
らない時に "Any" を *非常口* として使用することができます。

"Any" の挙動と "object" の挙動を対比しましょう。 "Any" と同様に、すべ
ての型は "object" のサブタイプです。しかしながら、 "Any" と異なり、逆
は成り立ちません: "object" はすべての他の型のサブタイプでは *ありませ
ん*。

これは、ある値の型が "object" のとき、型検査器はこれについてのほとんど
すべての操作を拒否し、これをより特殊化された変数に代入する (または返り
値として利用する) ことは型エラーになることを意味します。例えば:

   def hash_a(item: object) -> int:
       # 型チェックに失敗する。
       # object に 'magic' メソッドはない。
       item.magic()
       ...

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

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

   # Any はすべての型へ代入できるので型チェックを通過する
   hash_b(42)
   hash_b("foo")

値がどの型でもよいことを型安全に表すには "object" を使います。 値が動
的に型付けされることを示すには "Any" を使います。


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

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

この要件は以前、"Iterable" などの抽象基底クラスにも適用されていました
。 この方法では、抽象基底クラスに対応していることをクラスに明示する必
要がある点が問題です。 これは Python らしくなく、慣用的な動的型付けの
Python コードで通常行うこととも異なります。 例えば、次のコードは **PEP
484** に従っています。

   from collections.abc import Sized, Iterable, Iterator

   class Bucket(Sized, Iterable[int]):
       ...
       def __len__(self) -> int: ...
       def __iter__(self) -> Iterator[int]: ...

**PEP 544** は、上記のコードでクラス定義に基底クラスを明示しなくてもよ
いようにすることで、この問題を解決します。 静的型チェッカーは "Bucket"
を暗黙的に "Sized" と "Iterable[int]" の両方のサブタイプとみなせます。
これを *構造的部分型* (または静的ダックタイピング) と呼びます。

   from collections.abc import Iterator, Iterable

   class Bucket:  # 注意: 基底クラスの指定はない
       ...
       def __len__(self) -> int: ...
       def __iter__(self) -> Iterator[int]: ...

   def collect(items: Iterable[int]) -> int: ...
   result = collect(Bucket())  # 型チェックを通過する

さらに、特別なクラス "Protocol" のサブクラスを作ることで、新しい独自の
プロトコルを作って構造的部分型というものを満喫できます。


モジュールの内容
================

"typing" モジュールは以下のクラス、関数、デコレータを定義します。


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


特殊型
~~~~~~

アノテーション内で型として使用できます。 "[]" を使った添字表記には対応
していません。

typing.Any

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

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

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

   バージョン 3.11 で変更: "Any" を基底クラスとして使えるようになりま
   した。 あらゆる場面でダックタイピングに対応するクラスや、非常に動的
   なクラスで型チェッカーのエラーを避けるのに役立ちます。

typing.AnyStr

   制約付き型変数 です。

   定義は次のとおりです。

      AnyStr = TypeVar('AnyStr', str, bytes)

   "AnyStr" は、引数として "str" または "bytes" を受け取れるものの、両
   者の混在は許さない関数で使うためのものです。

   例えば:

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

      concat("foo", "bar")    # OK、戻り値の型は 'str'
      concat(b"foo", b"bar")  # OK、戻り値の型は 'bytes'
      concat("foo", b"bar")   # エラー、str と bytes は混在できない

   名前から連想されるかもしれませんが、"AnyStr" は "Any" 型とは無関係
   で、「任意の文字列」という意味でもありません。 特に、"AnyStr" と
   "str | bytes" は異なるもので、用途も異なります。

      # AnyStr の無効な使い方:
      # 型変数が関数のシグネチャに 1 回しか現れないため、
      # 型チェッカーが型を「解決」できない
      def greet_bad(cond: bool) -> AnyStr:
          return "hi there!" if cond else b"greetings!"

      # この関数のより適切なアノテーション:
      def greet_proper(cond: bool) -> str | bytes:
          return "hi there!" if cond else b"greetings!"

   バージョン 3.13 で非推奨、バージョン 3.18 で削除予定: 新しい 型引数
   構文 に置き換えられ、非推奨となりました。 "AnyStr" をインポートする
   代わりに "class A[T: (str, bytes)]: ..." を使ってください。 詳細は
   **PEP 695** を参照してください。Python 3.16 では "AnyStr" が
   "typing.__all__" から削除され、"typing" からのアクセスやインポート
   時に実行時の非推奨警告が発生するようになります。 Python 3.18 では
   "AnyStr" が "typing" から削除されます。

typing.LiteralString

   リテラル文字列だけを含む特殊な型です。

   どの文字列リテラルも、また他の "LiteralString" も、"LiteralString"
   と互換性があります。 ただし、単に "str" 型とされたオブジェクトには
   互換性がありません。 "LiteralString" 型のオブジェクトを組み合わせて
   作った文字列も、"LiteralString" として受け入れられます。

   例:

      def run_query(sql: LiteralString) -> None:
          ...

      def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
          run_query("SELECT * FROM students")  # OK
          run_query(literal_string)  # OK
          run_query("SELECT * FROM " + literal_string)  # OK
          run_query(arbitrary_string)  # 型チェッカーのエラー
          run_query(  # 型チェッカーのエラー
              f"SELECT * FROM students WHERE name = {arbitrary_string}"
          )

   "LiteralString" は、ユーザーが生成した任意の文字列を渡すと問題が生
   じる可能性のある、注意を要する API で役立ちます。 例えば、上の型チ
   ェッカーのエラーになる 2 つのケースには、SQL インジェクション攻撃に
   対する脆弱性があるかもしれません。

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

   Added in version 3.11.

typing.Never
typing.NoReturn

   "Never" と "NoReturn" は、値を 1 つも持たない型である ボトム型 を表
   します。

   "sys.exit()" のように、関数が決して戻らないことを示すために使えます
   。

      from typing import Never  # または NoReturn

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

   また、"assert_never()" のように、有効な引数が存在しないため決して呼
   び出されるべきでない関数を定義するためにも使えます。

      from typing import Never  # または NoReturn

      def never_call_me(arg: Never) -> None:
          pass

      def int_or_str(arg: int | str) -> None:
          never_call_me(arg)  # 型チェッカーのエラー
          match arg:
              case int():
                  print("It's an int")
              case str():
                  print("It's a str")
              case _:
                  never_call_me(arg)  # OK、arg の型は Never (または NoReturn)

   "Never" と "NoReturn" は型システム上で同じ意味を持ち、静的型チェッ
   カーは両者を同じように扱います。

   Added in version 3.6.2: "NoReturn" を追加しました。

   Added in version 3.11: "Never" を追加しました。

typing.Self

   それを囲む現在のクラスを表す特殊な型です。

   例えば:

      from typing import Self, reveal_type

      class Foo:
          def return_self(self) -> Self:
              ...
              return self

      class SubclassOfFoo(Foo): pass

      reveal_type(Foo().return_self())  # 表示される型は "Foo"
      reveal_type(SubclassOfFoo().return_self())  # 表示される型は "SubclassOfFoo"

   このアノテーションは、以下の書き方と同じ意味をより簡潔に表したもの
   です。

      from typing import TypeVar

      Self = TypeVar("Self", bound="Foo")

      class Foo:
          def return_self(self: Self) -> Self:
              ...
              return self

   一般に、上の例のように "self" を返す場合は、戻り値のアノテーション
   に "Self" を使うべきです。 "Foo.return_self" の戻り値を ""Foo"" と
   アノテーションすると、型チェッカーは "SubclassOfFoo.return_self" の
   戻り値の型を "SubclassOfFoo" ではなく "Foo" と推論します。

   他によくある用途として、以下があります:

   * 代替コンストラクタとして使われ、"cls" 引数のインスタンスを返す
     "classmethod"。

   * "self" を返す "__enter__()" メソッドのアノテーション。

   クラスを継承したときに、メソッドがそのサブクラスのインスタンスを返
   す保証がなければ、戻り値のアノテーションに "Self" を使うべきではあ
   りません。

      class Eggs:
          # サブクラスでも常に Eggs のインスタンスを返すため、
          # ここの戻り値のアノテーションに Self を使うのは
          # 誤りになる
          def returns_eggs(self) -> "Eggs":
              return Eggs()

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

   Added in version 3.11.

typing.TypeAlias

   型エイリアス を明示的に宣言するための特殊なアノテーションです。

   例えば:

      from typing import TypeAlias

      Factors: TypeAlias = list[int]

   古いバージョンの Python では、型チェッカーが前方参照を使うエイリア
   スと通常の変数代入を区別しにくい場合があります。 そのようなエイリア
   スのアノテーションには "TypeAlias" が特に役立ちます:

      from typing import Generic, TypeAlias, TypeVar

      T = TypeVar("T")

      # "Box" はまだ存在しないため、Python 3.12 未満では
      # 前方参照をクォートで囲む必要がある。
      # ``TypeAlias`` により、文字列を変数に代入するのではなく
      # 型エイリアスを宣言していることが型チェッカーに伝わる。
      BoxOfStrings: TypeAlias = "Box[str]"

      class Box(Generic[T]):
          @classmethod
          def make_box_of_strings(cls) -> BoxOfStrings: ...

   より詳しくは、 **PEP 613** をご覧ください。

   Added in version 3.10.

   バージョン 3.12 で非推奨: "TypeAlias" は非推奨です。 代わりに、
   "TypeAliasType" のインスタンスを作成し、前方参照に直接対応している
   "type" 文を使ってください。 "TypeAlias" と "TypeAliasType" は用途や
   名前が似ていますが、別のものであり、後者は前者の型ではありません。
   現時点では "TypeAlias" の削除予定はありませんが、"type" 文への移行
   が推奨されます。


特殊形式
~~~~~~~~

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

class typing.Union

   ユニオン型; "Union[X, Y]" は "X | Y" と等価で X または Y を表します
   。

   ユニオンを定義するには、例えば "Union[int, str]" または省略形の
   "int | str" を使います。 省略形の使用を推奨します。 詳細は次のとお
   りです:

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

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

        Union[Union[int, str], float] == Union[int, str, float]

     ただし、型エイリアスを介して参照されるユニオンにはこの処理は適用
     されません。 元の "TypeAliasType" を強制的に評価することを避ける
     ためです。

        type A = Union[int, str]
        Union[A, float] != Union[int, str, float]

   * 引数が一つのユニオン型は消えます。例えば:

        Union[int] == int  # コンストラクタは実際に int を返す

   * 冗長な実引数は飛ばされます。例えば:

        Union[int, str, int] == Union[int, str] == int | str

   * ユニオン型を比較するとき引数の順序は無視されます。例えば:

        Union[int, str] == Union[str, int]

   * "Union" のサブクラスを作成したり、インスタンスを作成することは出
     来ません。

   * "Union[X][Y]" と書くことは出来ません。

   バージョン 3.7 で変更: 明示的に書かれているサブクラスを、実行時に直
   和型から取り除かなくなりました。

   バージョン 3.10 で変更: ユニオン型は "X | Y" のように書けるようにな
   りました。 union型の表現 を参照ください。

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

typing.Optional

   "Optional[X]" は "X | None" (や "Union[X, None]") と同等です。

   これは、デフォルト値を持つ省略可能な引数とは別の概念です。 デフォル
   ト値があり省略可能というだけで、その引数の型アノテーションに
   "Optional" が必要になるわけではありません。 例えば次のようになりま
   す。

      def foo(arg: int = 0) -> None:
          ...

   それとは逆に、 "None" という値が許されていることが明示されている場
   合は、引数がオプションであろうとなかろうと、 "Optional" を使うのが
   好ましいです。 例えば次のようになります:

      def foo(arg: Optional[int] = None) -> None:
          ...

   バージョン 3.10 で変更: Optionalは "X | None" のように書けるように
   なりました。 union型の表現 を参照ください。

typing.Concatenate

   高階関数をアノテーションするための特殊形式です。

   "Concatenate" は Callable や "ParamSpec" と組み合わせて、 他の呼び
   出し可能オブジェクトのパラメータを追加、削除、変換する高階の呼び出
   し可能オブジェクトをアノテーションできます。 "Concatenate[Arg1Type,
   Arg2Type, ..., ParamSpecVariable]" の形式で使用します。
   "Concatenate" は、Callable の型ヒント内と、"ParamSpec" を型引数に持
   つユーザー定義のジェネリッククラスのインスタンス化で使用できます。
   "Concatenate" の最後の引数は "ParamSpec" または ellipsis ("...") で
   なければなりません。

   例えば、デコレートした関数に "threading.Lock" を渡すデコレータ
   "with_lock" にアノテーションを付ける場合を考えます。 "Concatenate"
   を使うと、"with_lock" が最初の引数に "Lock" を取る呼び出し可能オブ
   ジェクトを受け取り、 異なる型シグネチャの呼び出し可能オブジェクトを
   返すことを示せます。 この場合、"ParamSpec" は、返される呼び出し可能
   オブジェクトのパラメータの型が、渡された呼び出し可能オブジェクトの
   パラメータの型に依存することを示します。

      from collections.abc import Callable
      from threading import Lock
      from typing import Concatenate

      # このロックを使い、どの時点でも関数を実行するスレッドが
      # 1 つだけになるようにする。
      my_lock = Lock()

      def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
          '''ロックを渡す型安全なデコレータ。'''
          def inner(*args: P.args, **kwargs: P.kwargs) -> R:
              # 最初の引数としてロックを渡す。
              return f(my_lock, *args, **kwargs)
          return inner

      @with_lock
      def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
          '''数値のリストをスレッドセーフな方法で合計する。'''
          with lock:
              return sum(numbers)

      # デコレータがあるので、ロックを自分で渡す必要はない。
      sum_threadsafe([1.1, 2.2, 3.3])

   Added in version 3.10.

   参考:

     * **PEP 612** -- パラメータ仕様変数 ("ParamSpec" と "Concatenate"
       を導入した PEP)

     * "ParamSpec"

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

typing.Literal

   「リテラル型」を定義するための特殊な型付け形式です。

   "Literal" は、アノテーションを付けたオブジェクトの値が、指定したリ
   テラルのいずれかと等しいことを型チェッカーに示すために使えます。

   例えば:

      def validate_simple(data: Any) -> Literal[True]:  # 常に True を返す
          ...

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

      open_helper('/some/path', 'r')      # 型チェックを通過する
      open_helper('/other/path', 'typo')  # 型チェッカーのエラー

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

   その他の詳細:

   * 引数はリテラル値でなければならず、少なくとも 1 つ必要です。

   * 入れ子の "Literal" 型は平坦化されます。 例えば次のようになります
     。

        assert Literal[Literal[1, 2], 3] == Literal[1, 2, 3]

     ただし、型エイリアスを介して参照される "Literal" 型にはこの処理は
     適用されません。 元の "TypeAliasType" を強制的に評価することを避
     けるためです。

        type A = Literal[1, 2]
        assert Literal[A, 3] != Literal[1, 2, 3]

   * 冗長な実引数は飛ばされます。例えば:

        assert Literal[1, 2, 1] == Literal[1, 2]

   * リテラル型を比較するとき、引数の順序は無視されます。 例えば次のよ
     うになります。

        assert Literal[1, 2] == Literal[2, 1]

   * "Literal" のサブクラスやインスタンスは作成できません。

   * "Literal[X][Y]" とは書けません。

   Added in version 3.8.

   バージョン 3.9.1 で変更: "Literal" ではパラメータの重複を解消するよ
   うになりました。"Literal" オブジェクトの等値比較は順序に依存しない
   ようになりました。"Literal" オブジェクトは、等値比較する際に、パラ
   メータのうち 1 つでも *hashable* でない場合は "TypeError" を送出す
   るようになりました。

typing.ClassVar

   クラス変数であることを示す特別な型構築子です。

   **PEP 526** で導入された通り、 ClassVar でラップされた変数アノテー
   ションによって、ある属性はクラス変数として使うつもりであり、そのク
   ラスのインスタンスから設定すべきではないということを示せます。使い
   方は次のようになります:

      class Starship:
          stats: ClassVar[dict[str, int]] = {} # クラス変数
          damage: int = 10                     # インスタンス変数

   "ClassVar" は型だけを受け入れ、さらに添字付けすることはできません。

   "ClassVar" 自体はクラスではなく、"isinstance()" や "issubclass()"
   では使えません。 "ClassVar" は Python の実行時の動作を変えませんが
   、静的型チェッカーが利用できます。 例えば、型チェッカーは以下のコー
   ドをエラーとして報告する場合があります。

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

   Added in version 3.5.3.

   バージョン 3.13 で変更: "ClassVar" を "Final" の内側に入れることも
   、その逆も可能になりました。

typing.Final

   再代入できない名前であることを型チェッカーに示すための特殊な型構築
   子です。

   final とされた名前は、どのスコープでも再代入できません。 クラススコ
   ープで宣言された final な名前は、サブクラスでオーバーライドできませ
   ん。

   例えば:

      MAX_SIZE: Final = 9000
      MAX_SIZE += 1  # 型チェッカーがエラーを報告する

      class Connection:
          TIMEOUT: Final[int] = 10

      class FastConnector(Connection):
          TIMEOUT = 1  # 型チェッカーがエラーを報告する

   この機能は実行時には検査されません。詳細については **PEP 591** を参
   照してください。

   Added in version 3.8.

   バージョン 3.13 で変更: "Final" を "ClassVar" の内側に入れることも
   、その逆も可能になりました。

typing.Required

   "TypedDict" のキーが必須であることを示すための特殊な型構築子です。

   主に "total=False" の TypedDict で役立ちます。 詳細は "TypedDict"
   と **PEP 655** を参照してください。

   Added in version 3.11.

typing.NotRequired

   "TypedDict" のキーが存在しない場合もあることを示すための特殊な型構
   築子です。

   より詳しくは、 "TypedDict" と **PEP 655** を参照してください。

   Added in version 3.11.

typing.ReadOnly

   "TypedDict" の項目が読み取り専用であることを示すための特殊な型構築
   子です。

   例えば:

      class Movie(TypedDict):
         title: ReadOnly[str]
         year: int

      def mutate_movie(m: Movie) -> None:
         m["year"] = 1999  # 許可される
         m["title"] = "The Matrix"  # 型チェッカーのエラー

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

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

   Added in version 3.13.

typing.Annotated

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

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

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

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

   メタデータをどう解釈するかは、"Annotated" アノテーションを処理する
   ツールやライブラリの責任です。 "Annotated" 型を処理するツールやライ
   ブラリは、メタデータの各要素を調べて、 自分が扱うべきものかどうかを
   判定できます (例えば "isinstance()" を使います)。

   Annotated[<type>, <metadata>]

   範囲解析を行う場合に、"Annotated" を使って型アノテーションにメタデ
   ータを追加する例を示します:

      @dataclass
      class ValueRange:
          lo: int
          hi: int

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

   "Annotated" の最初の引数は有効な型でなければなりません。
   "Annotated" は可変長引数に対応しているため、複数のメタデータ要素を
   指定できます。 メタデータ要素の順序は保持され、等価比較の結果にも影
   響します。

      @dataclass
      class ctype:
           kind: str

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

      assert a1 != a2  # 順序が影響する

   利用者が 1 つのアノテーションに複数のメタデータ要素を追加してよいか
   どうかや、それらのアノテーションをどう統合するかは、アノテーション
   を利用するツールが決めます。

   入れ子の "Annotated" 型は平坦化されます。 メタデータ要素は、最も内
   側のアノテーションから順に並びます。

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

   ただし、型エイリアスを介して参照される "Annotated" 型にはこの処理は
   適用されません。 元の "TypeAliasType" を強制的に評価することを避け
   るためです。

      type From3To10[T] = Annotated[T, ValueRange(3, 10)]
      assert Annotated[From3To10[int], ctype("char")] != Annotated[
         int, ValueRange(3, 10), ctype("char")
      ]

   重複するメタデータ要素は取り除かれません。

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

   "Annotated" は、入れ子のエイリアスやジェネリックなエイリアスで使え
   ます:

         @dataclass
         class MaxLen:
             value: int

         type Vec[T] = Annotated[list[tuple[T, T]], MaxLen(10)]

         # 型アノテーションで使うと、型チェッカーは "V" を
         # ``Annotated[list[tuple[int, int]], MaxLen(10)]`` と同じように扱う:
         type V = Vec[int]

   "Annotated" は、展開された "TypeVarTuple" では使えません。

      type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1]  # 無効

   ここで "T1"、"T2"、... は "TypeVar" です。 Annotated に渡す型は 1
   つだけでなければならないため、この書き方は無効です。

   デフォルトでは "get_type_hints()" はアノテーションからメタデータを
   取り除きます。 メタデータを保持するには "include_extras=True" を渡
   してください:

         >>> from typing import Annotated, get_type_hints
         >>> def func(x: Annotated[int, "metadata"]) -> None: pass
         ...
         >>> get_type_hints(func)
         {'x': <class 'int'>, 'return': <class 'NoneType'>}
         >>> get_type_hints(func, include_extras=True)
         {'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

   実行時には、"Annotated" 型に関連付けられたメタデータを
   "__metadata__" 属性から取得できます:

         >>> from typing import Annotated
         >>> X = Annotated[int, "very", "important", "metadata"]
         >>> X
         typing.Annotated[int, 'very', 'important', 'metadata']
         >>> X.__metadata__
         ('very', 'important', 'metadata')

   "Annotated" でラップされた元の型を取得するには、"__origin__" 属性を
   使ってください:

         >>> from typing import Annotated, get_origin
         >>> Password = Annotated[str, "secret"]
         >>> Password.__origin__
         <class 'str'>

   "get_origin()" を使うと "Annotated" 自体が返されることに注意してく
   ださい:

         >>> get_origin(Password)
         typing.Annotated

   参考:

     **PEP 593** - 関数と変数の柔軟なアノテーション
        "Annotated" を標準ライブラリに導入した PEP です。

   Added in version 3.9.

typing.TypeForm

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

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

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

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

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

      from typing import Any, TypeForm

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

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

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

   Added in version 3.15.

typing.TypeIs

   ユーザー定義の型述語関数であることを示すための特殊な型構築子です。

   "TypeIs" は、ユーザー定義の型述語関数の戻り値の型をアノテーションす
   るために使えます。 "TypeIs" が受け取る型引数は 1 つだけです。 この
   ようにアノテーションされた関数は、実行時に少なくとも 1 つの位置引数
   を受け取り、ブール値を返す必要があります。

   "TypeIs" は *型の絞り込み* に役立つように設計されています。 これは
   、静的型チェッカーがプログラムの制御フロー内で式の型をより具体的に
   特定する手法です。 通常は条件分岐を解析し、その結果に基づいてコード
   ブロック内の型を絞り込みます。 ここで使われる条件式を「型述語」と呼
   ぶことがあります。

      def is_str(val: str | float):
          # "isinstance" による型述語
          if isinstance(val, str):
              # ``val`` の型を ``str`` に絞り込む
              ...
          else:
              # そうでなければ、``val`` の型を ``float`` に絞り込む。
              ...

   ブール値を返すユーザー定義関数を型述語として使うと便利な場合があり
   ます。 そのような関数では、静的型チェッカーに意図を伝えるため、戻り
   値の型に "TypeIs[...]" または "TypeGuard" を使うべきです。 "TypeIs"
   は通常 "TypeGuard" より直感的に動作しますが、 入力の型と絞り込む先
   の型に互換性がない場合 ("list[object]" から "list[int]" など) や、
   絞り込む先の型のすべてのインスタンスに対して "True" を返す関数でな
   い場合には使えません。

   "-> TypeIs[NarrowedType]" と指定すると、静的型チェッカーに関数の以
   下の性質を伝えられます:

   1. 戻り値はブール値です。

   2. 戻り値が "True" なら、引数の型は、元の引数の型と "NarrowedType"
      の共通部分になります。

   3. 戻り値が "False" なら、引数の型は "NarrowedType" を除外するよう
      に絞り込まれます。

   例えば:

      from typing import assert_type, final, TypeIs

      class Parent: pass
      class Child(Parent): pass
      @final
      class Unrelated: pass

      def is_parent(val: object) -> TypeIs[Parent]:
          return isinstance(val, Parent)

      def run(arg: Child | Unrelated):
          if is_parent(arg):
              # ``arg`` の型を ``Parent`` と ``Child`` の共通部分に
              # 絞り込む。
              # これは ``Child`` と同じ。
              assert_type(arg, Child)
          else:
              # ``arg`` の型から ``Parent`` を除外するように絞り込むので、
              # ``Unrelated`` だけが残る。
              assert_type(arg, Unrelated)

   "TypeIs" の内側の型は、関数の引数の型と整合していなければなりません
   。 整合していなければ、静的型チェッカーがエラーを報告します。
   "TypeIs" 関数を誤って書くと型システムの健全性が損なわれるおそれがあ
   り、そのような関数を型安全に書くのは利用者の責任です。

   "TypeIs" 関数がクラスメソッドまたはインスタンスメソッドの場合、
   "TypeIs" 内の型は ("cls" または "self" の後の) 2 番目のパラメータの
   型に対応します。

   つまり、"def foo(arg: TypeA) -> TypeIs[TypeB]: ..." という形式は、
   "foo(arg)" が "True" を返したら "arg" は "TypeB" のインスタンスであ
   り、 "False" を返したら "TypeB" のインスタンスではないことを意味し
   ます。

   "TypeIs" は型変数でも使えます。 詳細は **PEP 742** ("TypeIs" による
   型の絞り込み) を参照してください。

   Added in version 3.13.

typing.TypeGuard

   ユーザー定義の型述語関数であることを示すための特殊な型構築子です。

   型述語関数は、引数が特定の型のインスタンスであるかどうかを返すユー
   ザー定義関数です。 "TypeGuard" は "TypeIs" と同じように動作しますが
   、型チェックへの効果には細かな違いがあります (下記を参照)。

   "-> TypeGuard" と指定すると、静的型チェッカーに関数の以下の性質を伝
   えられます:

   1. 戻り値はブール値です。

   2. 戻り値が "True" なら、引数の型は "TypeGuard" 内の型になります。

   "TypeGuard" は型変数でも使えます。 詳細は **PEP 647** を参照してく
   ださい。

   例えば:

      def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
          '''リスト内のすべてのオブジェクトが文字列かどうかを判定する'''
          return all(isinstance(x, str) for x in val)

      def func1(val: list[object]):
          if is_str_list(val):
              # ``val`` の型を ``list[str]`` に絞り込む。
              print(" ".join(val))
          else:
              # ``val`` の型は ``list[object]`` のまま。
              print("Not a list of strings!")

   "TypeIs" と "TypeGuard" には以下の違いがあります:

   * "TypeIs" は、絞り込む先の型が入力の型のサブタイプであることを要求
     しますが、"TypeGuard" は要求しません。 主な理由は、"list[object]"
     から "list[str]" への絞り込みなどを可能にするためです。 "list" は
     不変なので、後者は前者のサブタイプではありません。

   * "TypeGuard" 関数が "True" を返すと、型チェッカーは変数の型を
     "TypeGuard" に指定された型そのものに絞り込みます。 "TypeIs" 関数
     が "True" を返す場合は、変数についてすでに分かっている型と
     "TypeIs" に指定された型を組み合わせて、 型チェッカーはより具体的
     な型を推論できます (専門的には交差型と呼びます)。

   * "TypeGuard" 関数が "False" を返した場合、型チェッカーは変数の型を
     まったく絞り込めません。 "TypeIs" 関数が "False" を返した場合は、
     "TypeIs" に指定された型を除外するように変数の型を絞り込めます。

   Added in version 3.10.

typing.Unpack

   オブジェクトが展開済みであることを概念的に示すための型付け演算子で
   す。

   例えば、型変数タプル に展開演算子 "*" を適用することは、"Unpack" を
   使ってその型変数タプルを展開済みと示すことと同じです。

      Ts = TypeVarTuple('Ts')
      tup: tuple[*Ts]
      # 実質的に次と同じ:
      tup: tuple[Unpack[Ts]]

   実際、"typing.TypeVarTuple" や "builtins.tuple" の型を扱う場合、
   "Unpack" と "*" は互いに置き換えられます。 古いバージョンの Python
   では "*" を使えない箇所があったため、"Unpack" を明示的に使う書き方
   も見られます。

      # 古いバージョンの Python では、TypeVarTuple と Unpack は
      # バックポート用の `typing_extensions` パッケージに含まれる。
      from typing_extensions import TypeVarTuple, Unpack

      Ts = TypeVarTuple('Ts')
      tup: tuple[*Ts]         # Python 3.10 以下では構文エラー!
      tup: tuple[Unpack[Ts]]  # 意味は同じで、後方互換性もある

   "Unpack" は "typing.TypedDict" と組み合わせて、関数シグネチャの
   "**kwargs" の型を指定するためにも使えます。

      from typing import TypedDict, Unpack

      class Movie(TypedDict):
          name: str
          year: int

      # この関数は 2 つのキーワード引数を取る。
      # `str` 型の `name` と `int` 型の `year`。
      def foo(**kwargs: Unpack[Movie]): ...

   "Unpack" で "**kwargs" の型を指定する方法の詳細は **PEP 692** を参
   照してください。

   Added in version 3.11.


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

以下のクラスをアノテーションとして直接使うべきではありません。 これら
はジェネリック型や型エイリアスを作成するための構成要素として使うもので
す。

これらのオブジェクトは、専用の構文 (型引数リスト と "type" 文) で作成
できます。 Python 3.11 以前との互換性のために、以下で説明するように専
用の構文を使わずに作成することもできます。

class typing.Generic

   ジェネリック型のための抽象基底クラスです。

   通常、ジェネリック型はクラス名の後に型引数のリストを追加して宣言し
   ます。

      class Mapping[KT, VT]:
          def __getitem__(self, key: KT) -> VT:
              ...
              # など。

   このようなクラスは暗黙的に "Generic" を継承します。 この構文の実行
   時の意味は 言語リファレンス で説明しています。

   このクラスは次のように使用することが出来ます:

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

   ここでは、関数名の後の角括弧が ジェネリック関数 であることを示しま
   す。

   後方互換性のために、"Generic" を明示的に継承してジェネリッククラス
   を宣言することもできます。 この場合、型引数は別途宣言する必要があり
   ます。

      KT = TypeVar('KT')
      VT = TypeVar('VT')

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

class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)

   型変数です。

   型変数を作成するには、ジェネリック関数、ジェネリッククラス、 ジェネ
   リック型エイリアス の専用構文を使う方法が推奨されます。

      class Sequence[T]:  # T は TypeVar
          ...

   この構文では、上限付きや制約付きの型変数も作成できます。

      class StrSequence[S: str]:  # S は `str` を上限とする TypeVar
          ...                     # S は「`str` を上限とする」と言える


      class StrOrBytesSequence[A: (str, bytes)]:  # A は str または bytes に制約された TypeVar
          ...

   ただし、必要であれば、再利用可能な型変数を以下のように明示的に作成
   することもできます。

      T = TypeVar('T')  # どの型でもよい
      S = TypeVar('S', bound=str)  # str の任意のサブタイプ
      A = TypeVar('A', str, bytes)  # str または bytes そのものでなければならない

   型変数は、主に静的型チェッカーで利用するためのものです。 ジェネリッ
   ク型の型引数や、ジェネリック関数や型エイリアスの定義の型引数として
   使われます。 ジェネリック型の詳細は "Generic" を参照してください。
   ジェネリック関数は以下のように動作します。

      def repeat[T](x: T, n: int) -> Sequence[T]:
          """x への参照を n 個含むリストを返す。"""
          return [x]*n


      def print_capitalized[S: str](x: S) -> S:
          """x の先頭を大文字にして表示し、x を返す。"""
          print(x.capitalize())
          return x


      def concatenate[A: (str, bytes)](x: A, y: A) -> A:
          """2 つの文字列または bytes オブジェクトを連結する。"""
          return x + y

   型変数には *上限* を設けるか、*制約* を設けるか、どちらも設けないか
   を選べますが、上限 *と* 制約の両方を設けることはできません。

   型引数構文 で作成した型変数や、"infer_variance=True" を指定した型変
   数では、型チェッカーが変性を推論します。 明示的に作成する型変数は、
   "covariant=True" または "contravariant=True" を渡して共変または反変
   と指定できます。 明示的に作成する型変数は、デフォルトでは不変です。
   詳細は **PEP 484** と **PEP 695** を参照してください。

   上限付き型変数と制約付き型変数は、意味の面でいくつかの重要な違いが
   あります。 *上限付き* 型変数を使うと、"TypeVar" は可能な限り具体的
   な型に解決されます。

      x = print_capitalized('a string')
      reveal_type(x)  # 表示される型は str

      class StringSubclass(str):
          pass

      y = print_capitalized(StringSubclass('another string'))
      reveal_type(y)  # 表示される型は StringSubclass

      z = print_capitalized(45)  # エラー: int は str のサブタイプではない

   型変数の上限には、具象型、抽象型 (ABC やプロトコル)、さらには型のユ
   ニオンも指定できます。

      # __abs__ メソッドを持つ型なら何でもよい
      def print_abs[T: SupportsAbs](arg: T) -> None:
          print("Absolute value:", abs(arg))

      U = TypeVar('U', bound=str|bytes)  # ユニオン str|bytes の任意のサブタイプ
      V = TypeVar('V', bound=SupportsAbs)  # __abs__ メソッドを持つ型なら何でもよい

   一方、*制約付き* 型変数では、"TypeVar" は指定した制約のいずれかの型
   そのものにしか解決されません。

      a = concatenate('one', 'two')
      reveal_type(a)  # 表示される型は str

      b = concatenate(StringSubclass('one'), StringSubclass('two'))
      reveal_type(b)  # StringSubclass を渡しても、表示される型は str

      c = concatenate('one', b'two')  # エラー: 1 回の関数呼び出しで型変数 'A' は str か bytes のいずれかであり、両方にはできない

   実行時には "isinstance(x, T)" は "TypeError" を送出します。

   __name__

      型変数の名前です。

   __covariant__

      型変数が明示的に共変と指定されているかどうかです。

   __contravariant__

      型変数が明示的に反変と指定されているかどうかです。

   __infer_variance__

      型チェッカーが型変数の変性を推論するかどうかです。

      Added in version 3.12.

   __bound__

      型変数の上限です (設定されている場合)。

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

   evaluate_bound()

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

      Added in version 3.14.

   __constraints__

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

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

   evaluate_constraints()

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

      Added in version 3.14.

   __default__

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

      Added in version 3.13.

   evaluate_default()

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

      Added in version 3.14.

   has_default()

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

      Added in version 3.13.

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

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

class typing.TypeVarTuple(name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)

   型変数タプルです。 *可変長* ジェネリックを可能にする特殊な 型変数
   です。

   型引数リスト 内で、名前の前にアスタリスクを 1 つ ("*") 付けて型変数
   タプルを宣言できます。

      def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
          return (*tup[1:], tup[0])

   "TypeVarTuple" コンストラクタを明示的に呼び出すこともできます。

      T = TypeVar("T")
      Ts = TypeVarTuple("Ts")

      def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
          return (*tup[1:], tup[0])

   通常の型変数は 1 つの型でパラメータ化します。 これに対して型変数タ
   プルは、*任意の数* の型変数をタプルにまとめたように振る舞い、*任意
   の数* の型でパラメータ化できます。 例えば次のようになります。

      # T は int に、Ts は () に束縛される
      # 戻り値は (1,) で、型は tuple[int]
      move_first_element_to_last(tup=(1,))

      # T は int に、Ts は (str,) に束縛される
      # 戻り値は ('spam', 1) で、型は tuple[str, int]
      move_first_element_to_last(tup=(1, 'spam'))

      # T は int に、Ts は (str, float) に束縛される
      # 戻り値は ('spam', 3.0, 1) で、型は tuple[str, float, int]
      move_first_element_to_last(tup=(1, 'spam', 3.0))

      # tuple[()] は tuple[T, *Ts] と互換性がないため、
      # 型チェックにも実行時にも失敗する
      # (少なくとも 1 つの要素が必要)
      move_first_element_to_last(tup=())

   "tuple[T, *Ts]" で展開演算子 "*" を使っている点に注意してください。
   概念的には、"Ts" は型変数のタプル "(T1, T2, ...)" と考えられます。
   すると "tuple[T, *Ts]" は "tuple[T, *(T1, T2, ...)]" となり、
   "tuple[T, T1, T2, ...]" と同じ意味です。 古いバージョンの Python で
   は、代わりに "Unpack" を使って "Unpack[Ts]" と書かれている場合もあ
   ります。

   型変数タプルは *必ず* 展開しなければなりません。 これにより、型変数
   タプルを通常の型変数と区別しやすくなります。

      x: Ts          # 無効
      x: tuple[Ts]   # 無効
      x: tuple[*Ts]  # 正しい書き方

   型変数タプルは、通常の型変数と同じ文脈で使えます。 例えばクラス定義
   、引数、戻り値の型などです。

      class Array[*Shape]:
          def __getitem__(self, key: tuple[*Shape]) -> float: ...
          def __abs__(self) -> "Array[*Shape]": ...
          def get_shape(self) -> tuple[*Shape]: ...

   型変数タプルは通常の型変数と組み合わせて使えます:

      class Array[DType, *Shape]:  # これは問題ない
          pass

      class Array2[*Shape, DType]:  # これも問題ない
          pass

      class Height: ...
      class Width: ...

      float_array_1d: Array[float, Height] = Array()     # 問題ない
      int_array_2d: Array[int, Height, Width] = Array()  # これも問題ない

   ただし、型引数を指定または宣言する 1 つのリスト内には、型変数タプル
   を最大 1 つしか含められません。

      x: tuple[*Ts, *Ts]            # 無効
      class Array[*Shape, *Shape]:  # 無効
          pass

   最後に、展開された型変数タプルは "*args" の型アノテーションとして使
   えます。

      def call_soon[*Ts](
          callback: Callable[[*Ts], None],
          *args: *Ts
      ) -> None:
          ...
          callback(*args)

   展開しない "*args" のアノテーション (例えば "*args: int" は *すべて
   の* 引数を "int" と指定します) とは異なり、 "*args: *Ts" では
   "*args" の *個々の* 引数の型を参照できます。 この例では、
   "call_soon" に渡される "*args" の型と "callback" の (位置) 引数の型
   の一致を保証できます。

   型変数タプルの詳細は **PEP 646** を参照してください。

   __name__

      型変数タプルの名前です。

   __covariant__

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

      Added in version 3.15.

   __contravariant__

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

      Added in version 3.15.

   __infer_variance__

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

      Added in version 3.15.

   __default__

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

      Added in version 3.13.

   evaluate_default()

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

      Added in version 3.14.

   has_default()

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

      Added in version 3.13.

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

   Added in version 3.11.

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

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

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

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

   パラメータ仕様変数です。 特殊な 型変数 です。

   型引数リスト 内で、アスタリスクを 2 つ ("**") 付けてパラメータ仕様
   を宣言できます。

      type IntFunc[**P] = Callable[P, int]

   Python 3.11 以前との互換性のために、"ParamSpec" オブジェクトは以下
   のように作成することもできます。

      P = ParamSpec('P')

   パラメータ仕様変数は、主に静的型チェッカーで利用するためのものです
   。 ある呼び出し可能オブジェクトのパラメータの型を、別の呼び出し可能
   オブジェクトへ引き継ぐために使います。 これは高階関数やデコレータに
   よく見られるパターンです。 パラメータ仕様変数を使えるのは、
   "Concatenate" の中、"Callable" の最初の引数、またはユーザー定義のジ
   ェネリックの型引数だけです。 ジェネリック型の詳細は "Generic" を参
   照してください。

   例えば、関数に基本的なログ出力を追加するには、関数の呼び出しを記録
   するデコレータ "add_logging" を作れます。 パラメータ仕様変数は、デ
   コレータに渡した呼び出し可能オブジェクトと、それが返す新しい呼び出
   し可能オブジェクトの型引数が互いに依存していることを型チェッカーに
   伝えます。

      from collections.abc import Callable
      import logging

      def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
          '''関数にログ出力を追加する型安全なデコレータ。'''
          def inner(*args: P.args, **kwargs: P.kwargs) -> T:
              logging.info(f'{f.__name__} was called')
              return f(*args, **kwargs)
          return inner

      @add_logging
      def add_two(x: float, y: float) -> float:
          '''2 つの数値を足し合わせる。'''
          return x + y

   "ParamSpec" がなかった頃、このような関数にアノテーションを付ける最
   も簡単な方法は、上限を "Callable[..., Any]" とした "TypeVar" を使う
   ことでした。 ただし、この方法には 2 つの問題があります:

   1. "*args" と "**kwargs" の型を "Any" としなければならないため、型
      チェッカーは "inner" 関数の型チェックを行えません。

   2. "add_logging" デコレータの本体で "inner" 関数を返すときに
      "cast()" が必要になるか、静的型チェッカーに "return inner" を無
      視するように指示しなければなりません。

   args

   kwargs

      Since "ParamSpec" captures both positional and keyword
      parameters, "P.args" and "P.kwargs" can be used to split a
      "ParamSpec" into its components.  "P.args" represents the tuple
      of positional parameters in a given call and should only be used
      to annotate "*args".  "P.kwargs" represents the mapping of
      keyword parameters to their values in a given call, and should
      be only be used to annotate "**kwargs".  Both attributes require
      the annotated parameter to be in scope. At runtime, "P.args" and
      "P.kwargs" are instances respectively of "ParamSpecArgs" and
      "ParamSpecKwargs".

   __name__

      パラメータ仕様の名前です。

   __covariant__

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

   __contravariant__

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

   __infer_variance__

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

      Added in version 3.12.

   __default__

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

      Added in version 3.13.

   evaluate_default()

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

      Added in version 3.14.

   has_default()

      パラメータ仕様にデフォルト値があるかどうかを返します。
      "__default__" が "typing.NoDefault" シングルトンでないことを調べ
      るのと同じですが、遅延評価 されるデフォルト値を強制的に評価しま
      せん。

      Added in version 3.13.

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

   Added in version 3.10.

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

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

   注釈:

     pickle 化できるのは、グローバルスコープで定義されたパラメータ仕様
     変数だけです。

   参考:

     * **PEP 612** -- パラメータ仕様変数 ("ParamSpec" と "Concatenate"
       を導入した PEP)

     * "Concatenate"

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

class typing.ParamSpecArgs
class typing.ParamSpecKwargs

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

   どちらのオブジェクトでも、"get_origin()" を呼び出すと元の
   "ParamSpec" が返されます:

      >>> from typing import ParamSpec, get_origin
      >>> P = ParamSpec("P")
      >>> get_origin(P.args) is P
      True
      >>> get_origin(P.kwargs) is P
      True

   Added in version 3.10.

class typing.TypeAliasType(name, value, *, type_params=(), qualname=None)

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

   例:

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

   Added in version 3.12.

   __name__

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

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

   __qualname__

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

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

      Added in version 3.15.

   __module__

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

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

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

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

   __type_params__

      型エイリアスの型引数です。 ジェネリックでないエイリアスの場合は
      空のタプルです:

         >>> type ListOrSet[T] = list[T] | set[T]
         >>> ListOrSet.__type_params__
         (T,)
         >>> type NotGeneric = int
         >>> NotGeneric.__type_params__
         ()

   __value__

      型エイリアスの値です。 遅延評価 されるため、エイリアスの定義で使
      われる名前は "__value__" 属性にアクセスするまで解決されません:

         >>> type Mutually = Recursive
         >>> type Recursive = Mutually
         >>> Mutually
         Mutually
         >>> Recursive
         Recursive
         >>> Mutually.__value__
         Recursive
         >>> Recursive.__value__
         Mutually

   evaluate_value()

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

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

      Added in version 3.14.

   -[ 展開 ]-

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

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

   Added in version 3.14.


その他の特殊な指示
~~~~~~~~~~~~~~~~~~

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

class typing.NamedTuple

   "collections.namedtuple()" の型付き版です。

   使い方:

      class Employee(NamedTuple):
          name: str
          id: int

   これは次と等価です:

      Employee = collections.namedtuple('Employee', ['name', 'id'])

   フィールドにデフォルト値を与えるにはクラス本体で代入してください:

      class Employee(NamedTuple):
          name: str
          id: int = 3

      employee = Employee('Guido')
      assert employee.id == 3

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

   作成されたクラスに対して "annotationlib.get_annotations()" を呼び出
   すと、各フィールドの型を取得できます。 フィールド名は "_fields" 属
   性、デフォルト値は "_field_defaults" 属性に格納されており、どちらも
   "namedtuple()" API の一部です。

   "NamedTuple" のサブクラスは docstring やメソッドも持てます:

      class Employee(NamedTuple):
          """従業員を表す。"""
          name: str
          id: int = 3

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

   "NamedTuple" のサブクラスはジェネリックにもできます。

      class Group[T](NamedTuple):
          key: T
          group: list[T]

   後方互換な使用法:

      # Python 3.11 でジェネリックな NamedTuple を作成する方法
      T = TypeVar("T")

      class Group(NamedTuple, Generic[T]):
          key: T
          group: list[T]

      # 関数呼び出し形式にも対応している
      Employee = NamedTuple('Employee', [('name', str), ('id', int)])

   バージョン 3.6 で変更: **PEP 526** 変数アノテーションのシンタックス
   が追加されました。

   バージョン 3.6.1 で変更: デフォルト値、メソッド、ドキュメンテーショ
   ン文字列への対応が追加されました。

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

   バージョン 3.9 で変更: "_field_types" 属性は削除されました。代わり
   に同じ情報を持つより標準的な "__annotations__" 属性を使ってください
   。

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

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

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

class typing.NewType(name, tp)

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

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

   使い方:

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

   __module__

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

   __name__

      新しい型の名前です。

   __supertype__

      新しい型の基になる型です。

   Added in version 3.5.2.

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

class typing.Protocol(Generic)

   プロトコルクラスの基底クラスです。

   プロトコルクラスは以下のように定義します。

      class Proto(Protocol):
          def meth(self) -> int:
              ...

   このようなクラスは主に構造的部分型 (静的ダックタイピング) を認識す
   る静的型チェッカーが使います。例えば:

      class C:
          def meth(self) -> int:
              return 0

      def func(x: Proto) -> int:
          return x.meth()

      func(C())  # 静的型チェックを通過する

   See **PEP 544** for more details. Protocol classes decorated with
   "@runtime_checkable" (described later) act as simple-minded runtime
   protocols that check only the presence of given attributes,
   ignoring their type signatures. Protocol classes without this
   decorator cannot be used as the second argument to "isinstance()"
   or "issubclass()".

   プロトコルクラスはジェネリックにもできます。例えば:

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

   Python 3.11 以前との互換性が必要なコードでは、ジェネリックなプロト
   コルを以下のように書けます。

      T = TypeVar("T")

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

   Added in version 3.8.

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

@typing.runtime_checkable

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

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

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

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

      @runtime_checkable
      class Named(Protocol):
          name: str

      import threading
      assert isinstance(threading.Thread(name='Bob'), Named)

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

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

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

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

   注釈:

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

   注釈:

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

   Added in version 3.8.

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

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

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

class typing.TypedDict(dict)

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

   "TypedDict" は、その全てのインスタンスにおいてキーの集合が固定され
   ていて、各キーに対応する値が全てのインスタンスで同じ型を持つことが
   期待される辞書型を宣言します。 この期待は実行時にはチェックされず、
   型チェッカーでのみ強制されます。 使用方法は次の通りです:

      class Point2D(TypedDict):
          x: int
          y: int
          label: str

      a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
      b: Point2D = {'z': 3, 'label': 'bad'}           # 型チェックに失敗する

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

   関数呼び出し形式で "TypedDict" を作成する方法もあります。 2 番目の
   引数は "dict" リテラルでなければなりません。

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

   この関数呼び出し形式なら、キーワードである、ハイフンを含むなどの理
   由で有効な 識別子 ではないキーも定義できます。 通常のプライベート名
   のような 名前の変換 を避ける必要があるキー名にも使えます。

      # SyntaxError が発生する
      class Point2D(TypedDict):
          in: int  # 'in' はキーワード
          x-y: int  # ハイフンを含む名前

      class Definition(TypedDict):
          __schema: str  # `_Definition__schema` に変換される

      # OK、関数呼び出し形式
      Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})
      Definition = TypedDict('Definition', {'__schema': str})  # 名前が変換されない

   デフォルトでは "TypedDict" のすべてのキーが必須です。 "NotRequired"
   を使うと、個々のキーを必須でないものとして指定できます。

      class Point2D(TypedDict):
          x: int
          y: int
          label: NotRequired[str]

      # 別の構文
      Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

   つまり、"Point2D" "TypedDict" では "label" キーを省略できます。

   "total=False" を指定し、デフォルトですべてのキーを必須でなくするこ
   ともできます。

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

      # 別の構文
      Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)

   つまり、"Point2D" "TypedDict" ではどのキーも省略できます。 型チェッ
   カーが "total" 引数の値として対応する必要があるのは、リテラルの
   "False" と "True" だけです。 デフォルトは "True" で、クラス本体で定
   義したすべての項目を必須にします。

   "Required" を使うと、"total=False" の "TypedDict" の個々のキーを必
   須にできます。

      class Point2D(TypedDict, total=False):
          x: Required[int]
          y: Required[int]
          label: str

      # 別の構文
      Point2D = TypedDict('Point2D', {
          'x': Required[int],
          'y': Required[int],
          'label': str
      }, total=False)

   クラス定義形式では、"TypedDict" 型は他の 1 つ以上の "TypedDict" 型
   を継承できます。 使用例を示します。

      class Point3D(Point2D):
          z: int

   "Point3D" has three items: "x", "y" and "z". It is equivalent to
   this definition:

      class Point3D(TypedDict):
          x: int
          y: int
          z: int

   デフォルトの "TypedDict" は開いており、実行時にクラス本体で定義した
   もの以外のキーも持てます。 クラスの引数 *closed* でこの動作を制御で
   きます。 "closed=True" の場合、"TypedDict" は追加のキーを持てません
   。

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

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

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

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

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

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

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

   "TypedDict" は、"Generic" を除いて "TypedDict" でないクラスを継承で
   きません。 例えば次のようになります。

      class X(TypedDict):
          x: int

      class Y(TypedDict):
          y: int

      class Z(object): pass  # TypedDict でないクラス

      class XY(X, Y): pass  # OK

      class XZ(X, Z): pass  # TypeError が発生する

   "TypedDict" はジェネリックにもできます。

      class Group[T](TypedDict):
          key: T
          group: list[T]

   Python 3.11 以前と互換性のあるジェネリックな "TypedDict" を作成する
   には、"Generic" を明示的に継承します:

      T = TypeVar("T")

      class Group(TypedDict, Generic[T]):
          key: T
          group: list[T]

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

   __total__

      "Point2D.__total__" は "total" 引数の値を示します。 例を示します
      :

         >>> from typing import TypedDict
         >>> class Point2D(TypedDict): pass
         >>> Point2D.__total__
         True
         >>> class Point2D(TypedDict, total=False): pass
         >>> Point2D.__total__
         False
         >>> class Point3D(Point2D): pass
         >>> Point3D.__total__
         True

      この属性が反映するのは、現在の "TypedDict" クラスに渡された
      "total" 引数の値 *だけ* であり、すべてのキーが実際に必須かどうか
      ではありません。 例えば、"__total__" が "True" の "TypedDict" に
      "NotRequired" のキーがあったり、 "total=False" の別の
      "TypedDict" を継承していたりする場合があります。 したがって、イ
      ントロスペクションには通常 "__required_keys__" と
      "__optional_keys__" を使う方が適切です。

   __required_keys__

      Added in version 3.9.

   __optional_keys__

      "Point2D.__required_keys__" と "Point2D.__optional_keys__" は、
      それぞれ必須のキーと必須でないキーを含む "frozenset" オブジェク
      トを返します。

      "Required" で指定したキーは必ず "__required_keys__" に含まれ、
      "NotRequired" で指定したキーは必ず "__optional_keys__" に含まれ
      ます。

      Python 3.10 以前との後方互換性のために、継承を使って同じ
      "TypedDict" に必須のキーと必須でないキーを宣言することもできます
      。 まず "total" 引数にある値を指定した "TypedDict" を宣言し、そ
      れを継承した別の "TypedDict" で "total" に異なる値を指定します:

         >>> class Point2D(TypedDict, total=False):
         ...     x: int
         ...     y: int
         ...
         >>> class Point3D(Point2D):
         ...     z: int
         ...
         >>> Point3D.__required_keys__ == frozenset({'z'})
         True
         >>> Point3D.__optional_keys__ == frozenset({'x', 'y'})
         True

      Added in version 3.9.

      注釈:

        "from __future__ import annotations" を使っている場合や、アノ
        テーションを文字列で指定した場合は、"TypedDict" の定義時にアノ
        テーションが評価されません。 そのため、"__required_keys__" と
        "__optional_keys__" が利用する実行時のイントロスペクションが正
        しく機能せず、属性の値が誤っている場合があります。

   __readonly_keys__

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

      Added in version 3.13.

   __mutable_keys__

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

      Added in version 3.13.

   __closed__

      クラスの引数 *closed* の値です。 "True"、"False"、"None" のいず
      れかです。

   __extra_items__

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

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

   Added in version 3.8.

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

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

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

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

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

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


プロトコル
----------

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

class typing.SupportsAbs

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

class typing.SupportsBytes

   単一の抽象メソッド "__bytes__" を持つプロトコルです。

class typing.SupportsComplex

   単一の抽象メソッド "__complex__" を持つプロトコルです。

class typing.SupportsFloat

   単一の抽象メソッド "__float__" を持つプロトコルです。

class typing.SupportsIndex

   単一の抽象メソッド "__index__" を持つプロトコルです。

   Added in version 3.8.

class typing.SupportsInt

   単一の抽象メソッド "__int__" を持つプロトコルです。

class typing.SupportsRound

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


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

class typing.IO[AnyStr]
class typing.TextIO
class typing.BinaryIO

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

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

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

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

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


関数とデコレータ
----------------

typing.cast(typ, val)

   値をある型にキャストします。

   この関数は値を変更せずに返します。 型検査器に対して、返り値が指定さ
   れた型を持っていることを通知しますが、実行時には意図的に何も検査し
   ません。 (その理由は、処理をできる限り速くしたかったためです。)

typing.assert_type(val, typ, /)

   *val* の推論された型が *typ* であることを確認するよう、静的型チェッ
   カーに要求します。

   実行時には何もしません。 引数の実際の型にかかわらず、検査や副作用を
   伴わずに最初の引数をそのまま返します。

   静的型チェッカーは "assert_type()" の呼び出しを検出すると、値が指定
   された型でなければエラーを報告します。

      def greet(name: str) -> None:
          assert_type(name, str)  # OK、`name` の推論された型は `str`
          assert_type(name, int)  # 型チェッカーのエラー

   この関数は、型チェッカーによるスクリプトの解釈が開発者の意図と一致
   していることを確認するのに役立ちます。

      def complex_function(arg: object):
          # 複雑な型の絞り込み処理を行い、
          # その結果、型が `int` と推論されることを期待する
          ...
          # 型チェッカーが関数を正しく理解しているかを検査する
          assert_type(arg, int)

   Added in version 3.11.

typing.assert_never(arg, /)

   あるコード行に到達しないことを確認するよう、静的型チェッカーに要求
   します。

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

      def int_or_str(arg: int | str) -> None:
          match arg:
              case int():
                  print("It's an int")
              case str():
                  print("It's a str")
              case _ as unreachable:
                  assert_never(unreachable)

   この例では、アノテーションによって、型チェッカーは最後の case が決
   して実行されないと推論できます。 "arg" は "int" または "str" のいず
   れかで、どちらも前の case で処理されるためです。

   型チェッカーが "assert_never()" の呼び出しに到達可能と判断すると、
   エラーを報告します。 例えば "arg" の型アノテーションが "int | str |
   float" だった場合、型チェッカーは "unreachable" が "float" 型である
   というエラーを報告します。 "assert_never" の呼び出しが型チェックを
   通過するには、渡した引数の推論された型がボトム型の "Never" でなけれ
   ばならず、他の型ではいけません。

   実行時に呼び出すと例外を送出します。

   参考:

     静的型付けによる網羅性検査の詳細は、Unreachable Code and
     Exhaustiveness Checking を参照してください。

   Added in version 3.11.

typing.reveal_type(obj, /)

   式の推論された型を表示するよう、静的型チェッカーに要求します。

   静的型チェッカーは、この関数の呼び出しを検出すると、引数の推論され
   た型を診断メッセージとして出力します。 例えば次のようになります。

      x: int = 1
      reveal_type(x)  # 表示される型は "builtins.int"

   型チェッカーが特定のコードをどう扱うかをデバッグしたいときに役立ち
   ます。

   実行時には、引数の実際の型を "sys.stderr" に表示し、引数をそのまま
   返します (そのため、式の中で呼び出せます)。

      x = reveal_type(1)  # prints "Runtime type is int"
      print(x)  # prints "1"

   実行時の型は、型チェッカーが静的に推論した型と異なる場合があります
   (より具体的な場合も、より一般的な場合もあります)。

   ほとんどの型チェッカーは、"typing" から名前をインポートしていなくて
   も、どこでも "reveal_type()" を使えます。 ただし、"typing" からイン
   ポートしておくと、実行時エラーを起こさずにコードを実行でき、意図も
   より明確になります。

   Added in version 3.11.

@typing.dataclass_transform(*, eq_default=True, order_default=False, kw_only_default=False, frozen_default=False, field_specifiers=(), **kwargs)

   オブジェクトが "dataclass" のような振る舞いを提供することを示すデコ
   レータです。

   "@dataclass_transform" は、クラス、メタクラス、またはそれ自体がデコ
   レータである関数をデコレートできます。 "@dataclass_transform()" は
   、デコレートしたオブジェクトが、"@dataclasses.dataclass" と同じよう
   にクラスを変換する特別な処理を実行時に行うことを、静的型チェッカー
   に伝えます。

   デコレータ関数での使用例:

      @dataclass_transform()
      def create_model[T](cls: type[T]) -> type[T]:
          ...
          return cls

      @create_model
      class CustomerModel:
          id: int
          name: str

   基底クラスでの使用例です。

      @dataclass_transform()
      class ModelBase: ...

      class CustomerModel(ModelBase):
          id: int
          name: str

   メタクラスでの使用例です。

      @dataclass_transform()
      class ModelMeta(type): ...

      class ModelBase(metaclass=ModelMeta): ...

      class CustomerModel(ModelBase):
          id: int
          name: str

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

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

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

   パラメータ:
      * **eq_default** (*bool*) -- 呼び出し側が "eq" パラメータを省略
        したときに、"True" と "False" のどちらとみなすかを示します。
        デフォルトは "True" です。

      * **order_default** (*bool*) -- 呼び出し側が "order" パラメータ
        を省略したときに、"True" と "False" のどちらとみなすかを示しま
        す。 デフォルトは "False" です。

      * **kw_only_default** (*bool*) -- 呼び出し側が "kw_only" パラメ
        ータを省略したときに、"True" と "False" のどちらとみなすかを示
        します。 デフォルトは "False" です。

      * **frozen_default** (*bool*) --

        呼び出し側が "frozen" パラメータを省略したときに、"True" と
        "False" のどちらとみなすかを示します。 デフォルトは "False" で
        す。

        Added in version 3.12.

      * **field_specifiers** (*tuple**[**Callable**[**...**,
        **Any**]**, **...**]*) -- "dataclasses.field()" と同じようにフ
        ィールドを記述する、対応可能なクラスや関数の静的なリストを指定
        します。 デフォルトは "()" です。

      * ****kwargs** (*Any*) -- 将来の拡張を可能にするために、他の任意
        のキーワード引数も受け取れます。

   型チェッカーは、フィールド指定子の以下の省略可能なパラメータを認識
   します:


   **フィールド指定子で認識されるパラメータ**
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   +----------------------+----------------------------------------------------------------------------------+
   | パラメータ名         | 説明                                                                             |
   |======================|==================================================================================|
   | "init"               | 自動生成される "__init__" メソッドにフィールドを含めるかどうかを示 します。 指定 |
   |                      | しなければ、"init" のデフォルトは "True" です。                                  |
   +----------------------+----------------------------------------------------------------------------------+
   | "default"            | フィールドのデフォルト値を指定します。                                           |
   +----------------------+----------------------------------------------------------------------------------+
   | "default_factory"    | 実行時にフィールドのデフォルト値を返すコールバックを指定します。 "default" も    |
   |                      | "default_factory" も指定しない場合、フィールドにはデフ ォルト値がないものとみな  |
   |                      | され、クラスのインスタンス化時に値を渡す必 要があります。                        |
   +----------------------+----------------------------------------------------------------------------------+
   | "factory"            | フィールド指定子の "default_factory" パラメータのエイリアスです。                |
   +----------------------+----------------------------------------------------------------------------------+
   | "kw_only"            | フィールドをキーワード専用にするかどうかを示します。 "True" ならキ ーワード専用  |
   |                      | となり、"False" ならキーワード専用にはなりません。 指定 しなければ、             |
   |                      | "@dataclass_transform" でデコレートされたオブジェクトの "kw_only" パラメータの値 |
   |                      | を使います。 それも指定されていなければ、 "@dataclass_transform" の              |
   |                      | "kw_only_default" の値を使います。                                               |
   +----------------------+----------------------------------------------------------------------------------+
   | "alias"              | フィールドの別名を指定します。 この別名は、自動生成される "__init__" メソッドで  |
   |                      | 使われます。                                                                     |
   +----------------------+----------------------------------------------------------------------------------+

   実行時には、このデコレータは引数をデコレートしたオブジェクトの
   "__dataclass_transform__" 属性に記録します。 それ以外の実行時の効果
   はありません。

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

   Added in version 3.11.

@typing.overload

   オーバーロードされた関数やメソッドを作成するデコレータです。

   "@overload" デコレータは、引数の型の複数の組み合わせに対応する関数
   やメソッドを記述できます。 一連の "@overload" 付き定義の後には、同
   じ関数またはメソッドの "@overload" のない定義を 1 つだけ置く必要が
   あります。

   "@overload" 付きの定義は、その後の "@overload" のない定義で上書きさ
   れるため、型チェッカーのためだけに使われます。 一方、"@overload" の
   ない定義は実行時に使われますが、型チェッカーは呼び出しに対応するシ
   グネチャの判定ではこの定義を使いません。 実行時に "@overload" 付き
   の関数を直接呼び出すと、"NotImplementedError" が発生します。

   ユニオンや型変数では表現できない、より正確な型をオーバーロードで記
   述する例です:

      @overload
      def process(response: None) -> None:
          ...
      @overload
      def process(response: int) -> tuple[int, str]:
          ...
      @overload
      def process(response: bytes) -> str:
          ...
      def process(response):
          ...  # 実際の実装をここに書く

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

   バージョン 3.11 で変更: "get_overloads()" を使い、実行時にオーバー
   ロードされた関数を調べられるようになりました。

typing.get_overloads(func)

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

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

   "get_overloads()" は、実行時にオーバーロードされた関数を調べるため
   に使えます。

   Added in version 3.11.

typing.clear_overloads()

   内部レジストリに登録されたすべてのオーバーロードを消去します。

   レジストリが使用するメモリを解放するために使えます。

   Added in version 3.11.

@typing.final

   メソッドやクラスが final であることを示すデコレータです。

   メソッドを "@final" でデコレートすると、サブクラスでオーバーライド
   できないことを型チェッカーに伝えます。 クラスを "@final" でデコレー
   トすると、サブクラスを作成できないことを伝えます。

   例えば:

      class Base:
          @final
          def done(self) -> None:
              ...
      class Sub(Base):
          def done(self) -> None:  # 型チェッカーがエラーを報告する
              ...

      @final
      class Leaf:
          ...
      class Other(Leaf):  # 型チェッカーがエラーを報告する
          ...

   この機能は実行時には検査されません。詳細については **PEP 591** を参
   照してください。

   Added in version 3.8.

   バージョン 3.11 で変更: このデコレータは、デコレートしたオブジェク
   トの "__final__" 属性を "True" に設定しようとするようになりました。
   そのため、実行時に "if getattr(obj, "__final__", False)" などの検査
   で、オブジェクト "obj" が final と指定されているかどうかを調べられ
   ます。 デコレートしたオブジェクトが属性の設定に対応していなければ、
   例外を送出せずにそのオブジェクトをそのまま返します。

@typing.no_type_check

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

   クラスまたは関数の *デコレータ* として使えます。 クラスの場合、その
   クラス内で定義されたすべてのメソッドとクラスに再帰的に適用されます
   (スーパークラスやサブクラスで定義されたメソッドには適用されません)
   。 型チェッカーは、このデコレータを付けた関数やクラスのすべてのアノ
   テーションを無視します。

   "@no_type_check" は、デコレートしたオブジェクトをインプレースに変更
   します。

@typing.override

   サブクラスのメソッドが、スーパークラスのメソッドや属性をオーバーラ
   イドする意図を示すデコレータです。

   "@override" でデコレートされたメソッドが実際には何もオーバーライド
   していなければ、型チェッカーはエラーを報告すべきです。 これにより、
   基底クラスを変更したのに子クラスに対応する変更を加えなかった場合の
   バグを防ぎやすくなります。

   例えば:

      class Base:
          def log_status(self) -> None:
              ...

      class Sub(Base):
          @override
          def log_status(self) -> None:  # OK: Base.log_status をオーバーライドする
              ...

          @override
          def done(self) -> None:  # 型チェッカーがエラーを報告する
              ...

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

   このデコレータは、デコレートしたオブジェクトの "__override__" 属性
   を "True" に設定しようとします。 そのため、実行時に "if
   getattr(obj, "__override__", False)" などの検査で、オブジェクト
   "obj" がオーバーライドと指定されているかどうかを調べられます。 デコ
   レートしたオブジェクトが属性の設定に対応していなければ、例外を送出
   せずにそのオブジェクトをそのまま返します。

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

   Added in version 3.12.

@typing.disjoint_base

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

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

   例えば:

      @disjoint_base
      class Disjoint1: pass

      @disjoint_base
      class Disjoint2: pass

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

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

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

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

   Added in version 3.15.

@typing.type_check_only

   クラスや関数が実行時には使えないことを示すデコレータです。

   このデコレータ自身は実行時には使えません。 このデコレータは主に、実
   装がプライベートクラスのインスタンスを返す場合に、型スタブファイル
   に定義されているクラスに対して印を付けるためのものです:

      @type_check_only
      class Response:  # プライベート、または実行時には利用できない
          code: int
          def get_header(self, name: str) -> str: ...

      def fetch_response() -> Response: ...

   プライベートクラスのインスタンスを返すのは推奨されません。 そのよう
   なクラスは公開クラスにするのが望ましいです。


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

typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False, *, format=Format.VALUE)

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

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

   * 文字列リテラルや "ForwardRef" オブジェクトとして記述された前方参
     照は、*globalns*、*localns*、 該当する場合は *obj* の 型引数 の名
     前空間で評価して処理します。 *globalns* や *localns* を指定しなけ
     れば、*obj* から適切な名前空間の辞書を推定します。

   * "None" を "types.NoneType" に置き換えます。

   * *obj* に "@no_type_check" が適用されていれば、空の辞書を返します
     。

   * *obj* がクラス "C" の場合、"C" に直接付けられたアノテーションと、
     "C" の基底クラスのアノテーションを統合した辞書を返します。
     "C.__mro__" をたどり、各基底クラスの *アノテーション* を順に統合
     します。 *メソッド解決順序* で先に現れるクラスのアノテーションは
     、後に現れるクラスのアノテーションより常に優先されます。

   * *include_extras* が "True" でなければ、"Annotated[T, ...]"、
     "Required[T]"、"NotRequired[T]"、"ReadOnly[T]" を、再帰的にすべて
     "T" に置き換えます (詳細は "Annotated" を参照)。

   注意:

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

   注釈:

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

   注釈:

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

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

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

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

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

typing.get_origin(tp)

   型から添字を取り除いたものを取得します。 "X[Y, Z, ...]" の形式の型
   付けオブジェクトに対して "X" を返します。

   "X" が、組み込みクラスや "collections" のクラスに対する typing モジ
   ュールのエイリアスなら、元のクラスに正規化します。 "X" が
   "ParamSpecArgs" または "ParamSpecKwargs" のインスタンスなら、元の
   "ParamSpec" を返します。 対応していないオブジェクトでは "None" を返
   します。

   例:

      assert get_origin(str) is None
      assert get_origin(Dict[str, int]) is dict
      assert get_origin(Union[int, str]) is Union
      assert get_origin(Annotated[str, "metadata"]) is Annotated
      P = ParamSpec('P')
      assert get_origin(P.args) is P
      assert get_origin(P.kwargs) is P

   Added in version 3.8.

typing.get_args(tp)

   すべての代入を適用した型引数を取得します。 "X[Y, Z, ...]" の形式の
   型付けオブジェクトに対して "(Y, Z, ...)" を返します。

   "X" が他のジェネリック型の中に含まれるユニオンまたは "Literal" の場
   合、型のキャッシュにより、 "(Y, Z, ...)" の順序が元の引数 "[Y, Z,
   ...]" の順序と異なる場合があります。 対応していないオブジェクトでは
   "()" を返します。

   例:

      assert get_args(int) == ()
      assert get_args(Dict[int, str]) == (int, str)
      assert get_args(Union[int, str]) == (int, str)

   Added in version 3.8.

typing.get_protocol_members(tp)

   "Protocol" に定義されたメンバーの集合を返します。

      >>> from typing import Protocol, get_protocol_members
      >>> class P(Protocol):
      ...     def a(self) -> str: ...
      ...     b: int
      >>> get_protocol_members(P) == frozenset({'a', 'b'})
      True

   引数がプロトコルでなければ "TypeError" を送出します。

   Added in version 3.13.

typing.is_protocol(tp)

   型が "Protocol" であるかどうかを判定します。

   例えば:

      class P(Protocol):
          def a(self) -> str: ...
          b: int

      assert is_protocol(P)
      assert not is_protocol(int)

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

      class GenericP[T](Protocol):
          def a(self) -> T: ...
          b: int

      assert not is_protocol(GenericP[int])

   Added in version 3.13.

typing.is_typeddict(tp)

   型が "TypedDict" であるかどうかを調べます。

   例えば:

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

      assert is_typeddict(Film)
      assert not is_typeddict(list | str)

      # TypedDict は型付き辞書を作成するファクトリであり、
      # それ自体が型付き辞書ではない
      assert not is_typeddict(TypedDict)

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

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

      assert not is_typeddict(GenericFilm[int])

   Added in version 3.10.

class typing.ForwardRef

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

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

   注釈:

     **PEP 585** generic types such as "list["SomeClass"]" will not be
     implicitly transformed into "list[ForwardRef("SomeClass")]" and
     thus will not automatically resolve to "list[SomeClass]".

   Added in version 3.7.4.

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

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

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

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

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

   注意:

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

   Added in version 3.14.

typing.NoDefault

   型引数にデフォルト値がないことを示すセンチネルオブジェクトです。 例
   えば次のように使います:

      >>> T = TypeVar("T")
      >>> T.__default__ is typing.NoDefault
      True
      >>> S = TypeVar("S", default=None)
      >>> S.__default__ is None
      True

   Added in version 3.13.

typing.NoExtraItems

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

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


定数
----

typing.TYPE_CHECKING

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

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

   使い方:

      if TYPE_CHECKING:
          import expensive_mod

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

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

   Added in version 3.5.2.


非推奨のエイリアス
------------------

このモジュールは、既存の標準ライブラリクラスに対する非推奨のエイリアス
をいくつか定義しています。 これらは、ジェネリッククラスを "[]" でパラ
メータ化できるようにするため、元々 "typing" モジュールに追加されました
。 しかし Python 3.9 で、対応する既存クラスが "[]" に対応したため、エ
イリアスは不要になりました (**PEP 585** を参照)。

これらの不要になった型は Python 3.9 以降、非推奨です。 ただし、将来削
除される可能性はあるものの、現時点では削除予定はありません。 そのため
、これらのエイリアスについてインタープリタは現在、非推奨警告を出してい
ません。

将来、これらの非推奨エイリアスを削除すると決まった場合は、削除の少なく
とも 2 リリース前からインタープリタが非推奨警告を出すことになります。
少なくとも Python 3.14 までは、非推奨警告なしで "typing" モジュールに
残ることが保証されています。

検査対象のプログラムが Python 3.9 以降を最低対応バージョンとしている場
合、型チェッカーは非推奨の型の使用を報告することが推奨されます。


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

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

   "dict" の非推奨なエイリアス。

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

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

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

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

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

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

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

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

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

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

class typing.FrozenSet(frozenset, AbstractSet[T_co])

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

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

typing.Tuple

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

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

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

class typing.Type(Generic[CT_co])

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

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

   Added in version 3.5.2.

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


"collections" の型のエイリアス
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])

   "collections.defaultdict" の非推奨なエイリアス。

   Added in version 3.5.2.

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

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])

   "collections.OrderedDict" の非推奨なエイリアス。

   Added in version 3.7.2.

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

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])

   "collections.ChainMap" の非推奨なエイリアス。

   Added in version 3.6.1.

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

class typing.Counter(collections.Counter, Dict[T, int])

   "collections.Counter" の非推奨なエイリアス。

   Added in version 3.6.1.

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

class typing.Deque(deque, MutableSequence[T])

   "collections.deque" の非推奨なエイリアス。

   Added in version 3.6.1.

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


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

class typing.Pattern
class typing.Match

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

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

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

class typing.Text

   "str" の非推奨のエイリアスです。

   "Text" は Python 2 のコードに前方互換性を持たせるために提供されてい
   ます。 Python 2 では "Text" は "unicode" のエイリアスです。

   Python 2 と Python 3 の両方に対応する形で、値が Unicode 文字列でな
   ければならないことを示すには "Text" を使います。

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

   Added in version 3.5.2.

   バージョン 3.11 で非推奨: Python 2 のサポートは終了しており、ほとん
   どの型チェッカーも Python 2 コードの型チェックに対応しなくなりまし
   た。 このエイリアスの削除予定は現時点ではありませんが、"Text" の代
   わりに "str" を使うことが推奨されます。


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

class typing.AbstractSet(Collection[T_co])

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

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

class typing.ByteString(Sequence[int])

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

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

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

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

   バージョン 3.9 で非推奨、バージョン 3.17 で削除予定.

class typing.Collection(Sized, Iterable[T_co], Container[T_co])

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

   Added in version 3.6.

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

class typing.Container(Generic[T_co])

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

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

class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])

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

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

class typing.KeysView(MappingView, AbstractSet[KT_co])

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

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

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

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

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

class typing.MappingView(Sized)

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

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

class typing.MutableMapping(Mapping[KT, VT])

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

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

class typing.MutableSequence(Sequence[T])

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

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

class typing.MutableSet(AbstractSet[T])

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

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

class typing.Sequence(Reversible[T_co], Collection[T_co])

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

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

class typing.ValuesView(MappingView, Collection[_VT_co])

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

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


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

class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])

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

   型アノテーションで "collections.abc.Coroutine" と
   "typing.Coroutine" を使う方法の詳細は、ジェネレータとコルーチンのア
   ノテーション を参照してください。

   Added in version 3.5.3.

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

class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])

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

   型アノテーションで "collections.abc.AsyncGenerator" と
   "typing.AsyncGenerator" を使う方法の詳細は、ジェネレータとコルーチ
   ンのアノテーション を参照してください。

   Added in version 3.6.1.

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

   バージョン 3.13 で変更: "SendType" 型引数にデフォルト値が追加されま
   した。

class typing.AsyncIterable(Generic[T_co])

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

   Added in version 3.5.2.

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

class typing.AsyncIterator(AsyncIterable[T_co])

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

   Added in version 3.5.2.

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

class typing.Awaitable(Generic[T_co])

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

   Added in version 3.5.2.

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


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

class typing.Iterable(Generic[T_co])

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

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

class typing.Iterator(Iterable[T_co])

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

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

typing.Callable

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

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

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

   バージョン 3.10 で変更: "Callable" は "ParamSpec" と "Concatenate"
   をサポートしました。詳細は **PEP 612** を参照してください。

class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])

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

   型アノテーションで "collections.abc.Generator" と
   "typing.Generator" を使う方法の詳細は、ジェネレータとコルーチンのア
   ノテーション を参照してください。

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

   バージョン 3.13 で変更: 送信する値の型と戻り値の型にデフォルト値が
   追加されました。

class typing.Hashable

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

   バージョン 3.12 で非推奨: 代わりに "collections.abc.Hashable" を直
   接使用してください。

class typing.Reversible(Iterable[T_co])

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

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

class typing.Sized

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

   バージョン 3.12 で非推奨: 代わりに "collections.abc.Sized" を直接使
   用してください。


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

class typing.ContextManager(Generic[T_co, ExitT_co])

   "contextlib.AbstractContextManager" の非推奨なエイリアス。

   最初の型引数 "T_co" は、"__enter__()" メソッドが返す値の型を表しま
   す。 省略可能な 2 番目の型引数 "ExitT_co" は、"__exit__()" メソッド
   が返す値の型を表し、デフォルトは "bool | None" です。

   Added in version 3.5.4.

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

   バージョン 3.13 で変更: 省略可能な 2 番目の型引数 "ExitT_co" を追加
   しました。

class typing.AsyncContextManager(Generic[T_co, AExitT_co])

   "contextlib.AbstractAsyncContextManager" の非推奨なエイリアス。

   最初の型引数 "T_co" は、"__aenter__()" メソッドが返す値の型を表しま
   す。 省略可能な 2 番目の型引数 "AExitT_co" は、"__aexit__()" メソッ
   ドが返す値の型を表し、デフォルトは "bool | None" です。

   Added in version 3.6.2.

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

   バージョン 3.13 で変更: 省略可能な 2 番目の型引数 "AExitT_co" を追
   加しました。


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

"typing" の機能の中には非推奨のものがあり、Python の将来のバージョンで
削除される可能性があります。以下の表は主な非推奨機能をまとめたものです
。これは変更される可能性があり、すべての非推奨機能がリストされているわ
けではありません。

+---------------------------+---------------------------+---------------------------+---------------------------+
| 機能                      | 非推奨となるバージョン    | 削除予定のバージョン      | PEP/issue                 |
|===========================|===========================|===========================|===========================|
| 標準コレクションのエイリ  | 3.9                       | 未定（非推奨のエイリアス  | **PEP 585**               |
| アス                      |                           | を参照）                  |                           |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "typing.ByteString"       | 3.9                       | 3.17                      | gh-91896                  |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "typing.Text"             | 3.11                      | 未定                      | gh-92332                  |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "typing.Hashable"、       | 3.12                      | 未定                      | gh-94309                  |
| "typing.Sized"            |                           |                           |                           |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "typing.TypeAlias"        | 3.12                      | 未定                      | **PEP 695**               |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "typing.AnyStr"           | 3.13                      | 3.18                      | gh-105578                 |
+---------------------------+---------------------------+---------------------------+---------------------------+
