バージョン 2.1 で追加.
inspect は、 活動中のオブジェクト (モジュール、クラス、メソッド、関数、トレースバック、フレームオブジェクト、コードオブジェクトなど) から情報を取得する関数を定義しており、クラスの内容を調べたり、メソッドのソースコードを取得したり、関数の引数リストを取り出して整形したり、詳細なトレースバックを表示するのに必要な情報を取得したりするために利用できます。
このモジュールの機能は4種類に分類することができます。型チェック、ソースコードの情報取得、クラスや関数からの情報取得、インタープリタのスタック情報の調査です。
getmembers() は、クラスやモジュールなどのオブジェクトからメンバーを取得します。名前が”is”で始まる16個の関数は、主に getmembers() の第2引数として利用するために提供されています。以下のような特殊属性を参照できるかどうか調べる時にも使えるでしょう。
型 | 属性 | 説明 | 注 |
---|---|---|---|
module | __doc__ | ドキュメント文字列 | |
__file__ | ファイル名 (組み込みモジュールには存在しません) | ||
class | __doc__ | ドキュメント文字列 | |
__module__ | クラスを定義しているモジュールの名前 | ||
method | __doc__ | ドキュメント文字列 | |
__name__ | メソッドが定義された時の名前 | ||
im_class | メソッドを呼び出すために必要なクラスオブジェクト | (1) | |
im_func または __func__ | メソッドを実装している関数オブジェクト | ||
im_self または __self__ | メソッドに結合しているインスタンス、または None | ||
function | __doc__ | ドキュメント文字列 | |
__name__ | 関数が定義された時の名前 | ||
func_code | 関数をコンパイルしたバイトコード (bytecode) を格納するコードオブジェクト | ||
func_defaults | 引数のデフォルト値のタプル | ||
func_doc | (__doc__と同じ) | ||
func_globals | 関数を定義した時のグローバル名前空間 | ||
func_name | (__name__と同じ) | ||
generator | __iter__ | コンテナを通したイテレーションのために定義されます | |
close | イテレーションを停止するために、ジェネレータの内部で GeneratorExitexception を発生させます | ||
gi_code | コードオブジェクト | ||
gi_frame | フレームオブジェクト。ジェネレータが終了したあとは None になることもあります | ||
gi_running | ジェネレータが実行中の時は 1 それ以外の場合は 0 | ||
next | コンテナから次の要素を返します | ||
send | ジェネレータを再開して、現在の yield 式の結果となる値を送ります | ||
throw | ジェネレータ内部で例外を発生させるために用います | ||
traceback | tb_frame | このレベルのフレームオブジェクト | |
tb_lasti | 最後に実行しようとしたバイトコード中のインストラクションを示すインデックス | ||
tb_lineno | 現在の Python ソースコードの行番号 | ||
tb_next | このオブジェクトの内側 (このレベルから呼び出された) のトレースバックオブジェクト | ||
frame | f_back | 外側 (このフレームを呼び出した) のフレームオブジェクト | |
f_builtins | このフレームで参照している組み込み名前空間 | ||
f_code | このフレームで実行しているコードオブジェクト | ||
f_exc_traceback | このフレームで例外が発生した場合にはトレースバックオブジェクト、それ以外なら None | ||
f_exc_type | このフレームで例外が発生した場合には例外型、それ以外なら None | ||
f_exc_value | このフレームで例外が発生した場合には例外の値、それ以外なら None | ||
f_globals | このフレームで参照しているグローバル名前空間 | ||
f_lasti | 最後に実行しようとしたバイトコードのインデックス | ||
f_lineno | 現在の Python ソースコードの行番号 | ||
f_locals | このフレームで参照しているローカル名前空間 | ||
f_restricted | 制限実行モードなら1、それ以外なら0 | ||
f_trace | このフレームのトレース関数、または None | ||
code | co_argcount | 引数の数 (* や ** 引数は含まない) | |
co_code | コンパイルされたバイトコードそのままの文字列 | ||
co_consts | バイトコード中で使用している定数のタプル | ||
co_filename | コードオブジェクトを生成したファイルのファイル名 | ||
co_firstlineno | Python ソースコードの先頭行 | ||
co_flags | 以下の値の組み合わせ: 1=optimized | 2=newlocals | 4=*arg | 8=**arg | ||
co_lnotab | 行番号からバイトコードインデックスへの変換表を文字列にエンコードしたもの | ||
co_name | コードオブジェクトが定義されたときの名前 | ||
co_names | ローカル変数名のタプル | ||
co_nlocals | ローカル変数の数 | ||
co_stacksize | 必要とされる仮想マシンのスタックスペース | ||
co_varnames | 引数名とローカル変数名のタプル | ||
builtin | __doc__ | ドキュメント文字列 | |
__name__ | 関数、メソッドの元々の名前 | ||
__self__ | メソッドが結合しているインスタンス、または None |
Note:
バージョン 2.2 で変更: im_class は、以前はメソッドを定義しているクラスを指していました。
オブジェクトの全メンバーを、 (名前, 値) の組み合わせのリストで返します。リストはメンバー名でソートされています。 predicate が指定されている場合、 predicate の戻り値が真となる値のみを返します。
ノート
getmembers() は、引数がクラスの場合にメタクラス属性を返しません。 (この動作は dir() 関数に合わせてあります。)
path で指定したファイルがモジュールであれば、そのモジュールが Python でどのように解釈されるかを示す (name, suffix, mode, mtype) のタプルを返します。モジュールでなければ None を返します。 name はパッケージ名を含まないモジュール名、 suffix はファイル名からモジュール名を除いた残りの部分 (ドット区切りの拡張子であってはなりません)、 mode は open() で指定されるファイルモード ('r' または 'rb')、 mtype は imp で定義している定数のいずれかが指定されます。モジュールタイプについては imp を参照してください。
バージョン 2.6 で変更: 名前付きタプル (named tuple) の ModuleInfo(name, suffix, mode, module_type) を返します。
path で指定したファイルの、パッケージ名を含まないモジュール名を返します。この処理は、インタープリタがモジュールを検索する時と同じアルゴリズムで行われます。ファイルがこのアルゴリズムで見つからない場合には None が返ります。
オブジェクトがモジュールの場合は真を返します。
オブジェクトがクラスの場合は真を返します。
オブジェクトがメソッドの場合は真を返します。
object が Python のジェネレータ関数であるときに真を返します。
バージョン 2.6 で追加.
object がジェネレータであるときに真を返します。
バージョン 2.6 で追加.
オブジェクトがトレースバックの場合は真を返します。
オブジェクトがフレームの場合は真を返します。
オブジェクトがコードの場合は真を返します。
オブジェクトが組み込み関数の場合は真を返します。
オブジェクトがユーザ定義か組み込みの関数またはメソッドの場合は真を返します。
object が抽象規定型 (ABC) であるときに真を返します。
バージョン 2.6 で追加.
オブジェクトがメソッドデスクリプタの場合に真を返しますが、 ismethod(), isclass() または isfunction() が真の場合には真を返しません。
この機能は Python 2.2 から新たに追加されたもので、例えば int.__add__ は真になります。このテストをパスするオブジェクトは __get__ 属性を持ちますが __set__ 属性を持ちません。それ以外の属性を持っているかもしれません。通常 __name__ を持っていますし、しばしば __doc__ も持っています。
デスクリプタを使って実装されたメソッドで、上記のいずれかのテストもパスしているものは、 ismethoddescriptor() では偽を返します。これは単に他のテストの方がもっと確実だからです – 例えば、 ismethod() をパスしたオブジェクトは im_func 属性などを持っていると期待できます。
オブジェクトがデータデスクリプタの場合に真を返します。
データデスクリプタは __get__ および __set__ 属性の両方を持ちます。データデスクリプタの例は (Python 上で定義された) プロパティや getset やメンバーです。後者のふたつは C で定義されており、個々の型に特有のテストも行います。そのため、Python の実装よりもより確実です。通常、データデスクリプタは __name__ や __doc__ 属性を持ちます (プロパティ、 getset 、メンバーは両方の属性を持っています) が、保証されているわけではありません。
バージョン 2.3 で追加.
オブジェクトが getset デスクリプタの場合に真を返します。
CPython implementation detail:
getset とは、拡張モジュールで PyGetSetDef 構造体を用いて定義された属性のことです。そのような型を持たない Python 実装の場合は、このメソッドは常に False を返します。
バージョン 2.5 で追加.
オブジェクトがメンバーデスクリプタの場合に真を返します。
CPython implementation detail:
メンバーデスクリプタとは、拡張モジュールで PyMemberDef 構造体を用いて定義された属性のことです。そのような型を持たない Python 実装の場合は、このメソッドは常に False を返します。
バージョン 2.5 で追加.
cleandoc() でクリーンアップされた、オブジェクトのドキュメンテーション文字列を取得します。
オブジェクトがクラス、関数、メソッドのいずれかの場合は、オブジェクトのソースコードの直後にあるコメント行 (複数行) を、単一の文字列として返します。オブジェクトがモジュールの場合、ソースファイルの先頭にあるコメントを返します。
オブジェクトを定義している (テキストまたはバイナリの) ファイルの名前を返します。オブジェクトが組み込みモジュール、クラス、関数の場合は TypeError 例外が発生します。
オブジェクトを定義しているモジュールを推測します。
オブジェクトを定義している Python ソースファイルの名前を返します。オブジェクトが組み込みのモジュール、クラス、関数の場合には、 TypeError 例外が発生します。
オブジェクトのソース行のリストと開始行番号を返します。引数にはモジュール、クラス、メソッド、関数、トレースバック、フレーム、コードオブジェクトを指定することができます。戻り値は指定したオブジェクトに対応するソースコードのソース行リストと元のソースファイル上での開始行となります。ソースコードを取得できない場合は IOError が発生します。
オブジェクトのソースコードを返します。引数にはモジュール、クラス、メソッド、関数、トレースバック、フレーム、コードオブジェクトを指定することができます。ソースコードは単一の文字列で返します。ソースコードを取得できない場合は IOError が発生します。
インデントされた docstring から、コードブロックまでのインデントを削除します。 2行目以降では行頭の空白は一様に削除されます。全てのタブはスペースに展開されます。
バージョン 2.6 で追加.
リストで指定したクラスの継承関係から、ネストしたリストを作成します。ネストしたリストには、直前の要素から派生したクラスが格納されます。各要素は長さ2のタプルで、クラスと基底クラスのタプルを格納しています。 unique が真の場合、各クラスは戻り値のリスト内に一つだけしか格納されません。真でなければ、多重継承を利用したクラスとその派生クラスは複数回格納される場合があります。
Python 関数の引数名とデフォルト値を取得します。戻り値は長さ4のタプルで、次の値を返します: (args, varargs, varkw, defaults) 。 args は引数名のリストです (ネストしたリストが格納される場合があります)。 varargs と varkw は * 引数と ** 引数の名前で、引数がなければ None となります。 defaults は引数のデフォルト値のタプルか、デフォルト値がない場合は None です。このタプルに n 個の要素があれば、各要素は args の後ろから n 個分の引数のデフォルト値となります。
バージョン 2.6 で変更: ArgSpec(args, varargs, keywords, defaults) 形式の名前付きタプル (named tuple) を返します。
指定したフレームに渡された引数の情報を取得します。戻り値は長さ4のタプルで、次の値を返します: (args, varargs, varkw, locals) 。 args は引数名のリストです (ネストしたリストが格納される場合があります)。 varargs と varkw は * 引数と ** 引数の名前で、引数がなければ None となります。 locals は指定したフレームのローカル変数の辞書です。
バージョン 2.6 で変更: ArgInfo(args, varargs, keywords, locals) 形式の名前付きタプル (named tuple) を返します。
getargspec() で取得した4つの値を読みやすく整形します。 format* 引数はオプションで、名前と値を文字列に変換する整形関数を指定することができます。
getargvalues() で取得した4つの値を読みやすく整形します。 format* 引数はオプションで、名前と値を文字列に変換する整形関数を指定することができます。
cls クラスの基底クラス (cls 自身も含む) を、メソッドの優先順位順に並べたタプルを返します。結果のリスト内で各クラスは一度だけ格納されます。メソッドの優先順位はクラスの型によって異なります。非常に特殊なユーザ定義のメタクラスを使用していない限り、 cls が戻り値の先頭要素となります。
以下の関数には、戻り値として”フレームレコード”を返す関数があります。 “フレームレコード”は長さ6のタプルで、以下の値を格納しています: フレームオブジェクト、ファイル名、実行中の行番号、関数名、コンテキストのソース行のリスト、ソース行のリストにおける実行中の行のインデックス。
ノート
フレームレコードの最初の要素などのフレームオブジェクトへの参照を保存すると、循環参照になってしまう場合があります。循環参照ができると、 Python の循環参照検出機能を有効にしていたとしても関連するオブジェクトが参照しているすべてのオブジェクトが解放されにくくなり、明示的に参照を削除しないとメモリ消費量が増大する恐れがあります。
参照の削除を Python の循環参照検出機能にまかせることもできますが、 finally 節で循環参照を解除すれば確実にフレーム (とそのローカル変数) は削除されます。また、循環参照検出機能は Python のコンパイルオプションや gc.disable() で無効とされている場合がありますので注意が必要です。例:
def handle_stackframe_without_leak():
frame = inspect.currentframe()
try:
# do something with the frame
finally:
del frame
以下の関数でオプション引数 context には、戻り値のソース行リストに何行分のソースを含めるかを指定します。ソース行リストには、実行中の行を中心として指定された行数分のリストを返します。
フレームまたはトレースバックオブジェクトの情報を取得します。フレームレコードの先頭要素を除いた、長さ5のタプルを返します。
バージョン 2.6 で変更: Traceback(filename, lineno, function, code_context, index) 形式の名前付きタプル (named tuple) を返します。
指定したフレームと、その外側の全フレームのフレームレコードを返します。外側のフレームとは frame が生成されるまでのすべての関数呼び出しを示します。戻り値のリストの先頭は frame のフレームレコードで、末尾の要素は frame のスタックにある最も外側のフレームのフレームレコードとなります。
指定したフレームと、その内側の全フレームのフレームレコードを返します。内のフレームとは frame から続く一連の関数呼び出しを示します。戻り値のリストの先頭は traceback のフレームレコードで、末尾の要素は例外が発生した位置を示します。
呼び出し元のフレームオブジェクトを返します。
CPython implementation detail:
この関数はインタプリタの Python スタックフレームサポートに依存します。これは Python のすべての実装に存在している保証はありません。 Python スタックフレームサポートのない環境では、この関数は None を返します。
呼び出し元スタックのフレームレコードのリストを返します。最初の要素は呼び出し元のフレームレコードで、末尾の要素はスタックにある最も外側のフレームのフレームレコードとなります。
実行中のフレームと処理中の例外が発生したフレームの間のフレームレコードのリストを返します。最初の要素は呼び出し元のフレームレコードで、末尾の要素は例外が発生した位置を示します。