"inspect" --- 活動中のオブジェクトを調査する
********************************************

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

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

"inspect" は、活動中のオブジェクト (モジュール、クラス、メソッド、関数
、トレースバック、フレームオブジェクト、コードオブジェクトなど) から情
報を取得する関数を定義しており、クラスの内容を調べたり、メソッドのソー
スコードを取得したり、関数の引数リストを取り出して整形したり、詳細なト
レースバックを表示するのに必要な情報を取得したりするために利用できます
。

このモジュールの機能は4種類に分類することができます。型チェック、ソー
スコードの情報取得、クラスや関数からの情報取得、インタープリタのスタッ
ク情報の調査です。


型とメンバー
============

"getmembers()" は、クラスやモジュールなどのオブジェクトからメンバーを
取得します。名前が "is" で始まる関数は、主に "getmembers()" の第2引数
として利用するために提供されています。以下のような特殊属性を参照できる
かどうか調べる時にも使えるでしょう (モジュール属性については Import-
related attributes on module objects を参照してください):

+-------------------+---------------------+-----------------------------+
| 型                | 属性                | 説明                        |
|===================|=====================|=============================|
| クラス            | __doc__             | ドキュメント文字列          |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | クラスの定義名              |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | __module__          | クラスを定義しているモジュ  |
|                   |                     | ールの名前                  |
+-------------------+---------------------+-----------------------------+
|                   | __type_params__     | ジェネリッククラスの 型パラ |
|                   |                     | メータ (type parameters) を |
|                   |                     | 含むタプル                  |
+-------------------+---------------------+-----------------------------+
| メソッド          | __doc__             | ドキュメント文字列          |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | メソッドの定義名            |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | __func__            | メソッドを実装している関数  |
|                   |                     | オブジェクト                |
+-------------------+---------------------+-----------------------------+
|                   | __self__            | メソッドに結合しているイン  |
|                   |                     | スタンス、または "None"     |
+-------------------+---------------------+-----------------------------+
|                   | __module__          | このメソッドが定義されてい  |
|                   |                     | るモジュールの名前          |
+-------------------+---------------------+-----------------------------+
| 関数              | __doc__             | ドキュメント文字列          |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | 関数の定義名                |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | __code__            | 関数をコンパイルした *バイ  |
|                   |                     | トコード* を格納するコード  |
|                   |                     | オブジェクト                |
+-------------------+---------------------+-----------------------------+
|                   | __defaults__        | 位置またはキーワード引数の  |
|                   |                     | 全ての既定値のタプル        |
+-------------------+---------------------+-----------------------------+
|                   | __kwdefaults__      | キーワード専用引数の全ての  |
|                   |                     | 既定値のマッピング          |
+-------------------+---------------------+-----------------------------+
|                   | __globals__         | 関数が定義されたグローバル  |
|                   |                     | 名前空間                    |
+-------------------+---------------------+-----------------------------+
|                   | __builtins__        | 組み込みモジュールの名前空  |
|                   |                     | 間                          |
+-------------------+---------------------+-----------------------------+
|                   | __annotations__     | 仮引数名からアノテーション  |
|                   |                     | へのマッピング; ""return""  |
|                   |                     | キーは return ア ノテーショ |
|                   |                     | ンに予約されています        |
+-------------------+---------------------+-----------------------------+
|                   | __type_params__     | ジェネリック関数の 型パラメ |
|                   |                     | ータ (type parameters) を含 |
|                   |                     | むタプル                    |
+-------------------+---------------------+-----------------------------+
|                   | __module__          | この関数が定義されているモ  |
|                   |                     | ジュールの名前              |
+-------------------+---------------------+-----------------------------+
| traceback         | tb_frame            | このレベルのフレームオブジ  |
|                   |                     | ェクト                      |
+-------------------+---------------------+-----------------------------+
|                   | tb_lasti            | 最後に実行しようとしたバイ  |
|                   |                     | トコード中のインストラクシ  |
|                   |                     | ョンを示すインデッ クス     |
+-------------------+---------------------+-----------------------------+
|                   | tb_lineno           | 現在の Python ソースコード  |
|                   |                     | の行番号                    |
+-------------------+---------------------+-----------------------------+
|                   | tb_next             | このオブジェクトの内側 (こ  |
|                   |                     | のレベルから呼び出された)   |
|                   |                     | のトレースバックオ ブジェク |
|                   |                     | ト                          |
+-------------------+---------------------+-----------------------------+
| フレーム          | f_back              | 外側 (このフレームを呼び出  |
|                   |                     | した) のフレームオブジェク  |
|                   |                     | ト                          |
+-------------------+---------------------+-----------------------------+
|                   | f_builtins          | このフレームで参照している  |
|                   |                     | 組み込み名前空間            |
+-------------------+---------------------+-----------------------------+
|                   | f_code              | このフレームで実行している  |
|                   |                     | コードオブジェクト          |
+-------------------+---------------------+-----------------------------+
|                   | f_globals           | このフレームで参照している  |
|                   |                     | グローバル名前空間          |
+-------------------+---------------------+-----------------------------+
|                   | f_lasti             | 最後に実行しようとしたバイ  |
|                   |                     | トコード中のインストラクシ  |
|                   |                     | ョンを示すインデッ クス     |
+-------------------+---------------------+-----------------------------+
|                   | f_lineno            | 現在の Python ソースコード  |
|                   |                     | の行番号                    |
+-------------------+---------------------+-----------------------------+
|                   | f_locals            | このフレームで参照している  |
|                   |                     | ローカル名前空間            |
+-------------------+---------------------+-----------------------------+
|                   | f_trace             | このフレームのトレース関数  |
|                   |                     | 、または "None"             |
+-------------------+---------------------+-----------------------------+
| コード            | co_argcount         | 引数の数 (キーワード限定引  |
|                   |                     | 数、および * や ** は含まな |
|                   |                     | い)                         |
+-------------------+---------------------+-----------------------------+
|                   | co_code             | コンパイルされたバイトコー  |
|                   |                     | ドそのままの文字列          |
+-------------------+---------------------+-----------------------------+
|                   | co_cellvars         | (自身が包含するスコープから |
|                   |                     | 参照される) セル変数の名前  |
|                   |                     | のタプル                    |
+-------------------+---------------------+-----------------------------+
|                   | co_consts           | バイトコード中で使用してい  |
|                   |                     | る定数のタプル              |
+-------------------+---------------------+-----------------------------+
|                   | co_filename         | コードオブジェクトを生成し  |
|                   |                     | たファイルのファイル名      |
+-------------------+---------------------+-----------------------------+
|                   | co_firstlineno      | Python ソースコードの先頭行 |
+-------------------+---------------------+-----------------------------+
|                   | co_flags            | "CO_*" ビットフラグのマップ |
|                   |                     | 。詳細は こちら を参照。    |
+-------------------+---------------------+-----------------------------+
|                   | co_lnotab           | 行番号からバイトコードイン  |
|                   |                     | デックスへの変換表を文字列  |
|                   |                     | にエンコードしたも の       |
+-------------------+---------------------+-----------------------------+
|                   | co_freevars         | (関数のクロージャを介して参 |
|                   |                     | 照される) 自由変数の名前の  |
|                   |                     | タプル                      |
+-------------------+---------------------+-----------------------------+
|                   | co_posonlyargcount  | 位置専用引数の数            |
+-------------------+---------------------+-----------------------------+
|                   | co_kwonlyargcount   | キーワード専用引数 (** 引数 |
|                   |                     | を含まない) の数            |
+-------------------+---------------------+-----------------------------+
|                   | co_name             | コードオブジェクトが定義さ  |
|                   |                     | れたときの名前              |
+-------------------+---------------------+-----------------------------+
|                   | co_qualname         | このコードオブジェクトが定  |
|                   |                     | 義されたときの完全修飾名    |
|                   |                     | (fully qualified name)      |
+-------------------+---------------------+-----------------------------+
|                   | co_names            | 関数の引数でもローカル変数  |
|                   |                     | でもない名前のタプル        |
+-------------------+---------------------+-----------------------------+
|                   | co_nlocals          | ローカル変数の数            |
+-------------------+---------------------+-----------------------------+
|                   | co_stacksize        | 必要とされる仮想マシンのス  |
|                   |                     | タックスペース              |
+-------------------+---------------------+-----------------------------+
|                   | co_varnames         | 引数名とローカル変数名のタ  |
|                   |                     | プル                        |
+-------------------+---------------------+-----------------------------+
| ジェネレータ      | __name__            | name                        |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | gi_frame            | フレーム                    |
+-------------------+---------------------+-----------------------------+
|                   | gi_running          | ジェネレータが実行中かどう  |
|                   |                     | か                          |
+-------------------+---------------------+-----------------------------+
|                   | gi_code             | コード                      |
+-------------------+---------------------+-----------------------------+
|                   | gi_yieldfrom        | "yield from" でイテレートさ |
|                   |                     | れているオブジェクト、また  |
|                   |                     | は "None"                   |
+-------------------+---------------------+-----------------------------+
| 非同期ジェネレー  | __name__            | name                        |
| タ                |                     |                             |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | ag_await            | 待機されているオブジェクト  |
|                   |                     | 、または "None"             |
+-------------------+---------------------+-----------------------------+
|                   | ag_frame            | フレーム                    |
+-------------------+---------------------+-----------------------------+
|                   | ag_running          | ジェネレータが実行中かどう  |
|                   |                     | か                          |
+-------------------+---------------------+-----------------------------+
|                   | ag_code             | コード                      |
+-------------------+---------------------+-----------------------------+
| コルーチン        | __name__            | name                        |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | cr_await            | 待機されているオブジェクト  |
|                   |                     | 、または "None"             |
+-------------------+---------------------+-----------------------------+
|                   | cr_frame            | フレーム                    |
+-------------------+---------------------+-----------------------------+
|                   | cr_running          | コルーチンが実行中かどうか  |
+-------------------+---------------------+-----------------------------+
|                   | cr_code             | コード                      |
+-------------------+---------------------+-----------------------------+
|                   | cr_origin           | "None" またはコルーチンが生 |
|                   |                     | 成された場所。 "sys.set_co  |
|                   |                     | routine_origin_tracking_de  |
|                   |                     | pth()" を参照。             |
+-------------------+---------------------+-----------------------------+
| 組み込み          | __doc__             | ドキュメント文字列          |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | 関数、メソッドの元々の名前  |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | __self__            | メソッドが結合しているイン  |
|                   |                     | スタンス、または "None"     |
+-------------------+---------------------+-----------------------------+

