"types" --- 動的な型生成と組み込み型の名前
******************************************

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

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

このモジュールは新しい型の動的な生成を支援するユーティリティ関数を定義
します。

さらに、標準の Python インタプリタによって使用されているものの、 "int"
や "str" のように組み込みとして公開されていないようないくつかのオブジ
ェクト型の名前を定義しています。

さらに、組み込みにするほど基本的ではない、型に関連する補助的なユーティ
リティクラスや関数も提供します。


動的な型生成
============

types.new_class(name, bases=(), kwds=None, exec_body=None)

   適切なメタクラスを使用して動的にクラスオブジェクトを生成します。

   最初の3つの引数はクラス定義ヘッダーを構成する—クラス名、基底クラス
   (順番に)、キーワード引数 (例えば "metaclass")—です。

   *exec_body* 引数は、新規に生成されたクラスの名前空間を構築するため
   に使用されるコールバックです。それは唯一の引数としてクラスの名前空
   間を受け取り、クラスの内容で名前空間を直接更新します。コールバック
   が渡されない場合、それは "lambda ns: None" を渡すことと同じ効果があ
   ります。

   Added in version 3.3.

types.prepare_class(name, bases=(), kwds=None)

   適切なメタクラスを計算してクラスの名前空間を生成します。

   引数はクラス定義ヘッダーを構成する要素—クラス名、基底クラス (順番に
   )、キーワード引数 (例えば "metaclass")—です。

   返り値は "metaclass, namespace, kwds" の3要素のタプルです

   *metaclass* は適切なメタクラスです。*namespace* は用意されたクラス
   の名前空間です。また *kwds* は、"'metaclass'" エントリが削除された
   、渡された *kwds* 引数の更新されたコピーです。*kwds* 引数が渡されな
   ければ、これは空の dict になります。

   Added in version 3.3.

   バージョン 3.6 で変更: 返されるタプルの "namespace" 要素のデフォル
   ト値が変更されました。 現在では、メタクラスが "__prepare__" メソッ
   ドを持っていないときは、挿入順序を保存するマッピングが使われます。

参考:

  メタクラス
     これらの関数によってサポートされるクラス生成プロセスの完全な詳細

  **PEP 3115** - Metaclasses in Python 3000
     "__prepare__" 名前空間フックの導入

types.resolve_bases(bases)

   **PEP 560** の規定に従って MRO の項目を動的に解決します。

   この関数は *bases* から "type" のインスタンスでない項目を探します。
   そのようなオブジェクトが "__mro_entries__()" メソッドを持つ場合は、
   このメソッドの呼び出し結果を展開して置き換えたタプルを返します。
   *bases* の項目が "type" のインスタンスであるか、"__mro_entries__()"
   メソッドを持たない場合は、変更せずに戻り値のタプルに含めます。

   Added in version 3.7.

types.get_original_bases(cls, /)

   **PEP 560** の仕組みに従って各基底の "__mro_entries__()" メソッドが
   呼び出される前に、*cls* の基底として最初に指定されたオブジェクトの
   タプルを返します。 ジェネリック のイントロスペクションに役立ちます
   。

   クラスが "__orig_bases__" 属性を持つ場合は、"cls.__orig_bases__" の
   値を返します。 "__orig_bases__" 属性を持たない場合は、
   "cls.__bases__" を返します。

   例:

      from typing import TypeVar, Generic, NamedTuple, TypedDict

      T = TypeVar("T")
      class Foo(Generic[T]): ...
      class Bar(Foo[int], float): ...
      class Baz(list[str]): ...
      Eggs = NamedTuple("Eggs", [("a", int), ("b", str)])
      Spam = TypedDict("Spam", {"a": int, "b": str})

      assert Bar.__bases__ == (Foo, float)
      assert get_original_bases(Bar) == (Foo[int], float)

      assert Baz.__bases__ == (list,)
      assert get_original_bases(Baz) == (list[str],)

      assert Eggs.__bases__ == (tuple,)
      assert get_original_bases(Eggs) == (NamedTuple,)

      assert Spam.__bases__ == (dict,)
      assert get_original_bases(Spam) == (TypedDict,)

      assert int.__bases__ == (object,)
      assert get_original_bases(int) == (object,)

   Added in version 3.12.

