code.co_positions behaviour does not match documentation

[iritkatriel]

The documentation of co_positions() says:

The iterator returns tuples containing the (start_line, end_line, start_column, end_column). The i-th tuple corresponds to the position of the source code that compiled to the i-th instruction.

I think this is incorrect, because the iterator returns tuples for cache entries as well:

>>> def f():
...   a.b = 1
... 
>>> import dis
>>> dis.dis(f)
  1           0 RESUME                   0

  2           2 LOAD_CONST               1 (1)
              4 LOAD_GLOBAL              0 (a)
             16 STORE_ATTR               1 (b)
             26 LOAD_CONST               0 (None)
             28 RETURN_VALUE
>>> len(list(f.__code__.co_positions()))
15
>>> from pprint import pprint as pp
>>> pp(list(f.__code__.co_positions()))
[(1, 1, 0, 0),
 (2, 2, 8, 9),
 (2, 2, 2, 3),
 (2, 2, 2, 3),
 (2, 2, 2, 3),
 (2, 2, 2, 3),
 (2, 2, 2, 3),
 (2, 2, 2, 3),
 (2, 2, 2, 5),
 (2, 2, 2, 5),
 (2, 2, 2, 5),
 (2, 2, 2, 5),
 (2, 2, 2, 5),
 (2, 2, 2, 5),
 (2, 2, 2, 5)]
>>> 

Linked PRs

• GH-100117: Make co_lines more efficient #100447
• gh-100117: Fix inaccuracy in documentation of the CodeObject's co_positions field. #119364
• [3.13] gh-100117: Fix inaccuracy in documentation of the CodeObject's co_positions field. (GH-119364) #119869
• [3.12] gh-100117: Fix inaccuracy in documentation of the CodeObject's co_positions field. (GH-119364) #119870
• [3.11] gh-100117: Fix inaccuracy in documentation of the CodeObject's co_positions field. (GH-119364) #119871

[iritkatriel]

CC @markshannon @brandtbucher .

[brandtbucher]

I think this is probably just a place where the docs could be improved.

Are you suggesting replacing "instruction" with "code unit"? Or adding a note that inline CACHE "instructions" are included? I'd be fine with either.

[iritkatriel]

We discussed this at the meeting and I think the view was that the implementation needs to change. @markshannon ?

[markshannon]

I don't think we can change the current behavior of emitting one tuple per code unit . The docs should reflect that behaviour.

I think it is co_lines() that we should modify. We can merge successive tuples with the same line number, now that #99556 is merged.