バージョン 3.5 で変更: ジェネレータに "__qualname__" と "gi_yieldfrom"
属性が追加されました。ジェネレータの "__name__" 属性がコード名ではなく
関数名から設定されるようになり、変更できるようになりました。

バージョン 3.7 で変更: コルーチンに "cr_origin" 属性を追加しました。

バージョン 3.10 で変更: 関数に "__builtins__" 属性を追加しました。

inspect.getmembers(object[, predicate])

   オブジェクトの全てのメンバーを "(name, value)" ペアのリストで返しま
   す。リストは名前 (name) でソートされます。オプション引数
   *predicate* が指定された場合、各メンバーの "value" オブジェクトを引
   数として *predicate* が呼ばれ、その戻り値が真となるとなるメンバーだ
   けがリストに含まれます。

   注釈:

     引数がクラスでその属性がメタクラスで特別に定義された "__dir__()"
     に列挙されている場合、"getmembers()" はメタクラスで定義されたクラ
     ス属性のみを返します。

inspect.getmembers_static(object[, predicate])

   オブジェクトの全てのメンバーを "(name, value)" ペアのリストで返しま
   す。ただし、デスクリプタプロトコルの __getattr__ や
   __getattribute__ を介した動的なルックアップは行いません。オプション
   として、引数に与えられた predicate を満たすメンバーのみを返すことも
   できます。

   注釈:

     "getmembers_static()" は getmembers が取得できるメンバーの全てを
     取り出すことはできないかもしれません (たとえば動的に生成された属
     性など)が、逆に getmembers が見つけることのできなかったメンバーを
     取得できることもあります (AttributeError を送出するデスクリプタな
     ど)。また、時にはインスタンスメンバーの代わりにデスクリプタオブジ
     ェクトを返すこともあります。

   Added in version 3.11.

inspect.getmodulename(path)

   ファイル *path* で指定されたモジュールの名前を、そのモジュールを含
   むパッケージの名前を含まない形で返します。ファイル拡張子は、
   "importlib.machinery.all_suffixes()" の全てのエントリに対して一致す
   るかどうかをチェックされます。拡張子が一致した場合、最後のパス成分
   から拡張子を除いたものを返します。それ以外の場合は "None" を返しま
   す。

   この関数は、実際の Python モジュールとして意味のある名前 *だけ* を
   返します。すなわち、 Python パッケージを指している可能性のあるパス
   に対しては、依然として "None" を返します。

   バージョン 3.3 で変更: この関数は直接 "importlib" に依存するように
   なりました。

inspect.ismodule(object)

   オブジェクトがモジュールの場合 "True" を返します。

inspect.isclass(object)

   オブジェクトが組み込みか Python が生成したクラスの場合に "True" を
   返します。

inspect.ismethod(object)

   オブジェクトがメソッドの場合 "True" を返します。

inspect.isfunction(object)

   オブジェクトが、 *lambda* 式で生成されたものを含む Python 関数の場
   合に "True" を返します。

inspect.isgeneratorfunction(object)

   オブジェクトが Python のジェネレータ関数の場合 "True" を返します。

   バージョン 3.8 で変更: "functools.partial()" でラップした関数に対し
   て、ラップされた関数が Python のジェネレータ関数である場合は "True"
   を返すようになりました。

   バージョン 3.13 で変更: "functools.partialmethod()" でラップした関
   数に対して、ラップされた関数が Python のジェネレータ関数である場合
   は "True" を返すようになりました。

inspect.isgenerator(object)

   オブジェクトがジェネレータの場合 "True" を返します。

inspect.iscoroutinefunction(object)

   オブジェクトがコルーチン関数 *coroutine function* ("async def" 構文
   で定義された関数)、コルーチン関数 *coroutine function* をラップして
   いる "functools.partial()" もしくは "markcoroutinefunction()" とマ
   ークされた同期関数のいずれかの場合に "True" を返します

   Added in version 3.5.

   バージョン 3.8 で変更: "functools.partial()" でラップした関数に対し
   て、ラップされた関数が コルーチン関数 *coroutine function* である場
   合は "True" を返すようになりました。

   バージョン 3.12 で変更: "markcoroutinefunction()" とマークされた同
   期関数に対して "True" を返すようになりました。

   バージョン 3.13 で変更: "functools.partialmethod()" でラップした関
   数に対して、ラップされた関数がコルーチン関数 *coroutine function*
   である場合は "True" を返すようになりました。

