[3.11] Document the `co_lines` method on code objects (#113682) (#113687)

(cherry-picked from commit f1f839243251fef7422c31d6a7c3c747e0b5e27c)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 0a699346d09533fa020b2dd7d5e3b54e1086182f..2c7a87d4b25d40ef4701cff7f97b9c62641c9785 100644 (file)
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -314,17 +314,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>`.
 
 
 .. function:: findlabels(code)

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 1c2324d77cd484a9dfda4d8c54dbf9f02bd10bca..e04827e34f7927304084684796e14a31c0ef0288 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1202,8 +1202,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()
 
@@ -1238,6 +1238,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:
 

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 1fce4cfcbc6c5a49cf9ff087174e3a56293ede4f..87982c1e380eb5d59045ec1daa5f68036cb3b213 100644 (file)
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -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
 ------------------------------------

diff --git a/Objects/lnotab_notes.txt b/Objects/lnotab_notes.txt
index 362b87a86a481f086328f76bbbe409a6608dd037..a11ad937ec90e5e3184e72a9c143f1e752db8be8 100644 (file)
--- a/Objects/lnotab_notes.txt
+++ b/Objects/lnotab_notes.txt
@@ -57,7 +57,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: