Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 198aa67

Browse files
authoredOct 17, 2023
gh-107457: update dis documentation with changes in 3.12 (#108900)
1 parent 24e4ec7 commit 198aa67

File tree

1 file changed

+43
-16
lines changed

1 file changed

+43
-16
lines changed
 

‎Doc/library/dis.rst

Lines changed: 43 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,14 @@ interpreter.
4242
bytecode to specialize it for different runtime conditions. The
4343
adaptive bytecode can be shown by passing ``adaptive=True``.
4444

45+
.. versionchanged:: 3.12
46+
The argument of a jump is the offset of the target instruction relative
47+
to the instruction that appears immediately after the jump instruction's
48+
:opcode:`CACHE` entries.
49+
50+
As a consequence, the presence of the :opcode:`CACHE` instructions is
51+
transparent for forward jumps but needs to be taken into account when
52+
reasoning about backward jumps.
4553

4654
Example: Given the function :func:`!myfunc`::
4755

@@ -513,6 +521,14 @@ operations on it as if it was a Python list. The top of the stack corresponds to
513521
.. versionadded:: 3.12
514522

515523

524+
.. opcode:: END_SEND
525+
526+
Implements ``del STACK[-2]``.
527+
Used to clean up when a generator exits.
528+
529+
.. versionadded:: 3.12
530+
531+
516532
.. opcode:: COPY (i)
517533

518534
Push the i-th item to the top of the stack without removing it from its original
@@ -1159,15 +1175,21 @@ iterations of the loop.
11591175

11601176
.. opcode:: LOAD_SUPER_ATTR (namei)
11611177

1162-
This opcode implements :func:`super` (e.g. ``super().method()`` and
1163-
``super().attr``). It works the same as :opcode:`LOAD_ATTR`, except that
1164-
``namei`` is shifted left by 2 bits instead of 1, and instead of expecting a
1165-
single receiver on the stack, it expects three objects (from top of stack
1166-
down): ``self`` (the first argument to the current method), ``cls`` (the
1167-
class within which the current method was defined), and the global ``super``.
1178+
This opcode implements :func:`super`, both in its zero-argument and
1179+
two-argument forms (e.g. ``super().method()``, ``super().attr`` and
1180+
``super(cls, self).method()``, ``super(cls, self).attr``).
1181+
1182+
It pops three values from the stack (from top of stack down):
1183+
- ``self``: the first argument to the current method
1184+
- ``cls``: the class within which the current method was defined
1185+
- the global ``super``
1186+
1187+
With respect to its argument, it works similarly to :opcode:`LOAD_ATTR`,
1188+
except that ``namei`` is shifted left by 2 bits instead of 1.
11681189

11691190
The low bit of ``namei`` signals to attempt a method load, as with
1170-
:opcode:`LOAD_ATTR`.
1191+
:opcode:`LOAD_ATTR`, which results in pushing ``None`` and the loaded method.
1192+
When it is unset a single value is pushed to the stack.
11711193

11721194
The second-low bit of ``namei``, if set, means that this was a two-argument
11731195
call to :func:`super` (unset means zero-argument).
@@ -1632,9 +1654,9 @@ iterations of the loop.
16321654
Equivalent to ``STACK[-1] = STACK[-2].send(STACK[-1])``. Used in ``yield from``
16331655
and ``await`` statements.
16341656

1635-
If the call raises :exc:`StopIteration`, pop both items, push the
1636-
exception's ``value`` attribute, and increment the bytecode counter by
1637-
*delta*.
1657+
If the call raises :exc:`StopIteration`, pop the top value from the stack,
1658+
push the exception's ``value`` attribute, and increment the bytecode counter
1659+
by *delta*.
16381660

16391661
.. versionadded:: 3.11
16401662

@@ -1664,7 +1686,7 @@ iterations of the loop.
16641686

16651687
Calls an intrinsic function with one argument. Passes ``STACK[-1]`` as the
16661688
argument and sets ``STACK[-1]`` to the result. Used to implement
1667-
functionality that is necessary but not performance critical.
1689+
functionality that is not performance critical.
16681690

16691691
The operand determines which intrinsic function is called:
16701692

@@ -1712,9 +1734,13 @@ iterations of the loop.
17121734

17131735
.. opcode:: CALL_INTRINSIC_2
17141736

1715-
Calls an intrinsic function with two arguments. Passes ``STACK[-2]``, ``STACK[-1]`` as the
1716-
arguments and sets ``STACK[-1]`` to the result. Used to implement functionality that is
1717-
necessary but not performance critical.
1737+
Calls an intrinsic function with two arguments. Used to implement functionality
1738+
that is not performance critical::
1739+
1740+
arg2 = STACK.pop()
1741+
arg1 = STACK.pop()
1742+
result = intrinsic2(arg1, arg2)
1743+
STACK.push(result)
17181744

17191745
The operand determines which intrinsic function is called:
17201746

@@ -1810,8 +1836,9 @@ These collections are provided for automatic introspection of bytecode
18101836
instructions:
18111837

18121838
.. versionchanged:: 3.12
1813-
The collections now contain pseudo instructions as well. These are
1814-
opcodes with values ``>= MIN_PSEUDO_OPCODE``.
1839+
The collections now contain pseudo instructions and instrumented
1840+
instructions as well. These are opcodes with values ``>= MIN_PSEUDO_OPCODE``
1841+
and ``>= MIN_INSTRUMENTED_OPCODE``.
18151842

18161843
.. data:: opname
18171844

0 commit comments

Comments
 (0)
Please sign in to comment.