inspect.markcoroutinefunction(func)

   そのままであれば "iscoroutinefunction()" がコルーチン関数と判定しな
   いような呼び出し可能オブジェクトを、コルーチン関数 *coroutine
   function* とマークするためのデコレータです。

   これは、コルーチン *coroutine* を返す同期関数が、
   "iscoroutinefunction()" が真であることを要求するAPIに渡される場合に
   役に立つかもしれません。

   可能なら、 "async def" を使った関数定義が好ましいです。また、関数を
   呼び出した上でその戻り値を "iscoroutine()" でテストする方法も容認で
   きます。

   Added in version 3.12.

inspect.iscoroutine(object)

   オブジェクトが "async def" で生成された *コルーチン* の場合 "True"
   を返します。

   Added in version 3.5.

inspect.isawaitable(object)

   オブジェクトを "await" 式内で使用できる場合 "True" を返します。

   ジェネレータベースのコルーチンと通常のジェネレータを区別するのにも
   使えます:

      import types

      def gen():
          yield
      @types.coroutine
      def gen_coro():
          yield

      assert not isawaitable(gen())
      assert isawaitable(gen_coro())

   Added in version 3.5.

inspect.isasyncgenfunction(object)

   オブジェクトが非同期ジェネレータ *asynchronous generator* 関数であ
   る場合に "True" を返します。使用例:

      >>> async def agen():
      ...     yield 1
      ...
      >>> inspect.isasyncgenfunction(agen)
      True

   Added in version 3.6.

   バージョン 3.8 で変更: "functools.partial()" でラップされた関数でも
   、元の関数が非同期ジェネレータ *asynchronous generator* 関数であれ
   ば "True" を返すようになりました。

   バージョン 3.13 で変更: "functools.partialmethod()" でラップした関
   数に対して、ラップされた関数がコルーチン関数 *coroutine function*
   である場合は "True" を返すようになりました。

inspect.isasyncgen(object)

   オブジェクトが *asynchronous generator* 関数によって生成された
   *asynchronous generator iterator* である場合に "True" を返します。

   Added in version 3.6.

inspect.istraceback(object)

   オブジェクトがトレースバックの場合は "True" を返します。

inspect.isframe(object)

   オブジェクトがフレームの場合は "True" を返します。

inspect.iscode(object)

   オブジェクトがコードの場合は "True" を返します。

inspect.isbuiltin(object)

   オブジェクトが組み込み関数か束縛済みの組み込みメソッドの場合に
   "True" を返します。

inspect.ismethodwrapper(object)

   オブジェクトの型が "MethodWrapperType" である場合に "True" を返しま
   す。

   真を返すのは "MethodWrapperType" のインスタンスで、 "__str__()",
   "__eq__()",  "__repr__()" などです。

   Added in version 3.11.

inspect.isroutine(object)

   オブジェクトがユーザ定義か組み込みの関数またはメソッドの場合は
   "True" を返します。

inspect.isabstract(object)

   オブジェクトが抽象基底クラスであるときに "True" を返します。

inspect.ismethoddescriptor(object)

   オブジェクトがメソッドデスクリプタであり、 "ismethod()",
   "isclass()", "isfunction()", "isbuiltin()" でない場合に "True" を返
   します。

   これはたとえば、 "int.__add__" で真を返します。この関数によるテスト
   をパスする（真を返す）オブジェクトは "__get__()" メソッドを持ちます
   が、 "__set__()" メソッドや "__delete__()" メソッドは持ちません。そ
   れ以外の属性の有無はさまざまです。 "__name__" 属性は普通は存在しま
   すし、 "__doc__" 属性もしばしば見られます。

   デスクリプタによって実装されたメソッドがこのメソッド以外のテストを
   パスする場合、 "ismethoddescriptor()" によるテストでは "False" を返
   します。これは単純に、他のテストはより多くを約束するからです -- た
   とえば、あるオブジェクトが "ismethod()" のテストをパスするとき、そ
   のオブジェクトが "__func__" 属性 (など) を持っていることを期待する
   ことができます。

   バージョン 3.13 で変更: この関数は、 "__get__()" 属性と
   "__delete__()" 属性を持ち、 "__set__()" 属性を持たないオブジェクト
   をメソッドデスクリプタであると不正に報告することはなくなりました (
   そのようなオブジェクトはデータデスクリプタであって、メソッドデスク
   リプタではありません)。

inspect.isdatadescriptor(object)

   オブジェクトがデータデスクリプタの場合に "True" を返します。

   データデスクリプタは "__set__" メソッドか "__delete__" メソッドのい
   ずれかを持ちます。例としては、 (Python で定義された) プロパティ、
   getset デスクリプタ、メンバーデスクリプタがあります。後者2つは C で
   定義されており、それぞれの型に対して特別なテストが存在します。それ
   らのテストは、全ての Python 実装に対して堅牢です。概して、データデ
   スクリプタは "__name__" 属性や "__doc__" 属性も持ちますが、このこと
   は保証されてはいません (一方でプロパティ、 getset デスクリプタ、メ
   ンバーデスクリプタはこれら2つの属性を両方持っています)。

inspect.isgetsetdescriptor(object)

   オブジェクトが getset デスクリプタの場合に "True" を返します。

   getset とは、拡張モジュールで "PyGetSetDef" 構造体を用いて定義され
   た属性のことです。そのような型を持たない Python 実装の場合は、この
   メソッドは常に "False" を返します。

inspect.ismemberdescriptor(object)

   オブジェクトがメンバーデスクリプタの場合に "True" を返します。

   メンバーデスクリプタとは、拡張モジュールで "PyMemberDef" 構造体を用
   いて定義された属性のことです。そのような型を持たない Python 実装の
   場合は、このメソッドは常に "False" を返します。


ソースコードの情報取得
======================

inspect.getdoc(object)

   オブジェクトのドキュメンテーション文字列を、 "cleandoc()" で整理し
   た上で取得します。オブジェクトに対するドキュメンテーション文字列が
   与えられていない場合で、かつオブジェクトがクラス、メソッド、プロパ
   ティ、デスクリプタのいずれかである場合、継承の階層構造からドキュメ
   ンテーション文字列を探し出して返します。ドキュメンテーション文字列
   がないか、または不正な場合は "None" を返します。

   バージョン 3.5 で変更: ドキュメンテーション文字列がオーバーライドさ
   れていない場合は継承されるようになりました。

inspect.getcomments(object)

   オブジェクトのソースコード直前 (クラス、関数、メソッドの場合) また
   は Python ソースファイルの先頭 (モジュールの場合) の任意の行数にわ
   たるコメントを、ひとつの文字列として返します。オブジェクトのソース
   コードが存在しない場合は "None" を返します。オブジェクトが C で定義
   されている場合や、対話型シェルで定義したオブジェクトの場合にこのよ
   うなことが起こり得ます。

inspect.getfile(object)

   オブジェクトを定義している (テキストまたはバイナリの) ファイルの名
   前を返します。オブジェクトが組み込みモジュール、クラス、関数の場合
   は "TypeError" 例外が発生します。

inspect.getmodule(object)

   オブジェクトが定義されているモジュールの推定を試みます。モジュール
   が決められない場合は "None" を返します。

inspect.getsourcefile(object)

   オブジェクトが定義されている Python ソースファイルの名前を返します
   。ソースを取得する方法がない場合は "None" を返します。組み込みのモ
   ジュール、クラス、関数に対しては "TypeError" で失敗します。

inspect.getsourcelines(object)

   オブジェクトを定義しているソースコードの行のリストと、定義の開始行
   番号を返します。引数にはモジュール、クラス、メソッド、関数、トレー
   スバック、またはコードオブジェクトを渡すことができます。オブジェク
   トに対応するソースコードが行のリストとして返されます。また行番号は
   、元のソースファイル中でコードが見つかった最初の行を示します。ソー
   スコードを探し出すことができなかった場合、 "OSError" 例外が送出され
   ます。オブジェクトが組み込みのモジュール、クラス、または関数である
   場合は "TypeError" 例外が送出されます。

   バージョン 3.3 で変更: "IOError" の代わりに "OSError" を送出します
   。前者は後者のエイリアスです。

