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

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

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

"inspect" モジュールは、モジュール、クラス、メソッド、関数、トレースバ
ック、フレームオブジェクト、コードオブジェクトなど、実行中のオブジェク
トの情報を取得する便利な関数を提供します。 例えば、クラスの内容を調べ
る、メソッドのソースコードを取得する、関数の引数リストを取り出して整形
する、詳細なトレースバックの表示に必要な情報をすべて取得する、といった
用途に役立ちます。

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


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

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

+-------------------+---------------------+-----------------------------+
| 型                | 属性                | 説明                        |
|===================|=====================|=============================|
| クラス            | __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_generator         | このフレームを所有するジェ  |
|                   |                     | ネレータまたはコルーチンオ  |
|                   |                     | ブジェクトを返しま す。 通  |
|                   |                     | 常の関数のフレームなら      |
|                   |                     | "None" を返します           |
+-------------------+---------------------+-----------------------------+
|                   | f_trace             | このフレームのトレース関数  |
|                   |                     | 、または "None"             |
+-------------------+---------------------+-----------------------------+
|                   | f_trace_lines       | ソースコードの各行について  |
|                   |                     | トレースイベントを発生させ  |
|                   |                     | るかどうかを示しま す       |
+-------------------+---------------------+-----------------------------+
|                   | f_trace_opcodes     | 命令ごとのイベントが要求さ  |
|                   |                     | れているかどうかを示します  |
+-------------------+---------------------+-----------------------------+
|                   | clear()             | ローカル変数へのすべての参  |
|                   |                     | 照を消去するために使います  |
+-------------------+---------------------+-----------------------------+
| コード            | co_argcount         | 引数の数 (キーワード限定引  |
|                   |                     | 数、および * や ** は含まな |
|                   |                     | い)                         |
+-------------------+---------------------+-----------------------------+
|                   | co_code             | コンパイルされたバイトコー  |
|                   |                     | ドそのままの文字列          |
+-------------------+---------------------+-----------------------------+
|                   | co_cellvars         | (自身が包含するスコープから |
|                   |                     | 参照される) セル変数の名前  |
|                   |                     | のタプル                    |
+-------------------+---------------------+-----------------------------+
|                   | co_consts           | バイトコード中で使用してい  |
|                   |                     | る定数のタプル              |
+-------------------+---------------------+-----------------------------+
|                   | co_filename         | コードオブジェクトを生成し  |
|                   |                     | たファイルのファイル名      |
+-------------------+---------------------+-----------------------------+
|                   | co_firstlineno      | Python ソースコードの先頭行 |
|                   |                     | の番号                      |
+-------------------+---------------------+-----------------------------+
|                   | co_flags            | "CO_*" ビットフラグのマップ |
|                   |                     | 。詳細は こちら を参照。    |
+-------------------+---------------------+-----------------------------+
|                   | co_freevars         | (関数のクロージャを介して参 |
|                   |                     | 照される) 自由変数の名前の  |
|                   |                     | タプル                      |
+-------------------+---------------------+-----------------------------+
|                   | co_posonlyargcount  | 位置専用引数の数            |
+-------------------+---------------------+-----------------------------+
|                   | co_kwonlyargcount   | キーワード専用引数 (** 引数 |
|                   |                     | を含まない) の数            |
+-------------------+---------------------+-----------------------------+
|                   | co_name             | コードオブジェクトが定義さ  |
|                   |                     | れたときの名前              |
+-------------------+---------------------+-----------------------------+
|                   | co_qualname         | このコードオブジェクトが定  |
|                   |                     | 義されたときの完全修飾名    |
|                   |                     | (fully qualified name)      |
+-------------------+---------------------+-----------------------------+
|                   | co_names            | 関数の引数でもローカル変数  |
|                   |                     | でもない名前のタプル        |
+-------------------+---------------------+-----------------------------+
|                   | co_nlocals          | ローカル変数の数            |
+-------------------+---------------------+-----------------------------+
|                   | co_stacksize        | 必要とされる仮想マシンのス  |
|                   |                     | タックスペース              |
+-------------------+---------------------+-----------------------------+
|                   | co_varnames         | 引数名とローカル変数名のタ  |
|                   |                     | プル                        |
+-------------------+---------------------+-----------------------------+
|                   | co_lines()          | 連続するバイトコード範囲を  |
|                   |                     | yield するイテレータを返し  |
|                   |                     | ます                        |
+-------------------+---------------------+-----------------------------+
|                   | co_positions()      | 各バイトコード命令のソース  |
|                   |                     | コード上の位置を返すイテレ  |
|                   |                     | ータを返します              |
+-------------------+---------------------+-----------------------------+
|                   | replace()           | 新たな値を設定したコードオ  |
|                   |                     | ブジェクトのコピーを返しま  |
|                   |                     | す                          |
+-------------------+---------------------+-----------------------------+
| ジェネレータ      | __name__            | name                        |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | gi_frame            | フレーム                    |
+-------------------+---------------------+-----------------------------+
|                   | gi_running          | ジェネレータが実行中かどう  |
|                   |                     | か                          |
+-------------------+---------------------+-----------------------------+
|                   | gi_suspended        | ジェネレータが中断している  |
|                   |                     | かどうか                    |
+-------------------+---------------------+-----------------------------+
|                   | gi_code             | コード                      |
+-------------------+---------------------+-----------------------------+
|                   | gi_yieldfrom        | "yield from" でイテレートさ |
|                   |                     | れているオブジェクト、また  |
|                   |                     | は "None"                   |
+-------------------+---------------------+-----------------------------+
|                   | gi_state            | ジェネレータの状態。        |
|                   |                     | "GEN_CREATED"、             |
|                   |                     | "GEN_RUNNING"、             |
|                   |                     | "GEN_SUSPENDED"、           |
|                   |                     | "GEN_CLOSED" のいずれかです |
+-------------------+---------------------+-----------------------------+
| 非同期ジェネレー  | __name__            | name                        |
| タ                |                     |                             |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | ag_await            | 待機されているオブジェクト  |
|                   |                     | 、または "None"             |
+-------------------+---------------------+-----------------------------+
|                   | ag_frame            | フレーム                    |
+-------------------+---------------------+-----------------------------+
|                   | ag_running          | ジェネレータが実行中かどう  |
|                   |                     | か                          |
+-------------------+---------------------+-----------------------------+
|                   | ag_suspended        | ジェネレータが中断している  |
|                   |                     | かどうか                    |
+-------------------+---------------------+-----------------------------+
|                   | ag_code             | コード                      |
+-------------------+---------------------+-----------------------------+
|                   | ag_state            | 非同期ジェネレータの状態。  |
|                   |                     | "AGEN_CREATED"、            |
|                   |                     | "AGEN_RUNNING"、            |
|                   |                     | "AGEN_SUSPENDED"、          |
|                   |                     | "AGEN_CLOSED" のいずれかで  |
|                   |                     | す                          |
+-------------------+---------------------+-----------------------------+
| コルーチン        | __name__            | name                        |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | cr_await            | 待機されているオブジェクト  |
|                   |                     | 、または "None"             |
+-------------------+---------------------+-----------------------------+
|                   | cr_frame            | フレーム                    |
+-------------------+---------------------+-----------------------------+
|                   | cr_running          | コルーチンが実行中かどうか  |
+-------------------+---------------------+-----------------------------+
|                   | cr_suspended        | コルーチンが中断しているか  |
|                   |                     | どうか                      |
+-------------------+---------------------+-----------------------------+
|                   | cr_code             | コード                      |
+-------------------+---------------------+-----------------------------+
|                   | cr_origin           | "None" またはコルーチンが生 |
|                   |                     | 成された場所。 "sys.set_co  |
|                   |                     | routine_origin_tracking_de  |
|                   |                     | pth()" を参照。             |
+-------------------+---------------------+-----------------------------+
|                   | cr_state            | コルーチンの状態。          |
|                   |                     | "CORO_CREATED"、            |
|                   |                     | "CORO_RUNNING"、            |
|                   |                     | "CORO_SUSPENDED"、          |
|                   |                     | "CORO_CLOSED" のいずれかで  |
|                   |                     | す                          |
+-------------------+---------------------+-----------------------------+
| 組み込み          | __doc__             | ドキュメント文字列          |
+-------------------+---------------------+-----------------------------+
|                   | __name__            | 関数、メソッドの元々の名前  |
+-------------------+---------------------+-----------------------------+
|                   | __qualname__        | qualified name              |
+-------------------+---------------------+-----------------------------+
|                   | __self__            | メソッドが束縛されているイ  |
|                   |                     | ンスタンス、関数が定義され  |
|                   |                     | ているモジュールオ ブジェク |
|                   |                     | ト、または "None"           |
+-------------------+---------------------+-----------------------------+

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

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

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

バージョン 3.11 で変更: ジェネレータに "gi_suspended" 属性を追加しまし
た。

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

バージョン 3.12 で変更: 非同期ジェネレータに "ag_suspended" 属性を追加
しました。

バージョン 3.14 で変更: フレームに "f_generator" 属性を追加しました。

バージョン 3.15 で変更: ジェネレータに "gi_state"、コルーチンに
"cr_state"、非同期ジェネレータに "ag_state" 属性を追加しました。

inspect.getmembers(object[, predicate])

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

   注釈:

     "getmembers()" がメタクラスで定義されたクラス属性を返すのは、引数
     がクラスで、かつその属性がメタクラスのカスタム "__dir__()" に列挙
     されている場合だけです。

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" を
   返します。

   "list[int]" など、クラスの ジェネリックエイリアス に対しては
   "False" を返します。

inspect.ismethod(object)

   オブジェクトが Python で書かれた束縛メソッドの場合、"True" を返しま
   す。

   注釈:

     例えば、次のクラスを考えます。

        >>> class Greeter:
        ...     def say_hello(self):
        ...         print('hello!')

     "Greeter" クラスのインスタンスを通じて "say_hello" ("Greeter" の
     名前空間で定義された *関数*) にアクセスすると、束縛メソッド (*イ
     ンスタンスメソッド* とも呼ばれます) が作成されます。

        >>> instance = Greeter()

        >>> instance.say_hello
        <bound method Greeter.say_hello of <__main__.Greeter object ...>>
        >>> ismethod(instance.say_hello)
        True
        >>> isfunction(instance.say_hello)
        False

     "Greeter" クラスを通じて "say_hello" にアクセスすると、関数自体が
     返されます。 この関数に対しては、"ismethod()" は "False" を返しま
     すが、"isfunction()" は "True" を返します。

        >>> Greeter.say_hello
        <function Greeter.say_hello at 0x7f7503854a90>
        >>> ismethod(Greeter.say_hello)
        False
        >>> isfunction(Greeter.say_hello)
        True

     詳細は メソッド を参照してください。

inspect.isfunction(object)

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

   例については "ismethod()" の注記を参照してください。

inspect.ispackage(object)

   オブジェクトが *パッケージ* なら "True" を返します。

   Added in version 3.14.

inspect.isgeneratorfunction(object)

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

   Python のジェネレータ関数から作成された束縛メソッドに対しても
   "True" を返します (詳細は メソッド を参照)。

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

   バージョン 3.10.6 で変更: *ダックタイピング* による関数のようなオブ
   ジェクトでも、コードオブジェクトに "CO_GENERATOR" フラグがあれば
   "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.10.6 で変更: *ダックタイピング* による関数のようなオブ
   ジェクトでも、コードオブジェクトに "CO_COROUTINE" フラグがあれば
   "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.10.6 で変更: *ダックタイピング* による関数のようなオブ
   ジェクトでも、コードオブジェクトに "CO_ASYNC_GENERATOR" フラグがあ
   れば "True" を返すようになりました。

   バージョン 3.13 で変更: "functools.partialmethod()" でラップされた
   関数でも、元の関数が *非同期ジェネレータ* 関数なら "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)

   オブジェクトがメソッドデスクリプタなら "True" を返します。 ただし、
   "isclass()"、"ismethod()"、"isfunction()" のいずれかが真の場合は
   "False" を返します。

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

   "isclass()"、"ismethod()"、"isfunction()" のいずれかでも真になるメ
   ソッドデスクリプタに対しては、この関数は "False" を返します。 それ
   らの判定のほうが、より多くの性質を保証するためです。 例えば
   "ismethod()" が真となるオブジェクトでは、"__func__" 属性があると分
   かります。

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

inspect.isdatadescriptor(object)

   オブジェクトがデータデスクリプタなら "True" を返します。 ただし、
   "isclass()"、"ismethod()"、"isfunction()" のいずれかが真の場合は
   "False" を返します。

   データデスクリプタは、"__set__()" メソッド、"__delete__()" メソッド
   、またはその両方を必ず持ちます。 さらに "__get__()" メソッドを持つ
   場合もあります。

   データデスクリプタの例には、"プロパティ"、getset デスクリプタ、メン
   バーデスクリプタがあります。 後の 2 つ (C 拡張モジュールでのみ定義
   されます) には、それぞれ "isgetsetdescriptor()" と
   "ismemberdescriptor()" という、より限定的な判定関数があります。

   データデスクリプタには "__name__" と "__doc__" 属性もある場合があり
   ます (プロパティ、getset デスクリプタ、メンバーデスクリプタなど)。
   ただし、一般に常に存在するとは限りません。

   バージョン 3.8 で変更: この関数は "__set__()" メソッドだけを持つオ
   ブジェクトもデータデスクリプタと判定するようになりました
   ("__get__()" の存在は不要になりました)。 また、"__delete__()" を持
   ち "__set__()" を持たないオブジェクトも、以前とは異なり正しくデータ
   デスクリプタと認識するようになりました。

inspect.isgetsetdescriptor(object)

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

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

inspect.ismemberdescriptor(object)

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

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


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

inspect.getdoc(object, *, inherit_class_doc=True, fallback_to_class_doc=True)

   オブジェクトのドキュメント文字列を取得し、"cleandoc()" で整形します
   。 オブジェクトにドキュメント文字列がない場合は、次のようにします。

   * オブジェクトがクラスで *inherit_class_doc* が真 (デフォルト) の場
     合、継承階層からドキュメント文字列を取得します。

   * オブジェクトがメソッド、プロパティ、またはデスクリプタの場合、継
     承階層からドキュメント文字列を取得します。

   * それ以外で *fallback_to_class_doc* が真 (デフォルト) の場合、オブ
     ジェクトのクラスからドキュメント文字列を取得します。

   ドキュメント文字列が不正か存在しない場合は、"None" を返します。

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

   バージョン 3.15 で変更: *inherit_class_doc* と
   *fallback_to_class_doc* 引数を追加しました。"cached_property" オブ
   ジェクトのドキュメント文字列も、オーバーライドされていなければ継承
   されるようになりました。

inspect.getcomments(object)

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

inspect.getfile(object)

   オブジェクトが定義された (テキストまたはバイナリの) ファイル名を返
   します。 ソースコードを取得できない場合は "OSError" を送出します。
   オブジェクトが組み込みのモジュール、クラス、関数の場合は
   "TypeError" で失敗します。

inspect.getmodule(object)

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

