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

type PyFrameObject
    * Część ograniczonego API (jako nieprzezroczysta struktura).*

   The C structure of the objects used to describe frame objects.

   There are no public members in this structure.

   Zmienione w wersji 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.

See also Reflection.

PyTypeObject PyFrame_Type

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

   Zmienione w wersji 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.

   Zmienione w wersji 3.11: Previously, this function was only
   available after including "<frameobject.h>".

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)
    *Wartość zwracana: nowa referencja.*

   Get the *frame* next outer frame.

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

    Dodane w wersji 3.9.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)
    *Wartość zwracana: nowa referencja.*

   Get the *frame*'s "f_builtins" attribute.

   Return a *strong reference*. The result cannot be "NULL".

    Dodane w wersji 3.11.

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)
    *Wartość zwracana: nowa referencja.** Część stabilnego ABI od
   wersji 3.10.*

   Get the *frame* code.

   Return a *strong reference*.

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

    Dodane w wersji 3.9.

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)
    *Wartość zwracana: nowa referencja.*

   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".

   Return a *strong reference*, or "NULL".

    Dodane w wersji 3.11.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)
    *Wartość zwracana: nowa referencja.*

   Get the *frame*'s "f_globals" attribute.

   Return a *strong reference*. The result cannot be "NULL".

    Dodane w wersji 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

   Get the *frame*'s "f_lasti" attribute.

   Returns -1 if "frame.f_lasti" is "None".

    Dodane w wersji 3.11.

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
    *Wartość zwracana: nowa referencja.*

   Get the variable *name* of *frame*.

   * Return a *strong reference* to the variable value on success.

   * Raise "NameError" and return "NULL" if the variable does not
     exist.

   * Raise an exception and return "NULL" on error.

   *name* type must be a "str".

    Dodane w wersji 3.12.

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)
    *Wartość zwracana: nowa referencja.*

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

    Dodane w wersji 3.12.

PyObject *PyFrame_GetLocals(PyFrameObject *frame)
    *Wartość zwracana: nowa referencja.*

   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()").

   Return a *strong reference*.

    Dodane w wersji 3.11.

   Zmienione w wersji 3.13: As part of **PEP 667**, return an instance
   of "PyFrameLocalsProxy_Type".

int PyFrame_GetLineNumber(PyFrameObject *frame)
    * Część stabilnego ABI od wersji 3.10.*

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


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

 Dodane w wersji 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.

See **PEP 667** for more information.

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.

Zobacz także: **PEP 667**


Internal frames
===============

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

struct _PyInterpreterFrame

   The interpreter's internal frame representation.

    Dodane w wersji 3.11.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);

   *To jest niestabilne API. Może ulec zmianie bez ostrzeżenia w
   wydaniach minor.*

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

    Dodane w wersji 3.12.

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);

   *To jest niestabilne API. Może ulec zmianie bez ostrzeżenia w
   wydaniach minor.*

   Return the byte offset into the last executed instruction.

    Dodane w wersji 3.12.

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);

   *To jest niestabilne API. Może ulec zmianie bez ostrzeżenia w
   wydaniach minor.*

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

    Dodane w wersji 3.12.

const PyTypeObject *PyUnstable_ExecutableKinds

   *To jest niestabilne API. Może ulec zmianie bez ostrzeżenia w
   wydaniach minor.*

   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  *To jest          | The frame is internal (For example: inlined) and   |
   | niestabilne API. Może ulec zmianie bez ostrzeżenia | should be skipped by tools.                        |
   | w wydaniach minor.*                                |                                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | PyUnstable_EXECUTABLE_KIND_PY_FUNCTION  *To jest   | The frame corresponds to a standard Python         |
   | niestabilne API. Może ulec zmianie bez ostrzeżenia | function.                                          |
   | w wydaniach minor.*                                |                                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION  *To   | The frame corresponds to a function defined in     |
   | jest niestabilne API. Może ulec zmianie bez        | native code.                                       |
   | ostrzeżenia w wydaniach minor.*                    |                                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR  *To  | The frame corresponds to a method on a class       |
   | jest niestabilne API. Może ulec zmianie bez        | instance.                                          |
   | ostrzeżenia w wydaniach minor.*                    |                                                    |
   +----------------------------------------------------+----------------------------------------------------+

   However, Python's C API lacks a function to read the executable
   kind from a frame. Instead, use this recipe:

      int
      get_executable_kind(PyFrameObject *frame)
      {
         _PyInterpreterFrame *f = frame->f_frame;
         PyObject *exec = PyStackRef_AsPyObjectBorrow(f->f_executable);

         if (PyCode_Check(exec)) {
            return PyUnstable_EXECUTABLE_KIND_PY_FUNCTION;
         }
         if (PyMethod_Check(exec)) {
            return PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION;
         }
         if (Py_IS_TYPE(exec, &PyMethodDescr_Type)) {
            return PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR;
         }

         return PyUnstable_EXECUTABLE_KIND_SKIP;
      }

    Dodane w wersji 3.13.

PyUnstable_EXECUTABLE_KINDS

   *To jest niestabilne API. Może ulec zmianie bez ostrzeżenia w
   wydaniach minor.*

   The number of entries in "PyUnstable_ExecutableKinds".

    Dodane w wersji 3.13.
