From 7aeb55dde84d58a377918faf2ba692f43f7000b2 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 3 Jan 2024 16:53:52 +0000 Subject: [PATCH 1/4] Document the `co_lines` method on code objects --- Doc/library/dis.rst | 9 +++++---- Doc/reference/datamodel.rst | 39 +++++++++++++++++++++++++++++++++++-- Doc/whatsnew/3.10.rst | 6 ++++-- Doc/whatsnew/3.13.rst | 3 ++- Misc/NEWS.d/3.12.0a4.rst | 4 ++-- Objects/lnotab_notes.txt | 2 +- 6 files changed, 51 insertions(+), 12 deletions(-) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 5823142cc75998..7492ae85c4ea46 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -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* 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 `. .. versionchanged:: 3.13 Line numbers can be ``None`` for bytecode that does not map to source lines. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index b3af5c6298d02d..14dbbfa9f9352e 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -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 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 a8a27bfd3dc1bc..cd86c82caffc56 100644 --- 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 ` 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/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index 888ebd0402d0e7..3ab6d1ddc6ef21 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -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`). diff --git a/Misc/NEWS.d/3.12.0a4.rst b/Misc/NEWS.d/3.12.0a4.rst index 75246f3f13503e..ce2814bbe2e5ab 100644 --- a/Misc/NEWS.d/3.12.0a4.rst +++ b/Misc/NEWS.d/3.12.0a4.rst @@ -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. .. diff --git a/Objects/lnotab_notes.txt b/Objects/lnotab_notes.txt index d45d09d4ab9a50..0f3599340318f0 100644 --- a/Objects/lnotab_notes.txt +++ b/Objects/lnotab_notes.txt @@ -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: From cbeba88aa27ae964711c94652a94727c0dd184ba Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 3 Jan 2024 17:21:37 +0000 Subject: [PATCH 2/4] . Co-authored-by: Hugo van Kemenade --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 14dbbfa9f9352e..ae37edab278b57 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1271,7 +1271,7 @@ Methods on code objects The items yielded generated will have the following properties: - * The first range yielded will have a ``start`` of 0; + * 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 equal to the end of the first. From ba2c50481d7755cfc2f675390f28601bae55d873 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 3 Jan 2024 17:23:56 +0000 Subject: [PATCH 3/4] Too many semicolons! I never thought it was possible --- Doc/reference/datamodel.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index ae37edab278b57..af0a577ba4be2e 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1262,19 +1262,19 @@ Methods on code objects :class:`tuple`: * ``start`` (an :class:`int`) represents the offset (inclusive) of the start - of the :term:`bytecode` range; + of the :term:`bytecode` range * ``end`` (an :class:`int`) represents the offset (inclusive) of the end of - the :term:`bytecode` range; + 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. + 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 equal - to the end of the first. + 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`. From 98dcf053f98c7bf4da7d91503d604e0c6a0613d7 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 3 Jan 2024 17:33:08 +0000 Subject: [PATCH 4/4] fix indentation --- Doc/reference/datamodel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index af0a577ba4be2e..d611bda298b509 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1288,7 +1288,7 @@ Methods on code objects .. seealso:: :pep:`626` - Precise line numbers for debugging and other tools. - The PEP that introduced the :meth:`!co_lines` method. + The PEP that introduced the :meth:`!co_lines` method. .. _frame-objects: