8000 [3.12] gh-101100: Properly document frame object attributes (GH-11273… · python/cpython@ef92e9e · GitHub
[go: up one dir, main page]
Skip to content 8000

Commit ef92e9e

Browse files
miss-islingtonAlexWaygood
miss-islington
and
AlexWaygood
authored
[3.12] gh-101100: Properly document frame object attributes (GH-112735) (#112772)
gh-101100: Properly document frame object attributes (GH-112735) (cherry picked from commit d109f63) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
1 parent e63bb9c commit ef92e9e

File tree

12 files changed

+88
-49
lines changed
  • 3.7.rst

    • 12 files changed

    +88
    -49
    lines changed

    ‎Doc/c-api/frame.rst

    Lines changed: 4 additions & 4 deletions
    Original file line numberDiff line numberDiff line change
    @@ -50,7 +50,7 @@ See also :ref:`Reflection <reflection>`.
    5050
    5151
    .. c:function:: PyObject* PyFrame_GetBuiltins(PyFrameObject *frame)
    5252
    53-
    Get the *frame*'s ``f_builtins`` attribute.
    53+
    Get the *frame*'s :attr:`~frame.f_builtins` attribute.
    5454
    5555
    Return a :term:`strong reference`. The result cannot be ``NULL``.
    5656
    @@ -81,7 +81,7 @@ See also :ref:`Reflection <reflection>`.
    8181
    8282
    .. c:function:: PyObject* PyFrame_GetGlobals(PyFrameObject *frame)
    8383
    84-
    Get the *frame*'s ``f_globals`` attribute.
    84+
    Get the *frame*'s :attr:`~frame.f_globals` attribute.
    8585
    8686
    Return a :term:`strong reference`. The result cannot be ``NULL``.
    8787
    @@ -90,7 +90,7 @@ See also :ref:`Reflection <reflection>`.
    9090
    9191
    .. c:function:: int PyFrame_GetLasti(PyFrameObject *frame)
    9292
    93-
    Get the *frame*'s ``f_lasti`` attribute.
    93+
    Get the *frame*'s :attr:`~frame.f_lasti` attribute.
    9494
    9595
    Returns -1 if ``frame.f_lasti`` is ``None``.
    9696
    @@ -120,7 +120,7 @@ See also :ref:`Reflection <reflection>`.
    120120
    121121
    .. c:function:: PyObject* PyFrame_GetLocals(PyFrameObject *frame)
    122122
    123-
    Get the *frame*'s ``f_locals`` attribute (:class:`dict`).
    123+
    Get the *frame*'s :attr:`~frame.f_locals` attribute (:class:`dict`).
    124124
    125125
    Return a :term:`strong reference`.
    126126

    ‎Doc/c-api/init.rst

    Lines changed: 3 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1909,7 +1909,8 @@ Python-level trace functions in previous versions.
    19091909
    19101910
    The value passed as the *what* parameter to a :c:type:`Py_tracefunc` function
    19111911
    (but not a profiling function) when a line-number event is being reported.
    1912-
    It may be disabled for a frame by setting :attr:`f_trace_lines` to *0* on that frame.
    1912+
    It may be disabled for a frame by setting :attr:`~frame.f_trace_lines` to
    1913+
    *0* on that frame.
    19131914
    19141915
    19151916
    .. c:var:: int PyTrace_RETURN
    @@ -1941,7 +1942,7 @@ Python-level trace functions in previous versions.
    19411942
    The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but not
    19421943
    profiling functions) when a new opcode is about to be executed. This event is
    19431944
    not emitted by default: it must be explicitly requested by setting
    1944-
    :attr:`f_trace_opcodes` to *1* on the frame.
    1945+
    :attr:`~frame.f_trace_opcodes` to *1* on the frame.
    19451946
    19461947
    19471948
    .. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

    ‎Doc/library/dis.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -771,8 +771,8 @@ iterations of the loop.
    771771
    .. opcode:: RERAISE
    772772

    773773
    Re-raises the exception currently on top of the stack. If oparg is non-zero,
    774-
    pops an additional value from the stack which is used to set ``f_lasti``
    775-
    of the current frame.
    774+
    pops an additional value from the stack which is used to set
    775+
    :attr:`~frame.f_lasti` of the current frame.
    776776

    777777
    .. versionadded:: 3.9
    778778

    ‎Doc/library/inspect.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1588,8 +1588,8 @@ the following flags:
    15881588

    15891589
    .. data:: CO_NEWLOCALS
    15901590

    1591-
    If set, a new dict will be created for the frame's ``f_locals`` when
    1592-
    the code object is executed.
    1591+
    If set, a new dict will be created for the frame's :attr:`~frame.f_locals`
    1592+
    when the code object is executed.
    15931593

    15941594
    .. data:: CO_VARARGS
    15951595

    ‎Doc/library/sys.rst

    Lines changed: 5 additions & 4 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1586,7 +1586,8 @@ always available.
    15861586
    :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
    15871587
    works.
    15881588
    Per-line events may be disabled for a frame by setting
    1589-
    :attr:`!f_trace_lines` to :const:`False` on that :ref:`frame <frame-objects>`.
    1589+
    :attr:`~frame.f_trace_lines` to :const:`False` on that
    1590+
    :ref:`frame <frame-objects>`.
    15901591

    15911592
    ``'return'``
    15921593
    A function (or other code block) is about to return. The local trace
    @@ -1604,7 +1605,7 @@ always available.
    16041605
    opcode details). The local trace function is called; *arg* is
    16051606
    ``None``; the return value specifies the new local trace function.
    16061607
    Per-opcode events are not emitted by default: they must be explicitly
    1607-
    requested by setting :attr:`!f_trace_opcodes` to :const:`True` on the
    1608+
    requested by setting :attr:`~frame.f_trace_opcodes` to :const:`True` on the
    16081609
    :ref:`frame <frame-objects>`.
    16091610

    16101611
    Note that as an exception is propagated down the chain of callers, an
    @@ -1634,8 +1635,8 @@ always available.
    16341635

    16351636
    .. versionchanged:: 3.7
    16361637

    1637-
    ``'opcode'`` event type added; :attr:`!f_trace_lines` and
    1638-
    :attr:`!f_trace_opcodes` attributes added to frames
    1638+
    ``'opcode'`` event type added; :attr:`~frame.f_trace_lines` and
    1639+
    :attr:`~frame.f_trace_opcodes` attributes added to frames
    16391640

    16401641
    .. function:: set_asyncgen_hooks(firstiter, finalizer)
    16411642

    ‎Doc/library/types.rst

    Lines changed: 2 additions & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -386,7 +386,8 @@ Standard names are defined for the following types:
    386386
    .. data:: GetSetDescriptorType
    387387

    388388
    The type of objects defined in extension modules with ``PyGetSetDef``, such
    389-
    as ``FrameType.f_locals`` or ``array.array.typecode``. This type is used as
    389+
    as :attr:`FrameType.f_locals <frame.f_locals>` or ``array.array.typecode``.
    390+
    This type is used as
    390391
    descriptor for object attributes; it has the same purpose as the
    391392
    :class:`property` type, but for classes defined in extension modules.
    392393

    ‎Doc/reference/datamodel.rst

    Lines changed: 59 additions & 25 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1174,47 +1174,81 @@ Frame objects represent execution frames. They may occur in traceback objects
    11741174
    single: f_lasti (frame attribute)
    11751175
    single: f_builtins (frame attribute)
    11761176

    1177-
    Special read-only attributes: :attr:`f_back` is to the previous stack frame
    1178-
    (towards the caller), or ``None`` if this is the bottom stack frame;
    1179-
    :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
    1180-
    is the dictionary used to look up local variables; :attr:`f_globals` is used for
    1181-
    global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
    1182-
    :attr:`f_lasti` gives the precise instruction (this is an index into the
    1183-
    bytecode string of the code object).
    1177+
    Special read-only attributes
    1178+
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    11841179

    1185-
    Accessing ``f_code`` raises an :ref:`auditing event <auditing>`
    1186-
    ``object.__getattr__`` with arguments ``obj`` and ``"f_code"``.
    1180+
    .. list-table::
    1181+
    1182+
    * - .. attribute:: frame.f_back
    1183+
    - Points to the previous stack frame (towards the caller),
    1184+
    or ``None`` if this is the bottom stack frame
    1185+
    1186+
    * - .. attribute:: frame.f_code
    1187+
    - The :ref:`code object <code-objects>` being executed in this frame.
    1188+
    Accessing this attribute raises an :ref:`auditing event <auditing>`
    1189+
    ``object.__getattr__`` with arguments ``obj`` and ``"f_code"``.
    1190+
    1191+
    * - .. attribute:: frame.f_locals
    1192+
    - The dictionary used by the frame to look up
    1193+
    :ref:`local variables <naming>`
    1194+
    1195+
    * - .. attribute:: frame.f_globals
    1196+
    - The dictionary used by the frame to look up
    1197+
    :ref:`global variables <naming>`
    1198+
    1199+
    * - .. attribute:: frame.f_builtins
    1200+
    - The dictionary used by the frame to look up
    1201+
    :ref:`built-in (intrinsic) names <naming>`
    1202+
    1203+
    * - .. attribute:: frame.f_lasti
    1204+
    - The "precise instruction" of the frame object
    1205+
    (this is an index into the :term:`bytecode` string of the
    1206+
    :ref:`code object <code-objects>`)
    11871207

    11881208
    .. index::
    11891209
    single: f_trace (frame attribute)
    11901210
    single: f_trace_lines (frame attribute)
    11911211
    single: f_trace_opcodes (frame attribute)
    11921212
    single: f_lineno (frame attribute)
    11931213

    1194-
    Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
    1195-
    called for various events during code execution (this is used by the debugger).
    1196-
    Normally an event is triggered for each new source line - this can be
    1197-
    disabled by setting :attr:`f_trace_lines` to :const:`False`.
    1214+
    Special writable attributes
    1215+
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1216+
    1217+
    .. list-table::
    1218+
    1219+
    * - .. attribute:: frame.f_trace
    1220+
    - If not ``None``, this is a function called for various events during
    1221+
    code execution (this is used by debuggers). Normally an event is
    1222+
    triggered for each new source line (see :attr:`~frame.f_trace_lines`).
    1223+
    1224+
    * - .. attribute:: frame.f_trace_lines
    1225+
    - Set this attribute to :const:`False` to disable triggering a tracing
    1226+
    event for each source line.
    1227+
    1228+
    * - .. attribute:: frame.f_trace_opcodes
    1229+
    - Set this attribute to :const:`True` to allow per-opcode events to be
    1230+
    requested. Note that this may lead to
    1231+
    undefined interpreter behaviour if exceptions raised by the trace
    1232+
    function escape to the function being traced.
    11981233

    1199-
    Implementations *may* allow per-opcode events to be requested by setting
    1200-
    :attr:`f_trace_opcodes` to :const:`True`. Note that this may lead to
    1201-
    undefined interpreter behaviour if exceptions raised by the trace
    1202-
    function escape to the function being traced.
    1234+
    * - .. attribute:: frame.f_lineno
    1235+
    - The current line number of the frame -- writing to this
    1236+
    from within a trace function jumps to the given line (only for the bottom-most
    1237+
    frame). A debugger can implement a Jump command (aka Set Next Statement)
    1238+
    by writing to this attribute.
    12031239

    1204-
    :attr:`f_lineno` is the current line number of the frame --- writing to this
    1205-
    from within a trace function jumps to the given line (only for the bottom-most
    1206-
    frame). A debugger can implement a Jump command (aka Set Next Statement)
    1207-
    by writing to f_lineno.
    1240+
    Frame object methods
    1241+
    ~~~~~~~~~~~~~~~~~~~~
    12081242

    12091243
    Frame objects support one method:
    12101244

    12111245
    .. method:: frame.clear()
    12121246

    1213-
    This method clears all references to local variables held by the
    1214-
    frame. Also, if the frame belonged to a generator, the generator
    1247+
    This method clears all references to :ref:`local variables <naming>` held by the
    1248+
    frame. Also, if the frame belonged to a :term:`generator`, the generator
    12151249
    is finalized. This helps break reference cycles involving frame
    1216-
    objects (for example when catching an exception and storing its
    1217-
    traceback for later use).
    1250+
    objects (for example when catching an :ref:`exception <bltin-exceptions>`
    1251+
    and storing its :ref:`traceback <traceback-objects>` for later use).
    12181252

    12191253
    :exc:`RuntimeError` is raised if the frame is currently executing.
    12201254

    ‎Doc/whatsnew/2.3.rst

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1998,13 +1998,13 @@ Some of the more notable changes are:
    19981998
    It would be difficult to detect any resulting difference from Python code, apart
    19991999
    from a slight speed up when Python is run without :option:`-O`.
    20002000

    2001-
    C extensions that access the :attr:`f_lineno` field of frame objects should
    2001+
    C extensions that access the :attr:`~frame.f_lineno` field of frame objects should
    20022002
    instead call ``PyCode_Addr2Line(f->f_code, f->f_lasti)``. This will have the
    20032003
    added effect of making the code work as desired under "python -O" in earlier
    20042004
    versions of Python.
    20052005

    20062006
    A nifty new feature is that trace functions can now assign to the
    2007-
    :attr:`f_lineno` attribute of frame objects, changing the line that will be
    2007+
    :attr:`~frame.f_lineno` attribute of frame objects, changing the line that will be
    20082008
    executed next. A ``jump`` command has been added to the :mod:`pdb` debugger
    20092009
    taking advantage of this new feature. (Implemented by Richie Hindle.)
    20102010

    ‎Doc/whatsnew/3.10.rst

    Lines changed: 4 additions & 3 deletions
    Original file line numberDiff line numberDiff line change
    @@ -399,7 +399,8 @@ PEP 626: Precise line numbers for debugging and other tools
    399399
    PEP 626 brings more precise and reliable line numbers for debugging, profiling and coverage tools.
    400400
    Tracing events, with the correct line number, are generated for all lines of code executed and only for lines of code that are executed.
    401401
    402-
    The ``f_lineno`` attribute of frame objects will always contain the expected line number.
    402+
    The :attr:`~frame.f_lineno` attribute of frame objects will always contain the
    403+
    expected line number.
    403404
    404405
    The ``co_lnotab`` attribute of code objects is deprecated and will be removed in 3.12.
    405406
    Code that needs to convert from offset to line number should use the new ``co_lines()`` method instead.
    @@ -1959,11 +1960,11 @@ Changes in the C API
    19591960
    source_buf = PyBytes_AsString(source_bytes_object);
    19601961
    code = Py_CompileString(source_buf, filename, Py_file_input);
    19611962
    1962-
    * For ``FrameObject`` objects, the ``f_lasti`` member now represents a wordcode
    1963+
    * For ``FrameObject`` objects, the :attr:`~frame.f_lasti` member now represents a wordcode
    19631964
    offset instead of a simple offset into the bytecode string. This means that this
    19641965
    number needs to be multiplied by 2 to be used with APIs that expect a byte offset
    19651966
    instead (like :c:func:`PyCode_Addr2Line` for example). Notice as well that the
    1966-
    ``f_lasti`` member of ``FrameObject`` objects is not considered stable: please
    1967+
    :attr:`!f_lasti` member of ``FrameObject`` objects is not considered stable: please
    19671968
    use :c:func:`PyFrame_GetLineNumber` instead.
    19681969
    19691970
    CPython bytecode changes

    ‎Doc/whatsnew/3.11.rst

    Lines changed: 3 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -2458,11 +2458,12 @@ Porting to Python 3.11
    24582458
    * ``f_valuestack``: removed.
    24592459

    24602460
    The Python frame object is now created lazily. A side effect is that the
    2461-
    ``f_back`` member must not be accessed directly, since its value is now also
    2461+
    :attr:`~frame.f_back` member must not be accessed directly,
    2462+
    since its value is now also
    24622463
    computed lazily. The :c:func:`PyFrame_GetBack` function must be called
    24632464
    instead.
    24642465

    2465-
    Debuggers that accessed the ``f_locals`` directly *must* call
    2466+
    Debuggers that accessed the :attr:`~frame.f_locals` directly *must* call
    24662467
    :c:func:`PyFrame_GetLocals` instead. They no longer need to call
    24672468
    :c:func:`PyFrame_FastToLocalsWithError` or :c:func:`PyFrame_LocalsToFast`,
    24682469
    in fact they should not call those functions. The necessary updating of the

    ‎Doc/whatsnew/3.6.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -2162,7 +2162,7 @@ Changes in the Python API
    2162< B925 /td>2162

    21632163
    * The format of the ``co_lnotab`` attribute of code objects changed to support
    21642164
    a negative line number delta. By default, Python does not emit bytecode with
    2165-
    a negative line number delta. Functions using ``frame.f_lineno``,
    2165+
    a negative line number delta. Functions using :attr:`frame.f_lineno`,
    21662166
    ``PyFrame_GetLineNumber()`` or ``PyCode_Addr2Line()`` are not affected.
    21672167
    Functions directly decoding ``co_lnotab`` should be updated to use a signed
    21682168
    8-bit integer type for the line number delta, but this is only required to

    ‎Doc/whatsnew/3.7.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -1891,7 +1891,7 @@ Other CPython Implementation Changes
    18911891

    18921892
    * Trace hooks may now opt out of receiving the ``line`` and opt into receiving
    18931893
    the ``opcode`` events from the interpreter by setting the corresponding new
    1894-
    ``f_trace_lines`` and ``f_trace_opcodes`` attributes on the
    1894+
    :attr:`~frame.f_trace_lines` and :attr:`~frame.f_trace_opcodes` attributes on the
    18951895
    frame being traced. (Contributed by Nick Coghlan in :issue:`31344`.)
    18961896

    18971897
    * Fixed some consistency problems with namespace package module attributes.

    0 commit comments

    Comments
     (0)
    0