inspect.getsource(object)

   オブジェクトを定義しているソースコードのテキストを返します。引数に
   はモジュール、クラス、メソッド、関数、トレースバック、フレーム、ま
   たはコードオブジェクトを渡すことができます。ソースコードはひとつの
   文字列として返されます。ソースコードを探し出すことができなかった場
   合、 "OSError" 例外が送出されます。オブジェクトが組み込みのモジュー
   ル、クラス、または関数である場合は "TypeError" 例外が送出されます。

   バージョン 3.3 で変更: "IOError" の代わりに "OSError" を送出します
   。前者は後者のエイリアスです。

inspect.cleandoc(doc)

   コードブロックと位置を合わせるためのインデントを docstring から削除
   します。

   先頭行の行頭の空白文字は全て削除されます。 2行目以降では全行で同じ
   数の行頭の空白文字が、削除できるだけ削除されます。 その後、先頭と末
   尾の空白行が削除され、全てのタブが空白に展開されます。


Signature オブジェクトで呼び出し可能オブジェクトを内省する
==========================================================

Added in version 3.3.

"Signature" オブジェクトは、呼び出し可能オブジェクトの呼び出しシグネチ
ャと戻り値のアノテーションを表現します。 "Signature" オブジェクトを取
得するには、 "signature()" 関数を使ってください。

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

   *callable* で与えられたオブジェクトに対する "Signature" オブジェク
   トを返します:

      >>> from inspect import signature
      >>> def foo(a, *, b:int, **kwargs):
      ...     pass

      >>> sig = signature(foo)

      >>> str(sig)
      '(a, *, b: int, **kwargs)'

      >>> str(sig.parameters['b'])
      'b: int'

      >>> sig.parameters['b'].annotation
      <class 'int'>

   単純な関数やクラスから、 "functools.partial()" オブジェクトまで、幅
   広い Python の呼び出し可能なオブジェクトを受け付けます。

   For objects defined in modules using stringized annotations ("from
   __future__ import annotations"), "signature()" will attempt to
   automatically un-stringize the annotations using
   "get_annotations()".  The *globals*, *locals*, and *eval_str*
   parameters are passed into "get_annotations()" when resolving the
   annotations; see the documentation for "get_annotations()" for
   instructions on how to use these parameters.

   Raises "ValueError" if no signature can be provided, and
   "TypeError" if that type of object is not supported.  Also, if the
   annotations are stringized, and *eval_str* is not false, the
   "eval()" call(s) to un-stringize the annotations in
   "get_annotations()" could potentially raise any kind of exception.

   A slash(/) in the signature of a function denotes that the
   parameters prior to it are positional-only. For more info, see the
   FAQ entry on positional-only parameters.

   バージョン 3.5 で変更: *follow_wrapped* パラメータが追加されました
   。parameter was added. 特に *callable* そのものについてのシグネチャ
   を取得するためには "False" を指定してください (そうすることで、デコ
   レータで修飾された呼び出し可能オブジェクトに対して
   ``callable.__wrapped__`` が使われなくなります)。

   バージョン 3.10 で変更: *globals*, *locals*, および *eval_str* パラ
   メータが追加されました。

   注釈:

     いくつかの呼び出し可能オブジェクトは、ある Python 実装の下ではイ
     ントロスペクション (実行時オブジェクト調査) ができないかもしれま
     せん。たとえば CPython では、 C で定義されたいくつかの組み込み関
     数はそれらの引数に関するメタデータを提供しません。

   渡されたオブジェクトが "__signature__" 属性を持つ場合、それにもとづ
   いてシグネチャを作ることができるかもしれません。厳密なセマンティク
   スは実装レベルの詳細であり、予告なく変更される可能性があります。現
   在のセマンティクスについてはソースコードをを参照してください。

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

   "Signature" オブジェクトは、関数の呼び出しシグネチャと戻り値のアノ
   テーションを表現します。このオブジェクトは "parameters" 集合として
   、関数が受け取るパラメータそれぞれについての "Parameter" オブジェク
   トを保存します。

   オプション引数 *parameters* は "Parameter" オブジェクトのシーケンス
   で、重複した名前のパラメータはないか、パラメータの並び順は正しいか
   、すなわち位置専用引数からはじまり次に位置引数としてもキーワード引
   数としても指定可能なパラメータが続くかどうか、またデフォルト値のあ
   るパラメータがデフォルト値のないパラメータの後にあるかどうか、とい
   った項目をチェックするための検証が行われます。

   オプション引数 *return_annotation* は任意の Python オブジェクトをと
   ることができます。この引数は、呼び出し可能オブジェクトの "戻り値"
   に対するアノテーションを表します。

   "Signature" オブジェクトは *immutable* すなわち変更不可能です。変更
   されたコピーを生成するためには、 "Signature.replace()" または
   "copy.replace()" を使ってください。

   バージョン 3.5 で変更: "Signature" オブジェクトは pickle 可能かつ *
   ハッシュ可能* になりました。

   empty

      return アノテーションがないことを指すクラスレベルの特殊マーカで
      す。

   parameters

      パラメータの名前と対応する "Parameter" オブジェクトの、順序あり
      マッピングです。パラメータは、キーワード専用パラメータも含めて、
      厳密な定義順に現れます。

      バージョン 3.7 で変更: バージョン 3.7 までは、Python はキーワー
      ド専用パラメータだけしか順序を保つことを明確に保証していませんで
      した。とはいえ Python 3 では事実上パラメータの順序は維持されてい
      ました。

   return_annotation

      呼び出し可能オブジェクトの "return" アノテーションです。呼び出し
      可能オブジェクトに "return" アノテーションがない場合、この属性は
      "Signature.empty" に設定されます。

   bind(*args, **kwargs)

      位置引数およびキーワード引数からパラメータへのマッピングを生成し
      ます。 "*args" と "**kwargs" がシグネチャに一致した場合
      "BoundArguments" を返します。引数がシグネチャと一致しない場合は
      "TypeError" 例外を送出します。

   bind_partial(*args, **kwargs)

      "Signature.bind()" と同様に動作しますが、いくつかの必要な引数を
      省略することができます ("functools.partial()" の振る舞いによく似
      たものです) 。 "BoundArguments" を返します。引数がシグネチャと一
      致しない場合は "TypeError" 例外を送出します。

   replace(*[, parameters][, return_annotation])

      "replace()" メソッドが呼び出されたインスタンスから、新しい
      "Signature" インスタンスを生成します。元になるシグネチャのプロパ
      ティをオーバーライドするために異なる *parameters* や
      *return_annotation* を渡すことが可能です。 "return_annotation"
      をコピーされた "Signature" インスタンスから削除したい場合、
      "Signature.empty" を渡してください。

         >>> def test(a, b):
         ...     pass
         ...
         >>> sig = signature(test)
         >>> new_sig = sig.replace(return_annotation="new return anno")
         >>> str(new_sig)
         "(a, b) -> 'new return anno'"

      "Signature" オブジェクトのコピーは、汎用の関数 "copy.replace()"
      でもサポートされています。

   format(*, max_width=None)

      "Signature" オブジェクトの文字列表現を生成します。

      *max_width* が指定されると、メソッドはシグネチャをそれぞれの行が
      最大 *max_width* 文字になるようにフォーマットを試みます。シグネ
      チャが *max_width* よりも長くなってしまう場合は、全てのパラメー
      タごとに改行されます。

      Added in version 3.13.

   classmethod from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

      与えられた呼び出し可能オブジェクト *obj* に対する "Signature" (
      またはそのサブクラスの) オブジェクトを返します。

      このメソッドは "Signature" からサブクラスを作る作業を簡素化しま
      す:

         class MySignature(Signature):
             pass
         sig = MySignature.from_callable(sum)
         assert isinstance(sig, MySignature)

      このメソッドの振る舞いは、上記を除けば "signature()" と同じです
      。

      Added in version 3.5.

      バージョン 3.10 で変更: *globals*, *locals*, および *eval_str*
      パラメータが追加されました。

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

   "Parameter" オブジェクトはイミュータブル (*immutable*) すなわち変更
   不可能です。 "Parameter" オブジェクトを変更する代わりに、
   "Parameter.replace()" や "copy.replace()" を使ってオブジェクトの内
   容を変更したコピーを作成することができます。

   バージョン 3.5 で変更: Parameter オブジェクトはピックル化可能
   (picklable) かつ ハッシュ化可能 (*hashable*) になりました。

   empty

      デフォルト値とアノテーションがないことを指すクラスレベルの特殊マ
      ーカです。

   name

      仮引数名 (文字列) です。名前は有効な Python 識別子でなければなり
      ません。

      CPython は内包表記やジェネレータ式を実装するためのコードオブジェ
      クトにおいて、 ".0" という形式で暗黙のパラメータ名を生成します。

      バージョン 3.6 で変更: このモジュールにより、これら暗黙のパラメ
      ータ名は "implicit0" のような名前で公開されるようになりました。

   default

      引数のデフォルト値です。引数にデフォルト値がない場合、この属性は
      "Parameter.empty" に設定されます。

   annotation

      引数のアノテーションです。引数にアノテーションがない場合、この属
      性は "Parameter.empty" に設定されます。

   kind

      引数の値がどのようにパラメータと紐付けられるかを記述します。指定
      可能な値は "Parameter" を介して ("Parameter.KEYWORD_ONLY" のよう
      に) アクセス可能で、以下に示す順番で比較や順序付けをサポートして
      います:

      +--------------------------+------------------------------------------------+
      | 名前                     | 意味                                           |
      |==========================|================================================|
      | *POSITIONAL_ONLY*        | 値は位置引数として渡されなければなりません。   |
      |                          | Python の関数定義に おいて、位置専用引数は (も |
      |                          | し存在すれば) "/" エントリの前に現れる ものを  |
      |                          | 指します。                                     |
      +--------------------------+------------------------------------------------+
      | *POSITIONAL_OR_KEYWORD*  | 値をキーワードまたは位置引数として渡すことがで |
      |                          | きます (これは Python で実装された関数の標準的 |
      |                          | な束縛動作です)。                              |
      +--------------------------+------------------------------------------------+
      | *VAR_POSITIONAL*         | その他の仮引数に束縛されていない位置引数のタプ |
      |                          | ルです。Python の 関数定義における "*args" 仮  |
      |                          | 引数に対応します。                             |
      +--------------------------+------------------------------------------------+
      | *KEYWORD_ONLY*           | 値をキーワード引数として渡さなければなりません |
      |                          | 。キーワード専用引 数は Python の関数定義にお  |
      |                          | いて "*" や "*args" の後に現れる引数で す。    |
      +--------------------------+------------------------------------------------+
      | *VAR_KEYWORD*            | その他の仮引数に束縛されていないキーワード引数 |
      |                          | の辞書です。Python の関数定義における          |
      |                          | "**kwargs" 仮引数に対応します。                |
      +--------------------------+------------------------------------------------+

      例: デフォルト値を持たないキーワード専用引数を全て出力します:

         >>> def foo(a, b, *, c, d=10):
         ...     pass

         >>> sig = signature(foo)
         >>> for param in sig.parameters.values():
         ...     if (param.kind == param.KEYWORD_ONLY and
         ...                        param.default is param.empty):
         ...         print('Parameter:', param)
         Parameter: c

   kind.description

      "Parameter.kind" 列挙型の各定数を説明します。

      Added in version 3.8.

      例: 全ての引数に対する説明を出力します:

         >>> def foo(a, b, *, c, d=10):
         ...     pass

         >>> sig = signature(foo)
         >>> for param in sig.parameters.values():
         ...     print(param.kind.description)
         positional or keyword
         positional or keyword
         keyword-only
         keyword-only

   replace(*[, name][, kind][, default][, annotation])

      このメソッドの呼び出し元のインスタンスをもとにして、新たな
      "Parameter" インスタンスを生成します。 "Parameter" の属性をオー
      バーライドするには、対応する引数をこのメソッドに渡してください。
      "Parameter" からデフォルト値やアノテーションを取り除きたい場合は
      、 "Parameter.empty" を渡してください。

         >>> from inspect import Parameter
         >>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
         >>> str(param)
         'foo=42'

         >>> str(param.replace()) # Will create a shallow copy of 'param'
         'foo=42'

         >>> str(param.replace(default=Parameter.empty, annotation='spam'))
         "foo: 'spam'"

      "Parameter" オブジェクトは汎用関数 "copy.replace()" でもサポート
      されています。

   バージョン 3.4 で変更: Python 3.3 では、"kind" が "POSITIONAL_ONLY"
   の場合に限り、 "name" が "None" であるような "Parameter" オブジェク
   トが許されていました。ですが、そのようなオブジェクトはもはや許可さ
   れていません。

class inspect.BoundArguments

   "Signature.bind()" または "Signature.bind_partial()" を呼び出して得
   られる結果です。引数と関数のパラメータとの間のマッピング情報を保持
   します。

   arguments

      パラメータの名前と引数の値との間のミュータブルなマッピングです。
      明示的に紐付けされた引数だけを含みます。 "arguments" に対する変
      更は "args" と "kwargs" に反映されます。

      いかなる引数処理の目的でも、 "Signature.parameters" とあわせて使
      うようにしてください。

      注釈:

        "Signature.bind()" または "Signature.bind_partial()" でデフォ
        ルト値をあてにするとされた引数は、スキップされます。それらをマ
        ッピングに加えたい場合は、必要に応じて
        "BoundArguments.apply_defaults()" を使ってください。

      バージョン 3.9 で変更: "arguments" の型が "dict" になりました。
      以前は "collections.OrderedDict" 型でした。

   args

      位置引数の値のタプルです。"arguments" 属性から動的に計算されます
      。

   kwargs

      キーワード引数の値の辞書です。 "arguments" 属性から動的に計算さ
      れます。位置引数として渡すことができる引数は、 "args" に含まれる
      ことに注意してください。

   signature

      親の "Signature" オブジェクトへの参照です。

   apply_defaults()

      存在しない引数のデフォルト値を設定します。

      可変長位置引数 ("*args") に対するデフォルト値は、空のタプルです
      。

      可変長キーワード引数 ("**kwargs") に対するデフォルト値は、空の辞
      書です。

         >>> def foo(a, b='ham', *args): pass
         >>> ba = inspect.signature(foo).bind('spam')
         >>> ba.apply_defaults()
         >>> ba.arguments
         {'a': 'spam', 'b': 'ham', 'args': ()}

      Added in version 3.5.

   "args" と "kwargs" の2つのプロパティは、関数の呼び出しに使うことが
   できます:

      def test(a, *, b):
          ...

      sig = signature(test)
      ba = sig.bind(10, b=20)
      test(*ba.args, **ba.kwargs)

参考:

  **PEP 362**: - 関数シグニチャオブジェクト
     仕様の詳細、実装の詳細および使用例を示しています。


クラスと関数
============

inspect.getclasstree(classes, unique=False)

   リストで指定したクラスの継承関係から、ネストしたリストを作成します
   。ネストしたリストには、直前の要素から派生したクラスが格納されます
   。各要素は長さ2のタプルで、クラスと基底クラスのタプルを格納していま
   す。*unique* が真の場合、各クラスは戻り値のリスト内に一つだけしか格
   納されません。真でなければ、多重継承を利用したクラスとその派生クラ
   スは複数回格納される場合があります。

inspect.getfullargspec(func)

   Python 関数のパラメータの名前とデフォルト値を取得します。 *named
   tuple* を返します:

   "FullArgSpec(args, varargs, varkw, defaults, kwonlyargs,
   kwonlydefaults, annotations)"

   *args* は位置引数の名前のリストです。 *varargs* は "*" で始まる可変
   長位置引数の名前で、この引数を受け付けない場合は "None" です。
   *varkw* は "**" で始まる可変長キーワード引数の名前で、この引数を受
   け付けない場合は "None" です。 *defaults* は末尾 *n* 個の位置引数に
   対応するデフォルト引数の *n*-タプルで、 そのようなデフォルト値が定
   義されていない場合は "None" です。 *kwonlyargs* は宣言順に並んだキ
   ーワード専用引数の名前のリストです。 *kwonlydefaults* はそれらに対
   して値が渡されなかった場合の、 *kwonlyargs* の名前からデフォルト値
   へのマッピングを行う辞書です。 *annotations* 引数名からアノテーショ
   ンへのマッピングを行う辞書です。特殊キー ""return"" は (もしあれば)
   関数の戻り値に対するアノテーションを伝えるために使われます。

   "signature()" と Signature オブジェクト が呼び出し可能オブジェクト
   のイントロスペクション (実行時オブジェクト調査) のための推奨される
   API を提供しており、かつ拡張モジュール API でときどき遭遇する追加の
   振る舞い (位置専用引数など) もサポートしていることに注意してくださ
   い。この関数は、主に Python 2 の "inspect" モジュール API との互換
   性を維持することが必要なコードで利用されるために残されています。

   バージョン 3.4 で変更: この関数は "signature()" をもとに実装されて
   います。ただし、 "__wrapped__" 属性を無視します。また、束縛されたメ
   ソッドに対するシグネチャの出力において、すでに束縛された最初のパラ
   メータを含みます。

   バージョン 3.6 で変更: Python 3.5 ではこのメソッドは非推奨とされ、
   代わりに "signature()" の利用が推奨されていました。ですが、レガシー
   API である "getargspec()" から移行し、明確にサポートされた標準イン
   ターフェースによる単一ソースでの Python 2/3 互換コードを復活させる
   ため、非推奨の決定は取り消されました。

   バージョン 3.7 で変更: バージョン 3.7 までは、Python はキーワード専
   用パラメータだけしか順序を保つことを明確に保証していませんでした。
   とはいえ Python 3 では事実上パラメータの順序は維持されていました。

inspect.getargvalues(frame)

   指定したフレームに渡された引数の情報を取得します。戻り値は *名前付
   きタプル* "ArgInfo(args, varargs, keywords, locals)" です。*args*
   は引数名のリストです。 *varargs* と *keywords* は "*" 引数と "**"
   引数の名前で、引数がなければ "None" となります。 *locals* は指定し
   たフレームのローカル変数の辞書です。

   注釈:

     この関数は Python 3.5 において、不注意により非推奨とされていまし
     た。

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

   "getargvalues()" で取得した4つの値を読みやすく整形します。 format*
   引数はオプションで、名前と値を文字列に変換する整形関数を指定するこ
   とができます。

   注釈:

     この関数は Python 3.5 において、不注意により非推奨とされていまし
     た。

inspect.getmro(cls)

   *cls* クラスの基底クラス (*cls* 自身も含む) を、メソッドの優先順位
   順に並べたタプルを返します。結果のリスト内で各クラスは一度だけ格納
   されます。メソッドの優先順位はクラスの型によって異なります。非常に
   特殊なユーザ定義のメタクラスを使用していない限り、*cls* が戻り値の
   先頭要素となります。

inspect.getcallargs(func, /, *args, **kwds)

   *args* と *kwds* を、あたかもそれらをパラメータとして呼ばれたかのよ
   うに、 Python 関数またはメソッド *func* に束縛します。また、第一引
   数 (通常 "self" という名前です) を関連するインスタンスに束縛します
   。引数名 (もし存在すれば "*" や "**" で始まる引数も含む) を *args*
   および *kwds* で与えられた値にマッピングする辞書を返します。 *func*
   を不正に呼び出した場合、すなわち "func(*args, **kwds)" の呼び出しが
   不完全なシグネチャにより例外を送出するような場合は、同じ型の例外を
   同一またはよく似たメッセージとともに送出します。以下は使用例です:

      >>> from inspect import getcallargs
      >>> def f(a, b=1, *pos, **named):
      ...     pass
      ...
      >>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
      True
      >>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
      True
      >>> getcallargs(f)
      Traceback (most recent call last):
      ...
      TypeError: f() missing 1 required positional argument: 'a'

   Added in version 3.2.

   バージョン 3.5 で非推奨: 代わりに "Signature.bind()" や
   "Signature.bind_partial()" を使ってください。

inspect.getclosurevars(func)

   Python 関数またはメソッド *func* の外部の名前参照と、それらの現在の
   値のマッピングを取得します。 *named tuple* "ClosureVars(nonlocals,
   globals, builtins, unbound)" を返します。参照名を、 *nonlocals* は
   レキシカルクロージャ変数、すなわち外側のスコープで定義された変数の
   値にマップし、 *globals* は関数が属するモジュールのグローバル変数に
   マップし、 *builtins* は関数本体から見える組み込み変数にマップしま
   す。 *unbound* は、現在のモジュールにおけるグローバル変数や組み込み
   変数において解決できないにもかかわらず、関数内で参照されている名前
   の集合です。

   *func* が Python の関数やメソッドでない場合 "TypeError" が送出され
   ます。

   Added in version 3.3.

inspect.unwrap(func, *, stop=None)

   *func* によりラップされたオブジェクトを取得します。 "__wrapped__"
   属性の連鎖をたどり、ラップの連鎖の最後にあるオブジェクトを返します
   。

   *stop* はオプションで指定可能なコールバック関数で、ラッパーの連鎖に
   おけるオブジェクトをただひとつの引数として取ります。このコールバッ
   ク関数が真値を返した段階で、オブジェクトのアンラップを早期に終了さ
   せることができます。コールバック関数が真値を返さない場合は、通常通
   りラッパーの連鎖における最後のオブジェクトを返します。例えば、
   "signature()" は、オブジェクトに "__signature__" 属性が定義されてい
   たらオブジェクトのアンラップを停止するために、このオプションを使っ
   ています。

   循環を検知した場合は "ValueError" を送出します。

   Added in version 3.4.

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False)

   オブジェクトに対するアノテーション辞書を計算します。

   "obj" may be a callable, class, or module. Passing in an object of
   any other type raises "TypeError".

   Returns a dict.  "get_annotations()" returns a new dict every time
   it's called; calling it twice on the same object will return two
   different but equivalent dicts.

   This function handles several details for you:

   * If "eval_str" is true, values of type "str" will be un-stringized
     using "eval()".  This is intended for use with stringized
     annotations ("from __future__ import annotations").

   * If "obj" doesn't have an annotations dict, returns an empty dict.
     (Functions and methods always have an annotations dict; classes,
     modules, and other types of callables may not.)

   * Ignores inherited annotations on classes.  If a class doesn't
     have its own annotations dict, returns an empty dict.

   * All accesses to object members and dict values are done using
     "getattr()" and "dict.get()" for safety.

   * Always, always, always returns a freshly created dict.

   "eval_str" controls whether or not values of type "str" are
   replaced with the result of calling "eval()" on those values:

   * If eval_str is true, "eval()" is called on values of type "str".
     (Note that "get_annotations" doesn't catch exceptions; if
     "eval()" raises an exception, it will unwind the stack past the
     "get_annotations" call.)

   * If eval_str is false (the default), values of type "str" are
     unchanged.

   "globals" and "locals" are passed in to "eval()"; see the
   documentation for "eval()" for more information.  If "globals" or
   "locals" is "None", this function may replace that value with a
   context-specific default, contingent on "type(obj)":

   * If "obj" is a module, "globals" defaults to "obj.__dict__".

   * If "obj" is a class, "globals" defaults to
     "sys.modules[obj.__module__].__dict__" and "locals" defaults to
     the "obj" class namespace.

   * If "obj" is a callable, "globals" defaults to "obj.__globals__",
     although if "obj" is a wrapped function (using
     "functools.update_wrapper()") it is first unwrapped.

   Calling "get_annotations" is best practice for accessing the
   annotations dict of any object.  See Annotations Best Practices for
   more information on annotations best practices.

   Added in version 3.10.


インタープリタスタック
======================

以下の関数のうちいくつかは "FrameInfo" オブジェクトを返します。これら
のオブジェクトは、後方互換性のために "positions" を除く全ての属性に対
して、タプル的な演算を許可します。この振る舞いは非推奨と考えられており
、将来削除されるかもしれません。

class inspect.FrameInfo

   frame

      そのレコードに相当する フレームオブジェクト です。

   filename

      このレコードに相当するフレームによって実行されるコードのファイル
      名です。

   lineno

      このレコードに相当するフレームによって実行されるコードの、現在の
      行の行番号です。

   function

      このレコードに相当するフレームによって実行される関数名です。

   code_context

      このレコードに相当するフレームによって実行される、ソースコードか
      ら生成されたコンテキストの行のリストです。

   index

      "code_context" リストにおいて実行される現在の行のインデックスで
      す。

   positions

      このレコードに相当するフレームによって実行される命令に結びついた
      "dis.Positions" オブジェクトで、開始行番号、終了行番号、開始カラ
      ムオフセット、終了カラムオフセットを含んでいます。

   バージョン 3.5 で変更: "tuple" ではなく *named tuple* を返すように
   なりました。

   バージョン 3.11 で変更: "FrameInfo" はクラスインスタンスになりまし
   た (ただしそれ以前の *named tuple* とは後方互換です) 。

class inspect.Traceback

   filename

      このトレースバックに対応するフレームによって実行されるコードのフ
      ァイル名です。

   lineno

      このトレースバックに対応するフレームによって実行されるコードの、
      現在の行の行番号です。

   function

      このトレースバックに対応するフレームによって実行される関数名です
      。

   code_context

      このトレースバックに対応するフレームによって実行される、ソースコ
      ードから生成されたコンテキストの行のリストです。

   index

      "code_context" リストにおいて実行される現在の行のインデックスで
      す。

   positions

      このトレースバックに対応するフレームによって実行される命令の開始
      行番号、終了行番号、開始カラムオフセット、終了カラムオフセットを
      含む "dis.Positions" オブジェクトです。

   バージョン 3.11 で変更: "Traceback" はクラスインスタンスになりまし
   た (ただしそれ以前の *named tuple* とは後方互換です) 。

注釈:

  フレームレコードの最初の要素などのフレームオブジェクトへの参照を保存
  すると、循環参照になってしまう場合があります。循環参照ができると、
  Python の循環参照検出機能を有効にしていたとしても関連するオブジェク
  トが参照しているすべてのオブジェクトが解放されにくくなり、明示的に参
  照を削除しないとメモリ消費量が増大する恐れがあります。参照の削除を
  Python の循環参照検出機能にまかせることもできますが、 "finally" 節で
  循環参照を解除すれば確実にフレーム (とそのローカル変数) は削除されま
  す。また、循環参照検出機能は Python のコンパイルオプションや
  "gc.disable()" で無効とされている場合がありますので注意が必要です。
  例:

     def handle_stackframe_without_leak():
         frame = inspect.currentframe()
         try:
             # フレーム上で何か処理をします
         finally:
             del frame

  (たとえばトレースバックをあとで表示したいなどの理由で) フレームを削
  除せずにとっておきたい場合は、 "frame.clear()" メソッドを使って循環
  参照を壊すこともできます。

以下の関数でオプション引数 *context* には、戻り値のソース行リストに何
行分のソースを含めるかを指定します。ソース行リストには、実行中の行を中
心として指定された行数分のリストを返します。

inspect.getframeinfo(frame, context=1)

   フレームまたはトレースバックオブジェクトの情報を取得します。
   "Traceback" オブジェクトが返されます。

   バージョン 3.11 で変更: 名前付きタプルの代わりに "Traceback" オブジ
   ェクトが返されるようになりました。

inspect.getouterframes(frame, context=1)

   指定したフレームと、その外側の全フレームの "FrameInfo" オブジェクト
   のリストを取得します。外側のフレームとは *frame* が生成されるまでの
   すべての関数呼び出しを示します。戻り値のリストの先頭は *frame* のフ
   レームレコードで、末尾の要素は *frame* のスタックにある最も外側のフ
   レームのフレームレコードとなります。

   バージョン 3.5 で変更: *名前付きタプル* "FrameInfo(frame, filename,
   lineno, function, code_context, index)" のリストが返されます。

   バージョン 3.11 で変更: "FrameInfo" オブジェクトのリストが返される
   ようになりました。

inspect.getinnerframes(traceback, context=1)

   トレースバックのフレームと、その内側の全フレームの  "FrameInfo" オ
   ブジェクトのリストを取得します。内のフレームとは *frame* から続く一
   連の関数呼び出しを示します。戻り値のリストの先頭は *traceback* のフ
   レームレコードで、末尾の要素は例外が発生した位置を示します。

   バージョン 3.5 で変更: *名前付きタプル* "FrameInfo(frame, filename,
   lineno, function, code_context, index)" のリストが返されます。

   バージョン 3.11 で変更: "FrameInfo" オブジェクトのリストが返される
   ようになりました。

inspect.currentframe()

   呼び出し元のフレームオブジェクトを返します。

   この関数はインタプリタの Python スタックフレームサポートに依存しま
   す。これは Python のすべての実装に存在している保証はありません。
   Python スタックフレームサポートのない環境では、この関数は "None" を
   返します。

inspect.stack(context=1)

   呼び出し元スタックの "FrameInfo" オブジェクトのリストを返します。最
   初の要素は呼び出し元のフレームレコードで、末尾の要素はスタックにあ
   る最も外側のフレームのフレームレコードとなります。

   バージョン 3.5 で変更: *名前付きタプル* "FrameInfo(frame, filename,
   lineno, function, code_context, index)" のリストが返されます。

   バージョン 3.11 で変更: "FrameInfo" オブジェクトのリストが返される
   ようになりました。

inspect.trace(context=1)

   実行中のフレームと処理中の例外が発生したフレームの間の "FrameInfo"
   オブジェクトのリストを返します。最初の要素は呼び出し元のフレームレ
   コードで、末尾の要素は例外が発生した位置を示します。

   バージョン 3.5 で変更: *名前付きタプル* "FrameInfo(frame, filename,
   lineno, function, code_context, index)" のリストが返されます。

   バージョン 3.11 で変更: "FrameInfo" オブジェクトのリストが返される
   ようになりました。