参考: **PEP 560** - typing モジュールとジェネリック型に対する言語コアによ
    るサポート


標準的なインタプリタ型
======================

このモジュールは、Python インタプリタを実装するために必要な多くの型に
対して名前を提供します。それは、"listiterator" 型のような、単に処理中
に付随的に発生するいくつかの型が含まれることを意図的に避けています。

これらの名前は典型的に "isinstance()" や "issubclass()" によるチェック
に使われます。

これらのタイプのいずれかをインスタンス化する場合、シグネチャは Python
のバージョンによって異なる可能性があることに注意してください。

以下の型に対して標準的な名前が定義されています:

class types.NoneType

   "None" の型です。

   Added in version 3.10.

class types.FunctionType
class types.LambdaType

   ユーザ定義の関数と "lambda" 式によって生成された関数の型です。

   引数 "code" を指定して 監査イベント "function.__new__" を送出します
   。

   この監査イベントは、関数オブジェクトを直接インスタンス化した場合に
   のみ発生し、通常のコンパイル時には発生しません。

class types.GeneratorType

   ジェネレータ関数によって生成された *ジェネレータ* イテレータオブジ
   ェクトの型です。

class types.CoroutineType

   "async def" 関数に生成される *コルーチン* オブジェクトの型です。

   Added in version 3.5.

class types.AsyncGeneratorType

   非同期ジェネレータ関数によって作成された *非同期ジェネレータ* イテ
   レータオブジェクトの型です。

   Added in version 3.6.

class types.CodeType(**kwargs)

   "compile()" が返すものなど、コードオブジェクト の型です。

   引数 "code", "filename", "name", "argcount", "posonlyargcount",
   "kwonlyargcount", "nlocals", "stacksize", "flags" を指定して 監査イ
   ベント "code.__new__" を送出します。

   監査の対象となる引数の名前や位置は、初期化子が要求するものと一致し
   ない場合があります。 この監査イベントはコードオブジェクトを直接イン
   スタンス化したときにのみ発生し、通常のコンパイル時には発生しません
   。

class types.CellType

   セルオブジェクトの型です。 セルオブジェクトは、関数の *クロージャ変
   数* を格納するコンテナとして使われます。

   Added in version 3.8.

class types.MethodType

   ユーザー定義のクラスのインスタンスのメソッドの型です。

class types.BuiltinFunctionType
class types.BuiltinMethodType

   "len()" や "sys.exit()" のような組み込み関数や、組み込み型のメソッ
   ドの型です。 (ここでは "組み込み" という単語を "Cで書かれた" という
   意味で使っています)

class types.WrapperDescriptorType

   "object.__init__()" や "object.__lt__()" など、一部の組み込みデータ
   型や基底クラスのメソッドの型です。

   Added in version 3.7.

class types.MethodWrapperType

   一部の組み込みデータ型や基底クラスの *束縛された* メソッドの型です
   。 例えば "object().__str__" の型がこれに当たります。

   Added in version 3.7.

class types.NotImplementedType

   "NotImplemented" の型です。

   Added in version 3.10.

class types.MethodDescriptorType

   "str.join()" など、一部の組み込みデータ型のメソッドの型です。

   Added in version 3.7.

class types.ClassMethodDescriptorType

   "dict.__dict__['fromkeys']" など、一部の組み込みデータ型の *束縛さ
   れていない* クラスメソッドの型です。

   Added in version 3.7.

class types.ModuleType(name, doc=None)

   *module* の型です。コンストラクタは生成するモジュールの名前と任意で
   その *docstring* を受け取ります。

   参考:

     モジュールオブジェクトのドキュメント
        "ModuleType" のインスタンスが持つ特殊属性について詳しく説明し
        ています。

     "importlib.util.module_from_spec()"
        "ModuleType" コンストラクタで作成したモジュールでは、多くの特
        殊属性が未設定かデフォルト値のままです。 "module_from_spec()"
        を使うと、各種属性が適切に設定される、より確実な方法で
        "ModuleType" のインスタンスを作成できます。

class types.EllipsisType

   "Ellipsis" の型です。

   Added in version 3.10.

