フレーム (frame) オブジェクト

type PyFrameObject

次に属します: Stable ABI (不透明な構造体として).

フレームオブジェクトを記述する際に用いられる、オブジェクトを表す C 構造体です。

この構造体には公開メンバはありません。

バージョン 3.11 で変更: この構造体のメンバは公開 C API から削除されました。 詳細は What's New の該当項目 を参照してください。

フレームオブジェクトは PyEval_GetFrame() と PyThreadState_GetFrame() 関数で取得できます。

リフレクション も参照してください。

PyTypeObject PyFrame_Type

フレームオブジェクトの型です。 Python レベルの types.FrameType と同じオブジェクトです。

バージョン 3.11 で変更: 以前は、この型を使うには <frameobject.h> をインクルードする必要がありました。

PyFrameObject *PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)

新しいフレームオブジェクトを作成します。 成功した場合は新しいフレームオブジェクトへの 強参照 を返し、失敗した場合は例外を設定して NULL を返します。

int PyFrame_Check(PyObject *obj)

obj がフレームオブジェクトの場合に非ゼロを返します。

バージョン 3.11 で変更: 以前は、この関数を使うには <frameobject.h> をインクルードする必要がありました。

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)

戻り値: 新しい参照。

frame の一つ外側のフレームを取得します。

Return a strong reference, or NULL if frame has no outer frame. This raises no exceptions.

Added in version 3.9.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)

戻り値: 新しい参照。

frame の f_builtins 属性を取得します。

強参照 を返します。 結果が NULL になることはありません。

Added in version 3.11.

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.10 より).

frame のコードを取得します。

強参照 を返します。

結果 (フレームのコード) が NULL になることはありません。

Added in version 3.9.

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)

戻り値: 新しい参照。

このフレームを所有するジェネレータ、コルーチン、非同期ジェネレータを取得します。 ジェネレータに所有されていない場合は NULL を返します。 戻り値が NULL であっても例外は送出しません。

強参照 または NULL を返します。

Added in version 3.11.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)

戻り値: 新しい参照。

frame の f_globals 属性を取得します。

強参照 を返します。 結果が NULL になることはありません。

Added in version 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

frame の f_lasti 属性を取得します。

Returns -1 if frame.f_lasti is None.

Added in version 3.11.

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)

戻り値: 新しい参照。

frame の変数 name を取得します。

• 成功した場合は、変数の値への 強参照 を返します。

• 変数が存在しない場合は NameError を送出し、NULL を返します。

• エラーの場合は例外を送出し、NULL を返します。

name の型は str でなければなりません。

Added in version 3.12.

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)

戻り値: 新しい参照。

PyFrame_GetVar() と同様ですが、変数名は UTF-8 でエンコードした C 文字列です。

Added in version 3.12.

PyObject *PyFrame_GetLocals(PyFrameObject *frame)

戻り値: 新しい参照。

frame の f_locals 属性を取得します。 フレームが 最適化されたスコープ を参照する場合、ローカル変数の変更を可能にする、書き込みを反映するプロキシオブジェクトを返します。 それ以外の場合 (クラス、モジュール、exec()、eval()) は、フレームのローカル変数を表すマッピングを直接返します (locals() の説明を参照)。

強参照 を返します。

Added in version 3.11.

バージョン 3.13 で変更: As part of PEP 667, return an instance of PyFrameLocalsProxy_Type.

int PyFrame_GetLineNumber(PyFrameObject *frame)

次に属します: Stable ABI (バージョン 3.10 より).

frame が現在実行している行番号を返します。

フレームのローカル変数のプロキシ

Added in version 3.13.

The f_locals attribute on a frame object is an instance of a "frame-locals proxy". The proxy object exposes a write-through view of the underlying locals dictionary for the frame. This ensures that the variables exposed by f_locals are always up to date with the live local variables in the frame itself.

詳細は PEP 667 を参照してください。

PyTypeObject PyFrameLocalsProxy_Type

フレームの locals() プロキシオブジェクトの型。

int PyFrameLocalsProxy_Check(PyObject *obj)

obj がフレームの locals() プロキシの場合に非ゼロを返します。

従来のローカル変数 API

これらの API は 緩やかに非推奨 です。 Python 3.13 以降では何も行わず、後方互換性のためだけに存在します。

void PyFrame_LocalsToFast(PyFrameObject *f, int clear)

Python 3.13 より前では、この関数は f の f_locals 属性をローカル変数の内部の "fast" 配列にコピーし、フレームオブジェクトへの変更をインタープリタから見えるようにしていました。 clear が真の場合は、ローカル変数の辞書で値が設定されていない変数も処理していました。

バージョン 3.13 で ソフト非推奨 <Soft deprecated>: この関数は何も行わなくなりました。

void PyFrame_FastToLocals(PyFrameObject *f)

Python 3.13 より前では、この関数はインタープリタが使うローカル変数の内部の "fast" 配列を f の f_locals 属性にコピーし、ローカル変数への変更をフレームオブジェクトから見えるようにしていました。

バージョン 3.13 で ソフト非推奨 <Soft deprecated>: この関数は何も行わなくなりました。

int PyFrame_FastToLocalsWithError(PyFrameObject *f)

Python 3.13 より前では、この関数は PyFrame_FastToLocals() と同様でしたが、成功した場合は 0 を返し、失敗した場合は例外を設定して -1 を返していました。

バージョン 3.13 で ソフト非推奨 <Soft deprecated>: この関数は何も行わなくなりました。

参考

PEP 667

内部フレーム

PEP 523 を使わない限り、これは必要ありません。

struct _PyInterpreterFrame

インタープリタ内部でのフレーム表現。

Added in version 3.11.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

フレームのコードオブジェクトへの 強参照 を返します。

Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

最後に実行した命令のバイトオフセットを返します。

Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

現在実行している行の番号を返します。 行番号がない場合は -1 を返します。

Added in version 3.12.

const PyTypeObject *PyUnstable_ExecutableKinds

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

内部のデバッグやトレースに使う、フレームの実行対象の種類 (executor の型) の配列。

デバッガやプロファイラなどのツールは、これを使ってフレームに関連付けられた実行コンテキストの種類を識別できます (例えば、内部フレームを除外するため)。 各エントリーのインデックスは以下の定数で指定します。

定数	説明
PyUnstable_EXECUTABLE_KIND_SKIP これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	内部フレーム (例えばインライン化されたフレーム) であり、ツールではスキップすべきです。
PyUnstable_EXECUTABLE_KIND_PY_FUNCTION これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	通常の Python 関数に対応するフレーム。
PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	ネイティブコードで定義された関数に対応するフレーム。
PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	クラスインスタンスのメソッドに対応するフレーム。

現在、フレームから実行対象の種類を読み取れるのは、文書化されていない内部 API だけです。

Added in version 3.13.

PyUnstable_EXECUTABLE_KINDS

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

PyUnstable_ExecutableKinds のエントリー数。

Added in version 3.13.