Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-101100: Improve documentation of code object attributes (#112781)

This commit is contained in:
Alex Waygood 2023-12-06 20:15:46 +00:00 committed by GitHub
parent b920d6ceaa
commit e9707d3c3d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 112 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Doc/c-api/function.rst
View File

@ -37,7 +37,7 @@ 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)
@ -45,7 +45,7 @@ There are a few functions specific to Python functions.
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

2
Doc/c-api/import.rst
View File

@ -154,7 +154,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

19
Doc/library/dis.rst
View File

@ -346,8 +346,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.
.. versionchanged:: 3.13
Line numbers can be ``None`` for bytecode that does not map to source lines.
@ -983,13 +984,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>`.
@ -1029,7 +1030,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)
@ -1039,7 +1040,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>`.
@ -1402,7 +1403,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)
@ -1424,7 +1425,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)
@ -1435,7 +1436,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)

4
Doc/library/inspect.rst
View File

@ -1596,8 +1596,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

114
Doc/reference/datamodel.rst
View File

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

2
Doc/whatsnew/2.7.rst
View File

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

3
Doc/whatsnew/3.10.rst
View File

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

5
Doc/whatsnew/3.12.rst
View File

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

5
Doc/whatsnew/3.13.rst
View File

@ -572,7 +572,8 @@ Pending Removal in Python 3.14
* date and datetime adapter, date and timestamp converter:
see the :mod:`sqlite3` documentation for suggested replacement recipes.
* :class:`types.CodeType`: Accessing ``co_lnotab`` was deprecated in :pep:`626`
* :class:`types.CodeType`: Accessing :attr:`~codeobject.co_lnotab` was
deprecated in :pep:`626`
since 3.10 and was planned to be removed in 3.12,
but it only got a proper :exc:`DeprecationWarning` in 3.12.
May be removed in 3.14.
@ -735,7 +736,7 @@ although there is currently no date scheduled for their removal.
* :mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules.
* ``types.CodeType.co_lnotab``: use the ``co_lines`` attribute instead.
* :attr:`~codeobject.co_lnotab`: use the ``co_lines`` attribute instead.
* :class:`typing.Text` (:gh:`92332`).

7
Doc/whatsnew/3.6.rst
View File

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