属性の静的なフェッチ
====================

"getattr()" や "hasattr()" は属性の存在確認や属性値の取得に際してコー
ドの実行を伴うことがあります。プロパティなどのデスクリプタが呼び出され
、また "__getattr__()" や "__getattribute__()" が呼び出されたりするか
もしれません。

たとえばドキュメントツールのように受動的なイントロスペクションをしたい
場合、この振る舞いは不便です。 "getattr_static()" は "getattr()" と同
じシグネチャを持ちますが、属性値を取得する際にコードの実行をしないよう
にします。

inspect.getattr_static(obj, attr, default=None)

   Retrieve attributes without triggering dynamic lookup via the
   descriptor protocol, "__getattr__()" or "__getattribute__()".

   Note: this function may not be able to retrieve all attributes that
   getattr can fetch (like dynamically created attributes) and may
   find attributes that getattr can't (like descriptors that raise
   AttributeError). It can also return descriptors objects instead of
   instance members.

   If the instance "__dict__" is shadowed by another member (for
   example a property) then this function will be unable to find
   instance members.

   Added in version 3.2.

"getattr_static()" does not resolve descriptors, for example slot
descriptors or getset descriptors on objects implemented in C. The
descriptor object is returned instead of the underlying attribute.

You can handle these with code like the following. Note that for
arbitrary getset descriptors invoking these may trigger code
execution:

   # example code for resolving the builtin descriptor types
   class _foo:
       __slots__ = ['foo']

   slot_descriptor = type(_foo.foo)
   getset_descriptor = type(type(open(__file__)).name)
   wrapper_descriptor = type(str.__dict__['__add__'])
   descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

   result = getattr_static(some_object, 'foo')
   if type(result) in descriptor_types:
       try:
           result = result.__get__()
       except AttributeError:
           # descriptors can raise AttributeError to
           # indicate there is no underlying value
           # in which case the descriptor itself will
           # have to do
           pass


Current State of Generators, Coroutines, and Asynchronous Generators
====================================================================

When implementing coroutine schedulers and for other advanced uses of
generators, it is useful to determine whether a generator is currently
executing, is waiting to start or resume or execution, or has already
terminated. "getgeneratorstate()" allows the current state of a
generator to be determined easily.

inspect.getgeneratorstate(generator)

   ジェネレータイテレータの現在の状態を取得します。

   取り得る状態は:

   * GEN_CREATED: 実行開始を待機しています。

   * GEN_RUNNING: インタープリタによって現在実行されています。

   * GEN_SUSPENDED: yield 式で現在サスペンドされています。

   * GEN_CLOSED: 実行が完了しました。

   Added in version 3.2.

inspect.getcoroutinestate(coroutine)

   Get current state of a coroutine object.  The function is intended
   to be used with coroutine objects created by "async def" functions,
   but will accept any coroutine-like object that has "cr_running" and
   "cr_frame" attributes.

   取り得る状態は:

   * CORO_CREATED: 実行開始を待機しています。

   * CORO_RUNNING: インタープリタにより現在実行中です。

   * CORO_SUSPENDED: await 式により現在停止中です。

   * CORO_CLOSED: 実行が完了しました。

   Added in version 3.5.

inspect.getasyncgenstate(agen)

   Get current state of an asynchronous generator object.  The
   function is intended to be used with asynchronous iterator objects
   created by "async def" functions which use the "yield" statement,
   but will accept any asynchronous generator-like object that has
   "ag_running" and "ag_frame" attributes.

   取り得る状態は:

   * AGEN_CREATED: Waiting to start execution.

   * AGEN_RUNNING: Currently being executed by the interpreter.

   * AGEN_SUSPENDED: Currently suspended at a yield expression.

   * AGEN_CLOSED: Execution has completed.

   Added in version 3.12.

ジェネレータの現在の内部状態を問い合わせることも出来ます。これは主に内
部状態が期待通り更新されているかどうかを確認するためのテストの目的に有
用です。

inspect.getgeneratorlocals(generator)

   Get the mapping of live local variables in *generator* to their
   current values.  A dictionary is returned that maps from variable
   names to values. This is the equivalent of calling "locals()" in
   the body of the generator, and all the same caveats apply.

   If *generator* is a *generator* with no currently associated frame,
   then an empty dictionary is returned.  "TypeError" is raised if
   *generator* is not a Python generator object.

   **CPython 実装の詳細:** This function relies on the generator
   exposing a Python stack frame for introspection, which isn't
   guaranteed to be the case in all implementations of Python. In such
   cases, this function will always return an empty dictionary.

   Added in version 3.3.

inspect.getcoroutinelocals(coroutine)

   This function is analogous to "getgeneratorlocals()", but works for
   coroutine objects created by "async def" functions.

   Added in version 3.5.

inspect.getasyncgenlocals(agen)

   This function is analogous to "getgeneratorlocals()", but works for
   asynchronous generator objects created by "async def" functions
   which use the "yield" statement.

   Added in version 3.12.


Code Objects Bit Flags
======================

Python code objects have a "co_flags" attribute, which is a bitmap of
the following flags:

inspect.CO_OPTIMIZED

   The code object is optimized, using fast locals.

inspect.CO_NEWLOCALS

   If set, a new dict will be created for the frame's "f_locals" when
   the code object is executed.

inspect.CO_VARARGS

   The code object has a variable positional parameter ("*args"-like).

inspect.CO_VARKEYWORDS

   The code object has a variable keyword parameter ("**kwargs"-like).

inspect.CO_NESTED

   The flag is set when the code object is a nested function.

inspect.CO_GENERATOR

   The flag is set when the code object is a generator function, i.e.
   a generator object is returned when the code object is executed.

inspect.CO_COROUTINE

   The flag is set when the code object is a coroutine function. When
   the code object is executed it returns a coroutine object. See
   **PEP 492** for more details.

   Added in version 3.5.

inspect.CO_ITERABLE_COROUTINE

   The flag is used to transform generators into generator-based
   coroutines.  Generator objects with this flag can be used in
   "await" expression, and can "yield from" coroutine objects. See
   **PEP 492** for more details.

   Added in version 3.5.

inspect.CO_ASYNC_GENERATOR

   The flag is set when the code object is an asynchronous generator
   function.  When the code object is executed it returns an
   asynchronous generator object.  See **PEP 525** for more details.

   Added in version 3.6.

注釈:

  The flags are specific to CPython, and may not be defined in other
  Python implementations.  Furthermore, the flags are an
  implementation detail, and can be removed or deprecated in future
  Python releases. It's recommended to use public APIs from the
  "inspect" module for any introspection needs.


Buffer flags
============

class inspect.BufferFlags

   This is an "enum.IntFlag" that represents the flags that can be
   passed to the "__buffer__()" method of objects implementing the
   buffer protocol.

   The meaning of the flags is explained at バッファリクエストのタイプ
   .

   SIMPLE

   WRITABLE

   FORMAT

   ND

   STRIDES

   C_CONTIGUOUS

   F_CONTIGUOUS

   ANY_CONTIGUOUS

   INDIRECT

   CONTIG

   CONTIG_RO

   STRIDED

   STRIDED_RO

   RECORDS

   RECORDS_RO

   FULL

   FULL_RO

   READ

   WRITE

   Added in version 3.12.


コマンドラインインターフェイス
==============================

The "inspect" module also provides a basic introspection capability
from the command line.

By default, accepts the name of a module and prints the source of that
module. A class or function within the module can be printed instead
by appended a colon and the qualified name of the target object.

--details

   Print information about the specified object rather than the source
   code
