
:mod:`inspect` --- 使用中オブジェクトの情報を取得する
=====================================================

.. module:: inspect
   :synopsis: 使用中のオブジェクトから、情報とソースコードを取得する。
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>


.. versionadded:: 2.1

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

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


.. _inspect-types:

型とメンバ
----------

:func:`getmembers` は、クラスやモジュールなどのオブジェクトからメンバを取得します。名前が"is"で始まる 16
個の関数は、 :func:`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      | メソッドに結合しているインスタンス、または ``None`` |       |
|           | __self__        |                                                     |       |
+-----------+-----------------+-----------------------------------------------------+-------+
| function  | __doc__         | ドキュメント文字列                                  |       |
+-----------+-----------------+-----------------------------------------------------+-------+
|           | __name__        | 関数が定義された時の名前                            |       |
+-----------+-----------------+-----------------------------------------------------+-------+
|           | func_code       | 関数をコンパイルしたバイトコード(:term:`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)
   .. versionchanged:: 2.2
      :attr:`im_class` 従来、メソッドを定義しているクラスを参照するために使用していた.


.. function:: getmembers(object[, predicate])

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

   .. note::

      .. :func:`getmembers` does not return metaclass attributes when the argument
         is a class (this behavior is inherited from the :func:`dir` function).

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


.. function:: getmoduleinfo(path)

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

   .. versionchanged:: 2.6
      .. Returns a :term:`named tuple` ``ModuleInfo(name, suffix, mode,
         module_type)``.
      名前付きタプル(:term:`named tuple`) の ``ModuleInfo(name, suffix, mode, module_type)``
      を返します。


.. function:: getmodulename(path)

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


.. function:: ismodule(object)

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


.. function:: isclass(object)

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


.. function:: ismethod(object)

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


.. function:: isfunction(object)

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


.. function:: isgeneratorfunction(object)

   .. Return true if the object is a Python generator function.

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

   .. versionadded:: 2.6

.. function:: isgenerator(object)

   .. Return true if the object is a generator.

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

   .. versionadded:: 2.6

.. function:: istraceback(object)

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


.. function:: isframe(object)

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


.. function:: iscode(object)

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


.. function:: isbuiltin(object)

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


.. function:: isroutine(object)

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

.. function:: isabstract(object)

   .. Return true if the object is an abstract base class.

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

   .. versionadded:: 2.6


.. function:: ismethoddescriptor(object)

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

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

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


.. function:: isdatadescriptor(object)

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

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

   .. versionadded:: 2.3


.. function:: isgetsetdescriptor(object)

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

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

   .. versionadded:: 2.5


.. function:: ismemberdescriptor(object)

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

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

   .. versionadded:: 2.5


.. _inspect-source:

ソース参照
----------


.. function:: getdoc(object)

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


.. function:: getcomments(object)

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


.. function:: getfile(object)

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


.. function:: getmodule(object)

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


.. function:: getsourcefile(object)

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


.. function:: getsourcelines(object)

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


.. function:: getsource(object)

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

.. function:: cleandoc(doc)

   .. Clean up indentation from docstrings that are indented to line up with blocks
      of code.  Any whitespace that can be uniformly removed from the second line
      onwards is removed.  Also, all tabs are expanded to spaces.

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

   .. versionadded:: 2.6



.. _inspect-classes-functions:

クラスと関数
------------


.. function:: getclasstree(classes[, unique])

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


.. function:: getargspec(func)

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

   .. versionchanged:: 2.6
      .. Returns a :term:`named tuple` ``ArgSpec(args, varargs, keywords,
         defaults)``.
      ``ArgSpec(args, varargs, keywords, defaults)`` 形式の名前付きタプル(:term:`named tuple`)を返します。


.. function:: getargvalues(frame)

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

   .. versionchanged:: 2.6
      .. Returns a :term:`named tuple` ``ArgInfo(args, varargs, keywords,
         locals)``.
      ``ArgInfo(args, varargs, keywords, locals)`` 形式の名前付きタプル(:term:`named tuple`)を返します。

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

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


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

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


.. function:: getmro(cls)

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


.. _inspect-stack:

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

以下の関数には、戻り値として"フレームレコード"を返す関数があります。" フレームレコード"は長さ6のタプルで、以下の値を格納しています:フレームオ
ブジェクト・ファイル名・実行中の行番号・関数名・コンテキストのソース行のリスト・ソース行リストの実行中行のインデックス。

.. warning::

   フレームレコードの最初の要素などのフレームオブジェクトへの参照を保存すると、循環参照になってしまう場合があります。循環参照ができると、Pythonの循
   環参照検出機能を有効にしていたとしても関連するオブジェクトが参照しているすべてのオブジェクトが解放されにくくなり、明示的に参照を削除しないとメモ
   リ消費量が増大する恐れがあります。

   参照の削除をPythonの循環参照検出機能にまかせる事もできますが、 :keyword:`finally` 節で循環参照を解除すれば確実にフレーム（とそのローカル
   変数）は削除されます。また、循環参照検出機能はPythonのコンパイルオプションや :func:`gc. disable` で無効とされている場合があります
   ので注意が必要です。例： ::

      def handle_stackframe_without_leak():
          frame = inspect.currentframe()
          try:
              # do something with the frame
          finally:
              del frame

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


.. function:: getframeinfo(frame[, context])

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

   .. versionchanged:: 2.6
      .. Returns a :term:`named tuple` ``Traceback(filename, lineno, function,
         code_context, index)``.
      ``Traceback(filename, lineno, function, code_context, index)``
      形式の名前付きタプル(:term:`named tuple`)を返します。

.. function:: getouterframes(frame[, context])

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


.. function:: getinnerframes(traceback[, context])

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


.. function:: currentframe()

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


.. function:: stack([context])

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


.. function:: trace([context])

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

