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

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

The `inspect` module provides several useful functions to help get information about live objects such as modules, classes, methods, functions, tracebacks, frame objects, and code objects. For example, it can help you examine the contents of a class, retrieve the source code of a method, extract and format the argument list for a function, or get all the information you need to display a detailed traceback.

このモジュールの機能は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_generator | returns the generator or coroutine object that owns this frame, or `None` if the frame is of a regular function
| f_trace | このフレームのトレース関数、または `None`
| f_trace_lines | indicate whether a tracing event is triggered for each source source line
| f_trace_opcodes | indicate whether per-opcode events are requested
| clear() | used to clear all references to local variables
コード | 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() | returns an iterator that yields successive bytecode ranges
| co_positions() | returns an iterator of source code positions for each bytecode instruction
| replace() | returns a copy of the code object with new values
ジェネレータ | __name__ | name
| __qualname__ | qualified name
| gi_frame | フレーム
| gi_running | ジェネレータが実行中かどうか
| gi_suspended | is the generator suspended?
| gi_code | コード
| gi_yieldfrom | `yield from` でイテレートされているオブジェクト、または `None`
| gi_state | state of the generator, one of `GEN_CREATED`, `GEN_RUNNING`, `GEN_SUSPENDED`, or `GEN_CLOSED`
非同期ジェネレータ | __name__ | name
| __qualname__ | qualified name
| ag_await | 待機されているオブジェクト、または `None`
| ag_frame | フレーム
| ag_running | ジェネレータが実行中かどうか
| ag_suspended | is the generator suspended?
| ag_code | コード
| ag_state | state of the async generator, one of `AGEN_CREATED`, `AGEN_RUNNING`, `AGEN_SUSPENDED`, or `AGEN_CLOSED`
コルーチン | __name__ | name
| __qualname__ | qualified name
| cr_await | 待機されているオブジェクト、または `None`
| cr_frame | フレーム
| cr_running | コルーチンが実行中かどうか
| cr_suspended | is the coroutine suspended?
| cr_code | コード
| cr_origin | `None` またはコルーチンが生成された場所。 `sys.set_coroutine_origin_tracking_depth()` を参照。
| cr_state | state of the coroutine, one of `CORO_CREATED`, `CORO_RUNNING`, `CORO_SUSPENDED`, or `CORO_CLOSED`
組み込み | __doc__ | ドキュメント文字列
| __name__ | 関数、メソッドの元々の名前
| __qualname__ | qualified name
| __self__ | メソッドが結合しているインスタンス、または `None`

バージョン 3.5 で変更: ジェネレータに `__qualname__` と `gi_yieldfrom` 属性が追加されました。

ジェネレータの `__name__` 属性がコード名ではなく関数名から設定されるようになり、変更できるようになりました。

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

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

バージョン 3.11 で変更: Add `gi_suspended` attribute to generators.

バージョン 3.11 で変更: Add `cr_suspended` attribute to coroutines.

バージョン 3.12 で変更: Add `ag_suspended` attribute to async generators.

バージョン 3.14 で変更: Add `f_generator` attribute to frames.

バージョン 3.15 で変更: Add `gi_state` attribute to generators, `cr_state` attribute to coroutines, and `ag_state` attribute to async generators.

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

  This function returns `False` for generic aliases of classes, such as `list[int]`.

inspect.ismethod(object)

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

  注釈

  For example, given this class:

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

  A bound method (also known as an instance method) is created when accessing `say_hello` (a function defined in the `Greeter` namespace) through an instance of the `Greeter` class:

      >>> instance = Greeter()

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

  Accessing `say_hello` through the `Greeter` class will return the function itself. For this function, `ismethod()` will return `False`, but `isfunction()` will return `True`:

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

  See メソッド for details.

inspect.isfunction(object)

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

  See the note for `ismethod()` for an example.

inspect.ispackage(object)

  Return `True` if the object is a package.

  Added in version 3.14.

inspect.isgeneratorfunction(object)

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

  It also returns `True` for bound methods created from Python generator functions (see メソッド for more information).

  バージョン 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 で変更: Functions wrapped in `functools.partialmethod()` now return `True` if the wrapped function is a asynchronous generator function.

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, *, inherit_class_doc=True, fallback_to_class_doc=True)

  Get the documentation string for an object, cleaned up with `cleandoc()`. If the documentation string for an object is not provided:

  - if the object is a class and inherit_class_doc is true (by default), retrieve the documentation string from the inheritance hierarchy;

  - if the object is a method, a property or a descriptor, retrieve the documentation string from the inheritance hierarchy;

  - otherwise, if fallback_to_class_doc is true (by default), retrieve the documentation string from the class of the object.

  Return `None` if the documentation string is invalid or missing.

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

  バージョン 3.15 で変更: Added parameters inherit_class_doc and fallback_to_class_doc.

  Documentation strings on `cached_property` objects are now inherited if not overridden.

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, 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 パラメータが追加されました。parameter was added. 特に 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 で変更: バージョン 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, 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 との互換性を維持することが必要なコードで利用されるために残されています。

  A member of the `annotationlib.Format` enum can be passed to the annotation_format parameter to control the format of the returned annotations. For example, use `annotation_format=annotationlib.Format.STRING` to return annotations in string format. Note that with the default `VALUE` format, creation of some argspecs may raise an exception.

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

  バージョン 3.6 で変更: This method was previously documented as deprecated in favour of `signature()` in Python 3.5, but that decision has been reversed in order to restore a clearly supported standard interface for single-source Python 2/3 code migrating away from the legacy `getargspec()` API.

  バージョン 3.7 で変更: バージョン 3.7 までは、Python はキーワード専用パラメータだけしか順序を保つことを明確に保証していませんでした。とはいえ 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()` のエイリアスです; 詳細はその関数のドキュメントを参照してください。

  注意

  This function may execute arbitrary code contained in annotations. See Security implications of introspecting annotations for more information.

  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, 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.

inspect.CO_HAS_DOCSTRING

  The flag is set when there is a docstring for the code object in the source code. If set, it will be the first item in `co_consts`.

  Added in version 3.14.

inspect.CO_METHOD

  The flag is set when the code object is a function defined in class scope.

  Added in version 3.14.

注釈

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 appending a colon and the qualified name of the target object.

--details

  Print information about the specified object rather than the source code

バージョン 3.15 で変更: The `--details` option now supports basic introspection for modules without available source code and indicates when modules are frozen. It also indicates when the given target reference is not the canonical name of the referenced object.