目次

前のトピックへ

28.11. gc — ガベージコレクタインターフェース

次のトピックへ

28.13. site — サイト固有の設定フック

このページ

28.12. inspect — 使用中オブジェクトの情報を取得する

バージョン 2.1 で追加.

inspect は、モジュール・クラス・メソッド・関数・トレースバック・フレームオブジェクト・コードオブジェクトなどのオブジェクトから情報を取得 する関数を定義しており、クラスの内容を調べる、メソッドのソースコードを取得する、関数の引数リストを取得して整形する、トレースバックから必要な情報 だけを取得して表示する、などの処理を行う場合に利用します。

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

28.12.1. 型とメンバ

getmembers() は、クラスやモジュールなどのオブジェクトからメンバを取得します。名前が”is”で始まる 16 個の関数は、 getmembers() の2番目の引数として利用する事ができますし、以下のような特殊属性を参照できるかどうか調べる時にも使えます。

Type Attribute Description Notes
module __doc__ ドキュメント文字列  
  __file__ ファイル名(組み込みモジュールには存在しない  
class __doc__ ドキュメント文字列  
  __module__ クラスを定義しているモジュールの名前  
method __doc__ ドキュメント文字列  
  __name__ メソッドが定義された時の名前  
  im_class メソッドを呼び出すために必要なクラスオブジェクト (1)
  im_func or __func__ メソッドを実装している関数オブジェクト  
  im_self or __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:

  1. バージョン 2.2 で変更: im_class 従来、メソッドを定義しているクラスを参照するために使用していた.

inspect.getmembers(object[, predicate])

オブジェクトの全メンバを、(名前, 値)の組み合わせのリストで返します。リストはメンバ名でソートされています。 predicate が指定されている場 合、predicateの戻り値が真となる値のみを返します。

ノート

getmembers() は、引数がクラスの場合にメタクラス属性を返さない。 (この動作は dir() 関数に合わせてあります。)

inspect.getmoduleinfo(path)

path で指定したファイルがモジュールであればそのモジュールがPython でどのように解釈されるかを示す``(name, suffix, mode, mtype)``のタプルを返し、モジュールでなければ `` None``を返します。 name はパッケージ名を含まないモジュール 名、 suffix はファイル名からモジュール名を除いた残りの部分(ドットによる拡張子とは限らない)、 modeopen() で指定されるフ ァイルモード('r' または 'rb')、 mtypeimp で定義している整定数のいずれかが指定されます。モジュール タイプに付いては imp を参照してください。

バージョン 2.6 で変更: .. Returns a named tuple ModuleInfo(name, suffix, mode,    module_type). 名前付きタプル(named tuple) の ModuleInfo(name, suffix, mode, module_type) を返します。

inspect.getmodulename(path)

path で指定したファイルの、パッケージ名を含まないモジュール名を返します。この処理は、インタープリタがモジュールを検索する時と同じアルゴ リズムで行われます。ファイルがこのアルゴリズムで見つからない場合には None が返ります。

inspect.ismodule(object)

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

inspect.isclass(object)

オブジェクトがクラスの場合は真を返します。

inspect.ismethod(object)

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

inspect.isfunction(object)

オブジェクトがPythonの関数、または無名関数(lambda)の場合は真を返します。

inspect.isgeneratorfunction(object)

object がPythonのジェネレータ関数であるときに真を返します。

バージョン 2.6 で追加.

inspect.isgenerator(object)

object がジェネレータであるときに真を返します。

バージョン 2.6 で追加.

inspect.istraceback(object)

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

inspect.isframe(object)

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

inspect.iscode(object)

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

inspect.isbuiltin(object)

オブジェクトが組み込み関数の場合は真を返します。

inspect.isroutine(object)

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

inspect.isabstract(object)

object が抽象規定型(ABC)であるときに真を返します。

バージョン 2.6 で追加.

inspect.ismethoddescriptor(object)

オブジェクトがメソッドデスクリプタの場合に真を返しますが、 ismethod(), isclass() または isfunction() が真の場合には真を返しません。

この機能は Python 2.2 から新たに追加されたもので、例えば int.__add__ は真になります。このテストをパスするオブジェクトは __get__ 属性を持ちますが __set__ 属性を持ちません。 それ以外の属性を持っているかもしれません。 通常 __name__ を持っていますし、しばしば __doc__ も持っています。

デスクリプタを使って実装されたメソッドで、上記のいずれかのテストもパスしているものは、 ismethoddescriptor() では偽を返します。これは単に他のテストの方がもっと確実だからです – 例えば、 ismethod() をパスしたオブジェクトは im_func 属性などを持っていると期待できます。

inspect.isdatadescriptor(object)

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

データデスクリプタは __get__ および __set__ 属性の両方を持ちます。 データデスクリプタの例は (Python 上で定義された) プロパティや getset やメンバです。 後者のふたつは C で定義されており、個々の型に特有のテストも行います。そのため、Python の実装よりもより確実です。 通常、データデスクリプタは __name____doc__ 属性を持ちます (プロパティ、 getset 、メンバは両方の属性を持っています) が、保証されているわけではありません。

バージョン 2.3 で追加.

inspect.isgetsetdescriptor(object)

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

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

バージョン 2.5 で追加.

inspect.ismemberdescriptor(object)

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

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

バージョン 2.5 で追加.

28.12.2. ソース参照

inspect.getdoc(object)

cleandoc() でクリーンアップされた、オブジェクトのドキュメンテーション文字列を取得します。

inspect.getcomments(object)

オブジェクトがクラス・関数・メソッドの何れかの場合は、オブジェクトのソースコードの直後にあるコメント行(複数行)を、単一の文字列として返し ます。オブジェクトがモジュールの場合、ソースファイルの先頭にあるコメントを返します。

inspect.getfile(object)

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

inspect.getmodule(object)

オブジェクトを定義しているモジュールを推測します。

inspect.getsourcefile(object)

オブジェクトを定義しているPythonソースファイルの名前を返します。オブジェクトが組み込みのモジュール、クラス、関数の場合には、 TypeError 例外が発生します。

inspect.getsourcelines(object)

オブジェクトのソース行のリストと開始行番号を返します。引数にはモジュール・クラス・メソッド・関数・トレースバック・フレーム・コードオブジェク トを指定する事ができます。戻り値は指定したオブジェクトに対応するソースコードのソース行リストと元のソースファイル上での開始行となります。ソー スコードを取得できない場合は IOError が発生します。

inspect.getsource(object)

オブジェクトのソースコードを返します。引数にはモジュール・クラス・メソッド・関数・トレースバック・フレーム・コードオブジェクトを指定する事が できます。ソースコードは単一の文字列で返します。ソースコードを取得できない場合は IOError が発生します。

inspect.cleandoc(doc)

インデントされた docstring から、コードブロックまでのインデントを削除します。 2行目以降では行頭の空白は一様に削除されます。 全てのタブはスペースに展開されます。

バージョン 2.6 で追加.

28.12.3. クラスと関数

inspect.getclasstree(classes[, unique])

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

inspect.getargspec(func)

関数の引数名とデフォルト値を取得します。戻り値は長さ4のタプルで、次の値を返します:(args, varargs, varkw, defaults)args は引数名のリストです(ネストしたリストが格納される場合があります) varargsvarkw* 引数と ** 引数の名前で、引数がなければ None となります。 defaults は引数のデフォルト値のタプルか、デフォルト値がない場合は None です。 このタプルに n 個の要素があれば、各要素は args の後ろから n 個分の引数のデフォルト値となります。

バージョン 2.6 で変更: .. Returns a named tuple ArgSpec(args, varargs, keywords,    defaults). ArgSpec(args, varargs, keywords, defaults) 形式の名前付きタプル(named tuple)を返します。

inspect.getargvalues(frame)

指定したフレームに渡された引数の情報を取得します。戻り値は長さ4のタプルで、次の値を返します:(args, varargs, varkw, locals)``。 *args* は引数名のリストです(ネストしたリストが格納される場合があります)。 *varargs* *varkw* は``*``引数と ``** 引数の名前で、引数がなければ None となります。 * locals*は指定したフレームのローカル変数の辞書です。

バージョン 2.6 で変更: .. Returns a named tuple ArgInfo(args, varargs, keywords,    locals). ArgInfo(args, varargs, keywords, locals) 形式の名前付きタプル(named tuple)を返します。

inspect.formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])

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

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

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

inspect.getmro(cls)

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

28.12.4. インタープリタスタック

以下の関数には、戻り値として”フレームレコード”を返す関数があります。” フレームレコード”は長さ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 には、戻り値のソース行リストに何行分のソースを含めるかを指定します。ソース行リストには、実行中の行を中心 として指定された行数分のリストを返します。

inspect.getframeinfo(frame[, context])

フレーム又はトレースバックオブジェクトの情報を取得します。フレームレコードの先頭要素を除いた、長さ5のタプルを返します。

バージョン 2.6 で変更: .. Returns a named tuple Traceback(filename, lineno, function,    code_context, index). Traceback(filename, lineno, function, code_context, index) 形式の名前付きタプル(named tuple)を返します。

inspect.getouterframes(frame[, context])

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

inspect.getinnerframes(traceback[, context])

指定したフレームと、その内側の全フレームのフレームレコードを返します。内のフレームとは frame から続く一連の関数呼び出しを示します。戻り 値のリストの先頭は traceback のフレームレコードで、末尾の要素は例外が発生した位置を示します。

inspect.currentframe()

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

inspect.stack([context])

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

inspect.trace([context])

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