inspect.getsourcefile(object)

   オブジェクトが定義された Python ソースファイルの名前を返します。 ソ
   ースを取得する方法が分からなければ "None" を返します。 ソースコード
   を取得できない場合は "OSError" を送出します。 オブジェクトが組み込
   みのモジュール、クラス、関数の場合は "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, annotation_format=Format.VALUE)

   *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 の呼び出し可能なオブジェクトを受け付けます。

   アノテーションのいくつかが (たとえば "from __future__ import
   annotations" が使われていることを理由に) 文字列である場合、
   "signature()" は "annotationlib.get_annotations()" を使って「非文字
   列化」すなわち文字列アノテーションを解決して本来のアノテーションに
   戻すことを試みます。アノテーションの解決を行う際には *globals*,
   *locals*, および *eval_str* パラメータが
   "annotationlib.get_annotations()" に渡されます; これらのパラメータ
   を使う方法についての説明は "annotationlib.get_annotations()" のドキ
   ュメンテーションを参照してください。返されるアノテーションの形式を
   制御するため、 *annotation_format* パラメータには
   "annotationlib.Format" 列挙型のメンバーを渡すことができます。たとえ
   ばアノテーションを文字列形式で返すためには
   "annotation_format=annotationlib.Format.STRING" を使ってください。

   シグネチャを提供できない場合は "ValueError" 例外を送出します。また
   オブジェクトの型がサポートされていない場合は "TypeError" 例外を送出
   します。さらに、アノテーションが文字列化されており、 *eval_str* が
   偽でない場合、アノテーションを「非文字列化」するために
   "annotationlib.get_annotations()" 内部で呼ばれる "eval()" により、
   いかなる種類の例外も送出される可能性があります。

   関数シグネチャにおけるスラッシュ (/) は、それより前のパラメータが位
   置専用引数であることを示します。より詳しい情報は、 位置専用引数に関
   する FAQ エントリ を参照してください。

   バージョン 3.5 で変更: *follow_wrapped* 引数を追加しました。
   *callable* 自体のシグネチャを取得するには "False" を渡してください
   (デコレータでラップされた呼び出し可能オブジェクトをたどるための
   "callable.__wrapped__" は使われません)。

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

   バージョン 3.14 で変更: *annotation_format* パラメータが追加されま
   した。

   注釈:

     いくつかの呼び出し可能オブジェクトは、ある 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 で変更: Python がキーワード専用パラメータの宣言順
      序の保持を明示的に保証するようになったのは、バージョン 3.7 から
      です。 ただし、実際には 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, quote_annotation_strings=True)

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

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

      *quote_annotation_strings* が偽の場合、シグネチャ内の *アノテー
      ション* が文字列であれば、前後の引用符を付けずに表示します。 こ
      れは、シグネチャが "STRING" 形式で作られた場合や、"from
      __future__ import annotations" を使った場合に便利です。

      Added in version 3.13.

      バージョン 3.14 で変更: *unquote_annotations* パラメータが追加さ
      れました。

   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, *, annotation_format=Format.VALUE)

   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 との互換
   性を維持することが必要なコードで利用されるために残されています。

   *annotation_format* 引数に "annotationlib.Format" 列挙型のメンバー
   を渡すと、返すアノテーションの形式を制御できます。 例えば、文字列形
   式で返すには "annotation_format=annotationlib.Format.STRING" を指定
   します。 デフォルトの "VALUE" 形式では、引数仕様の作成時に例外が送
   出される場合があります。

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

   バージョン 3.6 で変更: このメソッドは、Python 3.5 で "signature()"
   を使うことを推奨して非推奨と記載されていましたが、その決定は撤回さ
   れました。 古い "getargspec()" API から移行する、単一ソースで
   Python 2 と 3 の両方に対応するコードのために、明確にサポートされた
   標準インターフェースを復活させるためです。

   バージョン 3.7 で変更: Python がキーワード専用パラメータの宣言順序
   の保持を明示的に保証するようになったのは、バージョン 3.7 からです。
   ただし、実際には Python 3 では常にこの順序が保持されていました。

   バージョン 3.15 で変更: *annotation_format* パラメータが追加されま
   した。

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, format=annotationlib.Format.VALUE)

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

   これは "annotationlib.get_annotations()" のエイリアスです; 詳細はそ
   の関数のドキュメントを参照してください。

   注意:

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

   Added in version 3.10.

   バージョン 3.14 で変更: この関数は
   "annotationlib.get_annotations()" のエイリアスになりました。
   "inspect.get_annotations" として呼び出しても、引き続き正しく動作し
   ます。


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

以下の関数のうちいくつかは "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)
inspect.getattr_static(obj, attr, default)

   デスクリプタプロトコル、"__getattr__()"、"__getattribute__()" を介
   する動的な属性検索を行わずに属性を取得します。

   注: この関数は、"getattr" が取得できる属性 (動的に作成される属性な
   ど) をすべて取得できるとは限りません。 逆に、"getattr" では取得でき
   ない属性 ("AttributeError" を送出するデスクリプタなど) が見つかる場
   合もあります。 また、インスタンスのメンバーではなくデスクリプタオブ
   ジェクトを返す場合もあります。

   インスタンスの "__dict__" が他のメンバー (プロパティなど) に隠され
   ている場合、この関数ではインスタンスのメンバーを見つけられません。

   Added in version 3.2.

"getattr_static()" は、スロットデスクリプタや C で実装されたオブジェク
トの getset デスクリプタなどを解決しません。 属性の実際の値の代わりに
、デスクリプタオブジェクトを返します。

以下のようなコードでこれらを処理できます。 ただし、任意の getset デス
クリプタを呼び出すと、コードが実行される場合があります。

   # 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


ジェネレータ、コルーチン、非同期ジェネレータの現在の状態
========================================================

コルーチンのスケジューラを実装する場合など、ジェネレータを高度に活用す
る際には、現在実行中なのか、実行の開始や再開を待っているのか、すでに終
了しているのかを調べられると便利です。 "getgeneratorstate()" を使うと
、ジェネレータの現在の状態を簡単に判定できます。

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: 実行の開始を待っています。

   * AGEN_RUNNING: インタープリタが現在実行しています。

   * AGEN_SUSPENDED: yield 式で現在中断しています。

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

   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.

   *generator* が *ジェネレータ* で、現在関連付けられたフレームがなけ
   れば、空の辞書を返します。 *generator* が Python のジェネレータオブ
   ジェクトでない場合は、"TypeError" を送出します。

   この関数は、ジェネレータが調査用に Python スタックフレームを公開し
   ていることに依存しますが、すべての Python 実装で保証されるわけでは
   ありません。 公開していない実装では、常に空の辞書を返します。

   Added in version 3.3.

