[3.12] pythongh-101100: Improve documentation of code object attributes (python#112781) (python#112816)

(cherry-picked from commit e9707d3)

Author: AlexWaygood

Doc/c-api/function.rst

@@ -37,15 +37,15 @@ There are a few functions specific to Python functions.
    The function's docstring and name are retrieved from the code object. *__module__*
    is retrieved from *globals*. The argument defaults, annotations and closure are
    set to ``NULL``. *__qualname__* is set to the same value as the code object's
-   ``co_qualname`` field.
+   :attr:`~codeobject.co_qualname` field.
 
 
 .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
 
    As :c:func:`PyFunction_New`, but also allows setting the function object's
    ``__qualname__`` attribute.  *qualname* should be a unicode object or ``NULL``;
    if ``NULL``, the ``__qualname__`` attribute is set to the same value as the
-   code object's ``co_qualname`` field.
+   code object's :attr:`~codeobject.co_qualname` field.
 
    .. versionadded:: 3.3
 

Doc/c-api/import.rst

@@ -138,7 +138,7 @@ Importing Modules
    :class:`~importlib.machinery.SourceFileLoader` otherwise.
 
    The module's :attr:`__file__` attribute will be set to the code object's
-   :attr:`!co_filename`.  If applicable, :attr:`__cached__` will also
+   :attr:`~codeobject.co_filename`.  If applicable, :attr:`__cached__` will also
    be set.
 
    This function will reload the module if it was already imported.  See

Doc/library/dis.rst

@@ -324,8 +324,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Line numbers can be decreasing. Before, they were always increasing.
 
    .. versionchanged:: 3.10
-      The :pep:`626` ``co_lines`` method is used instead of the ``co_firstlineno``
-      and ``co_lnotab`` attributes of the code object.
+      The :pep:`626` ``co_lines`` method is used instead of the
+      :attr:`~codeobject.co_firstlineno` and :attr:`~codeobject.co_lnotab`
+      attributes of the code object.
 
 
 .. function:: findlabels(code)
@@ -889,13 +890,13 @@ iterations of the loop.
 .. opcode:: STORE_NAME (namei)
 
    Implements ``name = STACK.pop()``. *namei* is the index of *name* in the attribute
-   :attr:`!co_names` of the :ref:`code object <code-objects>`.
+   :attr:`~codeobject.co_names` of the :ref:`code object <code-objects>`.
    The compiler tries to use :opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.
 
 
 .. opcode:: DELETE_NAME (namei)
 
-   Implements ``del name``, where *namei* is the index into :attr:`!co_names`
+   Implements ``del name``, where *namei* is the index into :attr:`~codeobject.co_names`
    attribute of the :ref:`code object <code-objects>`.
 
 
@@ -935,7 +936,7 @@ iterations of the loop.
       value = STACK.pop()
       obj.name = value
 
-   where *namei* is the index of name in :attr:`!co_names` of the
+   where *namei* is the index of name in :attr:`~codeobject.co_names` of the
    :ref:`code object <code-objects>`.
 
 .. opcode:: DELETE_ATTR (namei)
@@ -945,7 +946,7 @@ iterations of the loop.
       obj = STACK.pop()
       del obj.name
 
-   where *namei* is the index of name into :attr:`!co_names` of the
+   where *namei* is the index of name into :attr:`~codeobject.co_names` of the
    :ref:`code object <code-objects>`.
 
 
@@ -1308,7 +1309,7 @@ iterations of the loop.
    Pushes a reference to the object the cell contains on the stack.
 
    .. versionchanged:: 3.11
-      ``i`` is no longer offset by the length of ``co_varnames``.
+      ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
 
 
 .. opcode:: LOAD_FROM_DICT_OR_DEREF (i)
@@ -1330,7 +1331,7 @@ iterations of the loop.
    storage.
 
    .. versionchanged:: 3.11
-      ``i`` is no longer offset by the length of ``co_varnames``.
+      ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
 
 
 .. opcode:: DELETE_DEREF (i)
@@ -1341,7 +1342,7 @@ iterations of the loop.
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.11
-      ``i`` is no longer offset by the length of ``co_varnames``.
+      ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
 
 
 .. opcode:: COPY_FREE_VARS (n)

Doc/library/inspect.rst

@@ -1579,8 +1579,8 @@ updated as expected:
 Code Objects Bit Flags
 ----------------------
 
-Python code objects have a ``co_flags`` attribute, which is a bitmap of
-the following flags:
+Python code objects have a :attr:`~codeobject.co_flags` attribute,
+which is a bitmap of the following flags:
 
 .. data:: CO_OPTIMIZED
 

Doc/reference/datamodel.rst

@@ -1077,57 +1077,111 @@ indirectly) to mutable objects.
    single: co_freevars (code object attribute)
    single: co_qualname (code object attribute)
 
-Special read-only attributes: :attr:`co_name` gives the function name;
-:attr:`co_qualname` gives the fully qualified function name;
-:attr:`co_argcount` is the total number of positional arguments
-(including positional-only arguments and arguments with default values);
-:attr:`co_posonlyargcount` is the number of positional-only arguments
-(including arguments with default values); :attr:`co_kwonlyargcount` is
-the number of keyword-only arguments (including arguments with default
-values); :attr:`co_nlocals` is the number of local variables used by the
-function (including arguments); :attr:`co_varnames` is a tuple containing
-the names of the local variables (starting with the argument names);
-:attr:`co_cellvars` is a tuple containing the names of local variables
-that are referenced by nested functions; :attr:`co_freevars` is a tuple
-containing the names of free variables; :attr:`co_code` is a string
-representing the sequence of bytecode instructions; :attr:`co_consts` is
-a tuple containing the literals used by the bytecode; :attr:`co_names` is
-a tuple containing the names used by the bytecode; :attr:`co_filename` is
-the filename from which the code was compiled; :attr:`co_firstlineno` is
-the first line number of the function; :attr:`co_lnotab` is a string
-encoding the mapping from bytecode offsets to line numbers (for details
-see the source code of the interpreter, is deprecated since 3.12
-and may be removed in 3.14); :attr:`co_stacksize` is the
-required stack size; :attr:`co_flags` is an integer encoding a number
-of flags for the interpreter.
+Special read-only attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+
+   * - .. attribute:: codeobject.co_name
+     - The function name
+
+   * - .. attribute:: codeobject.co_qualname
+     - The fully qualified function name
+
+   * - .. attribute:: codeobject.co_argcount
+     - The total number of positional :term:`parameters <parameter>`
+       (including positional-only parameters and parameters with default values)
+       that the function has
+
+   * - .. attribute:: codeobject.co_posonlyargcount
+     - The number of positional-only :term:`parameters <parameter>`
+       (including arguments with default values) that the function has
+
+   * - .. attribute:: codeobject.co_kwonlyargcount
+     - The number of keyword-only :term:`parameters <parameter>`
+       (including arguments with default values) that the function has
+
+   * - .. attribute:: codeobject.co_nlocals
+     - The number of :ref:`local variables <naming>` used by the function
+       (including parameters)
+
+   * - .. attribute:: codeobject.co_varnames
+     - A :class:`tuple` containing the names of the local variables in the
+       function (starting with the parameter names)
+
+   * - .. attribute:: codeobject.co_cellvars
+     - A :class:`tuple` containing the names of :ref:`local variables <naming>`
+       that are referenced by nested functions inside the function
+
+   * - .. attribute:: codeobject.co_freevars
+     - A :class:`tuple` containing the names of free variables in the function
+
+   * - .. attribute:: codeobject.co_code
+     - A string representing the sequence of :term:`bytecode` instructions in
+       the function
+
+   * - .. attribute:: codeobject.co_consts
+     - A :class:`tuple` containing the literals used by the :term:`bytecode` in
+       the function
+
+   * - .. attribute:: codeobject.co_names
+     - A :class:`tuple` containing the names used by the :term:`bytecode` in
+       the function
+
+   * - .. attribute:: codeobject.co_filename
+     - The name of the file from which the code was compiled
+
+   * - .. attribute:: codeobject.co_firstlineno
+     - The line number of the first line of the function
+
+   * - .. attribute:: codeobject.co_lnotab
+     - A string encoding the mapping from :term:`bytecode` offsets to line
+       numbers. For details, see the source code of the interpreter.
+
+       .. deprecated:: 3.12
+          This attribute of code objects is deprecated, and may be removed in
+          Python 3.14.
+
+   * - .. attribute:: codeobject.co_stacksize
+     - The required stack size of the code object
+
+   * - .. attribute:: codeobject.co_flags
+     - An :class:`integer <int>` encoding a number of flags for the
+       interpreter.
 
 .. index:: pair: object; generator
 
-The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
+The following flag bits are defined for :attr:`~codeobject.co_flags`:
+bit ``0x04`` is set if
 the function uses the ``*arguments`` syntax to accept an arbitrary number of
 positional arguments; bit ``0x08`` is set if the function uses the
 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
-if the function is a generator.
+if the function is a generator. See :ref:`inspect-module-co-flags` for details
+on the semantics of each flags that might be present.
 
 Future feature declarations (``from __future__ import division``) also use bits
