Add `show_positions` keyword argument to `dis.dis` and related functions

[markshannon]

Feature or enhancement

Proposal:

dis.dis is a useful debugging tool when trying to debug minor bytecode compiler errors.
However it lacks one important feature, the ability to see the exact positions attached to instructions. It can only show line numbers.

We should add a show_positions keyword argument to show positions.
For example, the function:

def foo(x):
    if x == 2:
        return 1

disassembles to:

  2           RESUME                   0

  3           LOAD_FAST                0 (x)
              LOAD_CONST               1 (2)
              COMPARE_OP              88 (bool(==))
              POP_JUMP_IF_FALSE        1 (to L1)

  4           RETURN_CONST             2 (1)

  3   L1:     RETURN_CONST             0 (None)

with show_positions it would disassemble to something like:

2:0-2:0                RESUME                   0

3:7-3:8                LOAD_FAST                0 (x)
3:12-3:13              LOAD_CONST               1 (2)
3:7-3:13               COMPARE_OP              88 (bool(==))
3:7-3:13               POP_JUMP_IF_FALSE        1 (to L1)

4:15-4:16              RETURN_CONST             2 (1)

3:7-3:13       L1:     RETURN_CONST             0 (None)

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-123165: make dis functions render positions on demand #123168
• gh-123165: correct tests for dis.dis(func, show_positions=True) #123220
• gh-123165: improve docs signature for dis.disassemble #123808

[markshannon]

@iritkatriel

[picnixz]

Since it's marked as an easy feature, could I perhaps work on this? (I took upon the task of doing it, so it will be ready in a few hours I think)