Frame objects

type PyFrameObject

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

フレームオブジェクトを記述する際に用いられる、オブジェクトを表す 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)

Create a new frame object. This function returns a strong reference to the new frame object on success, and returns NULL with an exception set on failure.

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 が現在実行している行番号を返します。

Frame locals proxies

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() プロキシの場合に非ゼロを返します。

Legacy local variable APIs

These APIs are soft deprecated. As of Python 3.13, they do nothing. They exist solely for backwards compatibility.

void PyFrame_LocalsToFast(PyFrameObject *f, int clear)

Prior to Python 3.13, this function would copy the f_locals attribute of f to the internal "fast" array of local variables, allowing changes in frame objects to be visible to the interpreter. If clear was true, this function would process variables that were unset in the locals dictionary.

Soft deprecated since version 3.13: This function now does nothing.

void PyFrame_FastToLocals(PyFrameObject *f)

Prior to Python 3.13, this function would copy the internal "fast" array of local variables (which is used by the interpreter) to the f_locals attribute of f, allowing changes in local variables to be visible to frame objects.

Soft deprecated since version 3.13: This function now does nothing.

int PyFrame_FastToLocalsWithError(PyFrameObject *f)

Prior to Python 3.13, this function was similar to PyFrame_FastToLocals(), but would return 0 on success, and -1 with an exception set on failure.

Soft deprecated since version 3.13: This function now does nothing.

参考

PEP 667

Internal frames

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です。マイナーリリースで予告なく変更されることがあります。

An array of executable kinds (executor types) for frames, used for internal debugging and tracing.

Tools like debuggers and profilers can use this to identify the type of execution context associated with a frame (such as to filter out internal frames). The entries are indexed by the following constants:

Constant	Description
PyUnstable_EXECUTABLE_KIND_SKIP これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	The frame is internal (For example: inlined) and should be skipped by tools.
PyUnstable_EXECUTABLE_KIND_PY_FUNCTION これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	The frame corresponds to a standard Python function.
PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	The frame corresponds to a function defined in native code.
PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。	The frame corresponds to a method on a class instance.

Note that reading the executable kind from a frame is currently only possible with undocumented internal APIs.

Added in version 3.13.

PyUnstable_EXECUTABLE_KINDS

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

The number of entries in PyUnstable_ExecutableKinds.

Added in version 3.13.