Frame 物件
**********

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 版被加入.

const PyTypeObject *PyUnstable_ExecutableKinds

   *這是 不穩定 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  *這是 不穩定 API  | The frame is internal (For example: inlined) and   |
   | ，它可能在小版本發布中沒有任何警告地被變更。*      | should be skipped by tools.                        |
   +----------------------------------------------------+----------------------------------------------------+
   | PyUnstable_EXECUTABLE_KIND_PY_FUNCTION  *這是 不穩 | The frame corresponds to a standard Python         |
   | 定 API，它可能在小版本發布中沒有任何警告地被變更。 | function.                                          |
   | *                                                  |                                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION  *這是 | The frame corresponds to a function defined in     |
   | 不穩定 API，它可能在小版本發布中沒有任何警告地被變 | native code.                                       |
   | 更。*                                              |                                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR  *這  | The frame corresponds to a method on a class       |
   | 是 不穩定 API，它可能在小版本發布中沒有任何警告地  | instance.                                          |
   | 被變更。*                                          |                                                    |
   +----------------------------------------------------+----------------------------------------------------+

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

   在 3.13 版被加入.

PyUnstable_EXECUTABLE_KINDS

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

   The number of entries in "PyUnstable_ExecutableKinds".

   在 3.13 版被加入.
