[New-bugs-announce] [issue44875] Update dis.findlinestarts documentaiton to reflect new usage of `co_lines` (PEP 626)

[George King]

New submission from George King <george.w.king at gmail.com>:

`dis.findlinestarts()` has been changed to use the no `co_lines()` function. (Blame indicates commit 877df851c3e by Mark Shannon.) However the docs currently state that it uses the older `co_firstlineno` and `co_lnotab`: https://docs.python.org/3.10/library/dis.html#dis.findlinestarts.

My cursory understanding of `dis.py` internals is that `get_instructions` relies on `findlinestarts`, implying that both of these APIs are going to return different line numbers than they did previously. I am perfectly fine with this, and hopeful that the PEP 626 changes will improve tool accuracy.

At minimum the `dis` docs should be updated. I also suggest that some kind of note about this be added to the PEP 626 text, because the way it reads now suggests that it avoids breakage by creating the new `co_lines` API. However it seems that users of the higher level dis APIs are going to see subtly different behavior.

FWIW I am fine with the change, and I hope this doesn't instigate a reversion to the old behavior. `lnotabs` semantics were very cryptic and seemed rather broken when I attempted to use it years ago. I am revisiting an experimental code coverage tool in part because of the PEP.

----------
assignee: docs at python
components: Documentation
messages: 399290
nosy: Mark.Shannon, docs at python, gwk
priority: normal
severity: normal
status: open
title: Update dis.findlinestarts documentaiton to reflect new usage of `co_lines` (PEP 626)
versions: Python 3.10

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue44875>
_______________________________________