Why do we need `dis.Positions`?

[sobolevn]

BPO	46422
Nosy	@pablogsal, @isidentical, @sobolevn
PRs	bpo-46422: use dis.Positions in dis.Instruction #30716

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2022-01-24.11:27:21.615>
created_at = <Date 2022-01-18.12:30:08.000>
labels = ['type-bug', 'library', '3.11']
title = 'Why do we need `dis.Positions`?'
updated_at = <Date 2022-01-24.11:27:21.615>
user = 'https://github.com/sobolevn'

bugs.python.org fields:

activity = <Date 2022-01-24.11:27:21.615>
actor = 'sobolevn'
assignee = 'none'
closed = True
closed_date = <Date 2022-01-24.11:27:21.615>
closer = 'sobolevn'
components = ['Library (Lib)']
creation = <Date 2022-01-18.12:30:08.000>
creator = 'sobolevn'
dependencies = []
files = []
hgrepos = []
issue_num = 46422
keywords = ['patch']
message_count = 4.0
messages = ['410855', '410927', '410935', '411466']
nosy_count = 3.0
nosy_names = ['pablogsal', 'BTaskaya', 'sobolevn']
pr_nums = ['30716']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue46422'
versions = ['Python 3.11']

[sobolevn]

While working on #30058 I've noticed that Positions namedtuple is kinda strange, source:
https://github.com/python/cpython/blame/8c2fd09f365e082cfceb29afdf38953cdd670946/Lib/dis.py#L204-L213

Why?

1. It is not used. grep shows that:

» ag Positions .  
Misc/HISTORY
21894:  treated as being relative to the end of the input string. Positions

Objects/codeobject.c
1021:static PyTypeObject PositionsIterator = {
1067:    positionsiterator* pi = (positionsiterator*)PyType_GenericAlloc(&PositionsIterator, 0);

Mac/PythonLauncher/English.lproj/MainMenu.nib/info.nib
7:      <key>IBEditorPositions</key>

Lib/dis.py
204:Positions = collections.namedtuple(
205:    'Positions',
239:_Instruction.positions.__doc__ = "dis.Positions object holding the span of source code covered by this instruction"
259:         positions - Optional dis.Positions object holding the span of source code

Lib/test/test_compile.py
1013:class TestSourcePositions(unittest.TestCase):

Doc/library/re.rst
1579:Finding all Adverbs and their Positions

2. Commenting it out does not make test_dis to fail (again, because it does not seem to be used)
3. It is documented (in docstrings only, not in dis.rst) that Instruction.positions is dis.Positions, but this is not true. Because Instruction is created as:

co_positions = co_positions or iter(())

try:
  positions = next(co_positions)
except StopIteration:
  positions = None

Instruction(positions=positions)

So, it is at best is tuple | None. Never Positions.

What to do with it?

1. Should it be removed as unused, undocumented, and unreleased?
2. Should it be used as documented? Here: https://github.com/python/cpython/blame/8c2fd09f365e082cfceb29afdf38953cdd670946/Lib/dis.py#L453-L455
3. Any other ideas?

In my opinion, it is not required, because we already have codeobject.co_positions which is pretty much the same thing: https://docs.python.org/3.11/reference/datamodel.html?highlight=co_positions#codeobject.co_positions

I would like to work on it after a final decision is made :)

[isidentical]

The initial aim of the dis.Positions was to provide an interface like AST nodes. So you could do

for instr in dis.Bytecode(source):
    print("located in: ", instr.positions.lineno)

instead of

for instr in dis.Bytecode(source):
    if instr.positions:
        lineno = instr.positions[0]
    else:
        lineno = None
    print("located in: ", lineno)

I think this is a bug that we are not currently using it, I'd say we should use it properly and go with option 2.

[sobolevn]

Ok then, I will send my option 2 proposal to fix this later today.

[isidentical]

New changeset 58f3d98 by Nikita Sobolev in branch 'main':
bpo-46422: use dis.Positions in dis.Instruction (GH-30716)
58f3d98