class types.GenericAlias(t_origin, t_args)

   "list[int]" など、パラメータ化されたジェネリック の型です。

   "t_origin" は "list"、"tuple"、"dict" などのパラメータ化されていな
   いジェネリッククラスである必要があります。 "t_args" は "t_origin"
   をパラメータ化する型の "tuple" です (長さが 1 でも構いません)。

      >>> from types import GenericAlias

      >>> list[int] == GenericAlias(list, (int,))
      True
      >>> dict[str, int] == GenericAlias(dict, (str, int))
      True

   Added in version 3.9.

   バージョン 3.9.2 で変更: この型のサブクラスを作成できるようになりま
   した。

   参考:

     ジェネリックエイリアス型
        "types.GenericAlias" のインスタンスについて詳しく説明したドキ
        ュメント

     **PEP 585** - 標準コレクション型の型ヒントにおける総称型
     (generics) の使用
        "types.GenericAlias" クラスの導入

class types.UnionType

   ユニオン型の式 の型です。

   Added in version 3.10.

   バージョン 3.14 で変更: "typing.Union" のエイリアスになりました。

class types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

   "sys.exception().__traceback__" に含まれるようなトレースバックオブ
   ジェクトの型です。

   利用できる属性と操作の詳細、およびトレースバックを動的に作成する方
   法は、言語リファレンス を参照してください。

class types.FrameType

   "tb" がトレースバックオブジェクトである場合の "tb.tb_frame" など、
   フレームオブジェクト の型です。

class types.FrameLocalsProxyType

   "frame.f_locals" 属性にあるような、フレームのローカル変数のプロキシ
   オブジェクトの型です。

   Added in version 3.15.

   参考: **PEP 667**

class types.LazyImportType

   遅延インポートのプロキシオブジェクトの型です。 これらのオブジェクト
   はモジュールが遅延インポートされたときに作成され、実際にモジュール
   にアクセスするまでプレースホルダーとして機能します。 この型を使うと
   、プログラムで遅延インポートを検出できます。

   Added in version 3.15.

   参考: **PEP 810**

   resolve()

      遅延インポートを実行し、インポートされる「実際の」オブジェクトを
      返します。

class types.GetSetDescriptorType

   "FrameType.f_locals" や "array.array.typecode" など、拡張モジュール
   で "PyGetSetDef" を使って定義されたオブジェクトの型です。 この型は
   オブジェクトの属性のデスクリプタとして使われます。 "property" 型と
   同じ目的を持ちますが、拡張モジュールで定義されたクラス用です。

class types.MemberDescriptorType

   "datetime.timedelta.days" など、拡張モジュールで "PyMemberDef" を使
   って定義されたオブジェクトの型です。 この型は、標準の変換関数を利用
   する単純な C データメンバーのデスクリプタとして使われます。
   "property" 型と同じ目的を持ちますが、拡張モジュールで定義されたクラ
   ス用です。

   また、クラスが "__slots__" 属性を使って定義されている場合は、各スロ
   ットに対して "MemberDescriptorType" のインスタンスがクラス属性とし
   て追加されます。 これにより、スロットがクラスの "__dict__" に現れる
   ようになります。

   Pythonの他の実装では、この型は "GetSetDescriptorType" と同じかもし
   れません。

class types.MappingProxyType(mapping)

   読み出し専用のマッピングのプロキシです。マッピングのエントリーに関
   する動的なビューを提供します。つまり、マッピングが変わった場合にビ
   ューがこれらの変更を反映するということです。

   "MappingProxyType" は 2 つの型を引数とする ジェネリック です。 型引
   数は順に、元になったマッピングのキーと値の型を表します。

   Added in version 3.3.

   バージョン 3.9 で変更: **PEP 584** の新しい和集合演算子 ("|") に対
   応しました。 演算はそのまま元になったマッピングに委譲します。

   key in proxy

      元になったマッピングが *key* というキーを持っている場合 "True"
      を返します。そうでなければ "False" を返します。

   proxy[key]

      元になったマッピングの *key* というキーに対応するアイテムを返し
      ます。 *key* が存在しなければ、 "KeyError" が発生します。

   iter(proxy)

      元になったマッピングのキーを列挙するイテレータを返します。これは
      "iter(proxy.keys())" のショートカットです。

   len(proxy)

      元になったマッピングに含まれるアイテムの数を返します。

   copy()

      元になったマッピングの浅いコピーを返します。

   get(key[, default])

      *key* が元になったマッピングに含まれている場合 *key* に対する値
      を返し、そうでなければ *default* を返します。もし *default* が与
      えられない場合は、デフォルト値の "None" になります。そのため、こ
      のメソッドが "KeyError" を発生させることはありません。

   items()

      元になったマッピングの items ("(key, value)" ペアの列) に対する
      新しいビューを返します。

   keys()

      元になったマッピングの keys に対する新しいビューを返します。

   values()

      元になったマッピングの values に対する新しいビューを返します。

   reversed(proxy)

      元になったマッピングのキーを逆順にたどるイテレータを返します。

      Added in version 3.9.

   hash(proxy)

      元になったマッピングのハッシュ値を返します。

      Added in version 3.12.

