mirror of
https://github.com/python/cpython.git
synced 2024-11-26 19:34:19 +08:00
Document the co_lines
method on code objects (#113682)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
This commit is contained in:
parent
178919cf21
commit
f1f8392432
@ -342,17 +342,18 @@ operation is being performed, so the intermediate analysis object isn't useful:
|
||||
|
||||
.. function:: findlinestarts(code)
|
||||
|
||||
This generator function uses the ``co_lines`` method
|
||||
of the code object *code* to find the offsets which are starts of
|
||||
This generator function uses the :meth:`~codeobject.co_lines` method
|
||||
of the :ref:`code object <code-objects>` *code* to find the offsets which
|
||||
are starts of
|
||||
lines in the source code. They are generated as ``(offset, lineno)`` pairs.
|
||||
|
||||
.. versionchanged:: 3.6
|
||||
Line numbers can be decreasing. Before, they were always increasing.
|
||||
|
||||
.. versionchanged:: 3.10
|
||||
The :pep:`626` ``co_lines`` method is used instead of the
|
||||
The :pep:`626` :meth:`~codeobject.co_lines` method is used instead of the
|
||||
:attr:`~codeobject.co_firstlineno` and :attr:`~codeobject.co_lnotab`
|
||||
attributes of the code object.
|
||||
attributes of the :ref:`code object <code-objects>`.
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Line numbers can be ``None`` for bytecode that does not map to source lines.
|
||||
|
@ -1219,8 +1219,8 @@ 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Methods on code objects
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. method:: codeobject.co_positions()
|
||||
|
||||
@ -1255,6 +1255,41 @@ The :meth:`!co_positions` method
|
||||
:option:`-X` ``no_debug_ranges`` command line flag or the :envvar:`PYTHONNODEBUGRANGES`
|
||||
environment variable can be used.
|
||||
|
||||
.. method:: codeobject.co_lines()
|
||||
|
||||
Returns an iterator that yields information about successive ranges of
|
||||
:term:`bytecode`\s. Each item yielded is a ``(start, end, lineno)``
|
||||
:class:`tuple`:
|
||||
|
||||
* ``start`` (an :class:`int`) represents the offset (inclusive) of the start
|
||||
of the :term:`bytecode` range
|
||||
* ``end`` (an :class:`int`) represents the offset (inclusive) of the end of
|
||||
the :term:`bytecode` range
|
||||
* ``lineno`` is an :class:`int` representing the line number of the
|
||||
:term:`bytecode` range, or ``None`` if the bytecodes in the given range
|
||||
have no line number
|
||||
|
||||
The items yielded generated will have the following properties:
|
||||
|
||||
* The first range yielded will have a ``start`` of 0.
|
||||
* The ``(start, end)`` ranges will be non-decreasing and consecutive. That
|
||||
is, for any pair of :class:`tuple`\s, the ``start`` of the second will be
|
||||
equal to the ``end`` of the first.
|
||||
* No range will be backwards: ``end >= start`` for all triples.
|
||||
* The :class:`tuple` yielded will have ``end`` equal to the size of the
|
||||
:term:`bytecode`.
|
||||
|
||||
Zero-width ranges, where ``start == end``, are allowed. Zero-width ranges
|
||||
are used for lines that are present in the source code, but have been
|
||||
eliminated by the :term:`bytecode` compiler.
|
||||
|
||||
.. versionadded:: 3.10
|
||||
|
||||
.. seealso::
|
||||
|
||||
:pep:`626` - Precise line numbers for debugging and other tools.
|
||||
The PEP that introduced the :meth:`!co_lines` method.
|
||||
|
||||
|
||||
.. _frame-objects:
|
||||
|
||||
|
@ -402,9 +402,11 @@ 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 :attr:`~codeobject.co_lnotab` attribute of code objects is deprecated and
|
||||
The :attr:`~codeobject.co_lnotab` attribute of
|
||||
:ref:`code objects <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.
|
||||
Code that needs to convert from offset to line number should use the new
|
||||
:meth:`~codeobject.co_lines` method instead.
|
||||
|
||||
PEP 634: Structural Pattern Matching
|
||||
------------------------------------
|
||||
|
@ -816,7 +816,8 @@ although there is currently no date scheduled for their removal.
|
||||
|
||||
* :mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules.
|
||||
|
||||
* :attr:`~codeobject.co_lnotab`: use the ``co_lines`` attribute instead.
|
||||
* :attr:`codeobject.co_lnotab`: use the :meth:`codeobject.co_lines` method
|
||||
instead.
|
||||
|
||||
* :class:`typing.Text` (:gh:`92332`).
|
||||
|
||||
|
@ -147,8 +147,8 @@ clinic.
|
||||
.. nonce: yRWQ1y
|
||||
.. section: Core and Builtins
|
||||
|
||||
Improve the output of ``co_lines`` by emitting only one entry for each line
|
||||
range.
|
||||
Improve the output of :meth:`codeobject.co_lines` by emitting only one entry
|
||||
for each line range.
|
||||
|
||||
..
|
||||
|
||||
|
@ -60,7 +60,7 @@ Final form:
|
||||
Iterating over the table.
|
||||
-------------------------
|
||||
|
||||
For the `co_lines` attribute we want to emit the full form, omitting the (350, 360, No line number) and empty entries.
|
||||
For the `co_lines` method we want to emit the full form, omitting the (350, 360, No line number) and empty entries.
|
||||
|
||||
The code is as follows:
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user