inspect.getcoroutinelocals(coroutine)

   この関数は "getgeneratorlocals()" と同様ですが、"async def" 関数が
   作成したコルーチンオブジェクトを対象とします。

   Added in version 3.5.

inspect.getasyncgenlocals(agen)

   この関数は "getgeneratorlocals()" と同様ですが、"yield" 文を使う
   "async def" 関数が作成した非同期ジェネレータオブジェクトを対象とし
   ます。

   Added in version 3.12.


コードオブジェクトのビットフラグ
================================

Python のコードオブジェクトには、以下のフラグのビットマップである
"co_flags" 属性があります。

inspect.CO_OPTIMIZED

   コードオブジェクトが最適化され、高速なローカル変数を使います。

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

   コードオブジェクトが可変長位置引数 ("*args" のような引数) を持ちま
   す。

inspect.CO_VARKEYWORDS

   コードオブジェクトが可変長キーワード引数 ("**kwargs" のような引数)
   を持ちます。

inspect.CO_NESTED

   コードオブジェクトが入れ子の関数である場合に、このフラグが設定され
   ます。

inspect.CO_GENERATOR

   コードオブジェクトがジェネレータ関数である場合、つまり実行するとジ
   ェネレータオブジェクトを返す場合に、このフラグが設定されます。

inspect.CO_COROUTINE

   コードオブジェクトがコルーチン関数である場合に、このフラグが設定さ
   れます。 このコードオブジェクトを実行するとコルーチンオブジェクトを
   返します。 詳細は **PEP 492** を参照してください。

   Added in version 3.5.

inspect.CO_ITERABLE_COROUTINE

   このフラグは、ジェネレータをジェネレータベースのコルーチンに変換す
   るために使います。 このフラグを持つジェネレータオブジェクトは
   "await" 式で使え、コルーチンオブジェクトに対して "yield from" を使
   うこともできます。 詳細は **PEP 492** を参照してください。

   Added in version 3.5.

inspect.CO_ASYNC_GENERATOR

   コードオブジェクトが非同期ジェネレータ関数である場合に、このフラグ
   が設定されます。 このコードオブジェクトを実行すると非同期ジェネレー
   タオブジェクトを返します。 詳細は **PEP 525** を参照してください。

   Added in version 3.6.

inspect.CO_HAS_DOCSTRING

   ソースコードでコードオブジェクトにドキュメント文字列が指定されてい
   る場合に、このフラグが設定されます。 設定されている場合、ドキュメン
   ト文字列は "co_consts" の最初の要素です。

   Added in version 3.14.

inspect.CO_METHOD

   コードオブジェクトがクラススコープ内で定義された関数である場合に、
   このフラグが設定されます。

   Added in version 3.14.

注釈:

  これらのフラグは CPython 固有であり、他の Python 実装では定義されて
  いない場合があります。 また、フラグは実装の詳細であり、将来の Python
  リリースで削除されたり非推奨になったりする可能性があります。 オブジ
  ェクトを調べるには、"inspect" モジュールの公開 API を使うことを推奨
  します。


バッファフラグ
==============

class inspect.BufferFlags

   バッファプロトコル を実装するオブジェクトの "__buffer__()" メソッド
   に渡せるフラグを表す "enum.IntFlag" です。

   フラグの意味は バッファリクエストのタイプ で説明しています。

   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.


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

"inspect" モジュールは、コマンドラインからオブジェクトを調べる基本的な
機能も提供します。

デフォルトでは、モジュール名を受け取り、そのモジュールのソースを表示し
ます。 コロンと対象オブジェクトの修飾名を追加すると、代わりにモジュー
ル内のクラスや関数を表示できます。

--details

   ソースコードの代わりに、指定されたオブジェクトの情報を表示します

バージョン 3.15 で変更: "--details" オプションは、ソースコードを取得で
きないモジュールの基本的な情報表示をサポートし、モジュールがフリーズさ
れている場合はその旨を示すようになりました。 また、指定した対象への参
照が、そのオブジェクトの正式な名前でない場合も、その旨を示します。