class types.CapsuleType

   カプセルオブジェクト の型です。

   Added in version 3.13.


追加のユーティリティクラスと関数
================================

class types.SimpleNamespace

   名前空間への属性アクセスに加えて意味のある repr を提供するための、
   単純な "object" サブクラスです。

   "object" とは異なり、"SimpleNamespace" では属性を追加したり削除した
   りできます。

   "SimpleNamespace" オブジェクトは "dict" と同じように、キーワード引
   数、単一の位置引数、またはその両方で初期化できます。 キーワード引数
   で初期化する場合は、それらが内部の名前空間に直接追加されます。 位置
   引数で初期化する場合は、その引数から得られるキーと値のペアで内部の
   名前空間を更新します。 位置引数には、マッピングオブジェクトか、キー
   と値のペアを生成する *イテラブル* オブジェクトを指定できます。 これ
   らのキーはすべて文字列でなければなりません。

   この型は以下のコードとほぼ等価です:

      class SimpleNamespace:
          def __init__(self, mapping_or_iterable=(), /, **kwargs):
              self.__dict__.update(mapping_or_iterable)
              self.__dict__.update(kwargs)

          def __repr__(self):
              items = (f"{k}={v!r}" for k, v in self.__dict__.items())
              return "{}({})".format(type(self).__name__, ", ".join(items))

          def __eq__(self, other):
              if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
                 return self.__dict__ == other.__dict__
              return NotImplemented

   "SimpleNamespace" は "class NS: pass" を置き換えるものとして有用か
   もしれません。ですが、構造化されたレコード型に対しては、これよりは
   むしろ "namedtuple()" を使用してください。

   "copy.replace()" は "SimpleNamespace" オブジェクトに対応しています
   。

   Added in version 3.3.

   バージョン 3.9 で変更: repr での属性の順序が、アルファベット順から
   ("dict" と同じ) 挿入順に変わりました。

   バージョン 3.13 で変更: 省略可能な位置引数に対応しました。

types.DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)

   クラスの属性アクセスを __getattr__ に振り替えます。

   これは記述子で、インスタンス経由のアクセスとクラス経由のアクセスで
   振る舞いが異なる属性を定義するのに使います。インスタンスアクセスは
   通常通りですが、クラス経由の属性アクセスはクラスの __getattr__ メソ
   ッドに振り替えられます。これは AttributeError の送出により行われま
   す。

   これによって、インスタンス上で有効なプロパティを持ち、クラス上で同
   名の仮想属性を持つことができます (例については "enum.Enum" を参照し
   てください)。

   Added in version 3.4.


コルーチンユーティリティ関数
============================

types.coroutine(gen_func)

   この関数は *ジェネレータ* 関数を、ジェネレータベースのコルーチンを
   返す *コルーチン関数* に変換します。 ジェネレータベースのコルーチン
   は依然として *ジェネレータイテレータ* ですが、*コルーチン* オブジェ
   クトかつ *awaitable* ともみなされます。 ただし、必ずしも
   "__await__()" メソッドを実装しているとは限りません。

   *gen_func* がジェネレータ関数の場合、その関数をインプレースに変更し
   ます。

   *gen_func* がジェネレータ関数でない場合、この関数はラップされます。
   この関数が "collections.abc.Generator" のインスタンスを返す場合、こ
   のインスタンスは *awaitable* なプロキシオブジェクトにラップされます
   。それ以外のすべての型のオブジェクトは、そのまま返されます。

   Added in version 3.5.
