Frame objects
*************

type PyFrameObject
    * 為 穩定 ABI 的一部分 （做為一個不透明結構 (opaque struct)）.*

   用來描述 frame 物件的 C 結構。

   在這個結構中沒有公開的成員。

   在 3.11 版的變更: The members of this structure were removed from
   the public C API. Refer to the What's New entry for details.

The "PyEval_GetFrame()" and "PyThreadState_GetFrame()" functions can
be used to get a frame object.

另請參閱 Reflection。

PyTypeObject PyFrame_Type

   The type of frame objects. It is the same object as
   "types.FrameType" in the Python layer.

   在 3.11 版的變更: Previously, this type was only available after
   including "<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)

   Return non-zero if *obj* is a frame object.

   在 3.11 版的變更: Previously, this function was only available
   after including "<frameobject.h>".

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)
    *回傳值：新的參照。*

   Get the *frame* next outer frame.

   回傳一個 *strong reference*，如果 *frame* 沒有外層 frame 則回傳
   "NULL"。此函式不會引發例外。

   在 3.9 版被加入.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)
    *回傳值：新的參照。*

   取得 *frame* 的 "f_builtins" 屬性。

   回傳 *strong reference*。結果不能為 "NULL"。

   在 3.11 版被加入.

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)
    *回傳值：新的參照。** 為 穩定 ABI 的一部分 自 3.10 版本開始.*

   Get the *frame* code.

   回傳 *strong reference*。

   The result (frame code) cannot be "NULL".

   在 3.9 版被加入.

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)
    *回傳值：新的參照。*

   Get the generator, coroutine, or async generator that owns this
   frame, or "NULL" if this frame is not owned by a generator. Does
   not raise an exception, even if the return value is "NULL".

   回傳 *strong reference* 或 "NULL"。

   在 3.11 版被加入.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)
    *回傳值：新的參照。*

   取得 *frame* 的 "f_globals" 屬性。

   回傳 *strong reference*。結果不能為 "NULL"。

   在 3.11 版被加入.

int PyFrame_GetLasti(PyFrameObject *frame)

   取得 *frame* 的 "f_lasti" 屬性。

   如果 "frame.f_lasti" 是 "None" 則回傳 -1。

   在 3.11 版被加入.

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
    *回傳值：新的參照。*

   取得 *frame* 的變數 *name*。

   * 在成功時回傳變數值的 *strong reference*。

   * 如果變數不存在，則引發 "NameError" 並回傳 "NULL"。

   * 在錯誤時引發例外並回傳 "NULL"。

   *name* 的型別必須是 "str"。

   在 3.12 版被加入.

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)
    *回傳值：新的參照。*

   Similar to "PyFrame_GetVar()", but the variable name is a C string
   encoded in UTF-8.

   在 3.12 版被加入.

PyObject *PyFrame_GetLocals(PyFrameObject *frame)
    *回傳值：新的參照。*

   Get the *frame*'s "f_locals" attribute. If the frame refers to an
   *optimized scope*, this returns a write-through proxy object that
   allows modifying the locals. In all other cases (classes, modules,
   "exec()", "eval()") it returns the mapping representing the frame
   locals directly (as described for "locals()").

   回傳 *strong reference*。

   在 3.11 版被加入.

   在 3.13 版的變更: As part of **PEP 667**, return an instance of
   "PyFrameLocalsProxy_Type".

int PyFrame_GetLineNumber(PyFrameObject *frame)
    * 為 穩定 ABI 的一部分 自 3.10 版本開始.*

   Return the line number that *frame* is currently executing.


Frame locals proxies
====================

在 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

   The type of frame "locals()" proxy objects.

int PyFrameLocalsProxy_Check(PyObject *obj)

   Return non-zero if *obj* is a frame "locals()" proxy.


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
===============

Unless using **PEP 523**, you will not need this.

struct _PyInterpreterFrame

   The interpreter's internal frame representation.

   在 3.11 版被加入.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

   *這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。*

      Return a *strong reference* to the code object for the frame.

   在 3.12 版被加入.

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

   *這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。*

   Return the byte offset into the last executed instruction.

   在 3.12 版被加入.

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);

   *這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。*

   Return the currently executing line number, or -1 if there is no
   line number.

   在 3.12 版被加入.
