フレーム (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  *これは    | 通常の Python 関数に対応するフレーム。             |
   | Unstable APIです。マイナーリリースで予告なく変更さ |                                                    |
   | れるこ とがあります。*                             |                                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | 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.