-in :attr:`co_flags` to indicate whether a code object was compiled with a
+in :attr:`~codeobject.co_flags` to indicate whether a code object was compiled with a
 particular feature enabled: bit ``0x2000`` is set if the function was compiled
 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
 versions of Python.
 
-Other bits in :attr:`co_flags` are reserved for internal use.
+Other bits in :attr:`~codeobject.co_flags` are reserved for internal use.
 
 .. index:: single: documentation string
 
-If a code object represents a function, the first item in :attr:`co_consts` is
+If a code object represents a function, the first item in
+:attr:`~codeobject.co_consts` is
 the documentation string of the function, or ``None`` if undefined.
 
+The :meth:`!co_positions` method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. method:: codeobject.co_positions()
 
-   Returns an iterable over the source code positions of each bytecode
+   Returns an iterable over the source code positions of each :term:`bytecode`
    instruction in the code object.
 
-   The iterator returns tuples containing the ``(start_line, end_line,
+   The iterator returns :class:`tuple`\s containing the ``(start_line, end_line,
    start_column, end_column)``. The *i-th* tuple corresponds to the
    position of the source code that compiled to the *i-th* instruction.
    Column information is 0-indexed utf-8 byte offsets on the given source

Doc/whatsnew/2.7.rst

@@ -2405,7 +2405,7 @@ Other Changes and Fixes
   :issue:`5464`.)
 
 * When importing a module from a :file:`.pyc` or :file:`.pyo` file
-  with an existing :file:`.py` counterpart, the :attr:`co_filename`
+  with an existing :file:`.py` counterpart, the :attr:`~codeobject.co_filename`
   attributes of the resulting code objects are overwritten when the
   original filename is obsolete.  This can happen if the file has been
   renamed, moved, or is accessed through different paths.  (Patch by

Doc/whatsnew/3.10.rst

@@ -402,7 +402,8 @@ Tracing events, with the correct line number, are generated for all lines of cod
 The :attr:`~frame.f_lineno` attribute of frame objects will always contain the
 expected line number.
 
-The ``co_lnotab`` attribute of code objects is deprecated and will be removed in 3.12.
+The :attr:`~codeobject.co_lnotab` attribute of code objects is deprecated and
+will be removed in 3.12.
 Code that needs to convert from offset to line number should use the new ``co_lines()`` method instead.
 
 PEP 634: Structural Pattern Matching

Doc/whatsnew/3.12.rst

@@ -1323,7 +1323,8 @@ Deprecated
   ``int``, convert to int explicitly: ``~int(x)``. (Contributed by Tim Hoffmann
   in :gh:`103487`.)
 
-* Accessing ``co_lnotab`` on code objects was deprecated in Python 3.10 via :pep:`626`,
+* Accessing :attr:`~codeobject.co_lnotab` on code objects was deprecated in
+  Python 3.10 via :pep:`626`,
   but it only got a proper :exc:`DeprecationWarning` in 3.12,
   therefore it will be removed in 3.14.
   (Contributed by Nikita Sobolev in :gh:`101866`.)
@@ -1430,7 +1431,7 @@ and will be removed in Python 3.14.
 
 * The ``__package__`` and ``__cached__`` attributes on module objects.
 
-* The ``co_lnotab`` attribute of code objects.
+* The :attr:`~codeobject.co_lnotab` attribute of code objects.
 
 Pending Removal in Python 3.15
 ------------------------------

Doc/whatsnew/3.6.rst

@@ -2160,14 +2160,15 @@ Changes in the Python API
 * :c:func:`PyErr_SetImportError` now sets :exc:`TypeError` when its **msg**
   argument is not set. Previously only ``NULL`` was returned.
 
-* The format of the ``co_lnotab`` attribute of code objects changed to support
+* The format of the :attr:`~codeobject.co_lnotab` attribute of code objects
+  changed to support
   a negative line number delta. By default, Python does not emit bytecode with
   a negative line number delta. Functions using :attr:`frame.f_lineno`,
   ``PyFrame_GetLineNumber()`` or ``PyCode_Addr2Line()`` are not affected.
-  Functions directly decoding ``co_lnotab`` should be updated to use a signed
+  Functions directly decoding :attr:`!co_lnotab` should be updated to use a signed
   8-bit integer type for the line number delta, but this is only required to
   support applications using a negative line number delta. See
-  ``Objects/lnotab_notes.txt`` for the ``co_lnotab`` format and how to decode
+  ``Objects/lnotab_notes.txt`` for the :attr:`!co_lnotab` format and how to decode
   it, and see the :pep:`511` for the rationale.
 
 * The functions in the :mod:`compileall` module now return booleans instead