Debian Codegraph @

Doc/library/dis.rst

raw
1 :mod:`!dis` --- Disassembler for Python bytecode
2 ================================================
3
4 .. module:: dis
5 :synopsis: Disassembler for Python bytecode.
6
7 **Source code:** :source:`Lib/dis.py`
8
9 .. testsetup::
10
11 import dis
12 def myfunc(alist):
13 return len(alist)
14
15 --------------
16
17 The :mod:`!dis` module supports the analysis of CPython :term:`bytecode` by
18 disassembling it. The CPython bytecode which this module takes as an input is
19 defined in the file :file:`Include/opcode.h` and used by the compiler and the
20 interpreter.
21
22 .. impl-detail::
23
24 Bytecode is an implementation detail of the CPython interpreter. No
25 guarantees are made that bytecode will not be added, removed, or changed
26 between versions of Python. Use of this module should not be considered to
27 work across Python VMs or Python releases.
28
29 .. versionchanged:: 3.6
30 Use 2 bytes for each instruction. Previously the number of bytes varied
31 by instruction.
32
33 .. versionchanged:: 3.10
34 The argument of jump, exception handling and loop instructions is now
35 the instruction offset rather than the byte offset.
36
37 .. versionchanged:: 3.11
38 Some instructions are accompanied by one or more inline cache entries,
39 which take the form of :opcode:`CACHE` instructions. These instructions
40 are hidden by default, but can be shown by passing ``show_caches=True`` to
41 any :mod:`!dis` utility. Furthermore, the interpreter now adapts the
42 bytecode to specialize it for different runtime conditions. The
43 adaptive bytecode can be shown by passing ``adaptive=True``.
44
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.
53
54 .. versionchanged:: 3.13
55 The output shows logical labels rather than instruction offsets
56 for jump targets and exception handlers. The ``-O`` command line
57 option and the ``show_offsets`` argument were added.
58
59 .. versionchanged:: 3.14
60 The :option:`-P <dis --show-positions>` command-line option
61 and the ``show_positions`` argument were added.
62
63 The :option:`-S <dis --specialized>` command-line option is added.
64
65 Example: Given the function :func:`!myfunc`::
66
67 def myfunc(alist):
68 return len(alist)
69
70 the following command can be used to display the disassembly of
71 :func:`!myfunc`:
72
73 .. doctest::
74
75 >>> dis.dis(myfunc)
76 2 RESUME 0
77 <BLANKLINE>
78 3 LOAD_GLOBAL 1 (len + NULL)
79 LOAD_FAST_BORROW 0 (alist)
80 CALL 1
81 RETURN_VALUE
82
83 (The "2" is a line number).
84
85 .. _dis-cli:
86
87 Command-line interface
88 ----------------------
89
90 The :mod:`!dis` module can be invoked as a script from the command line:
91
92 .. code-block:: sh
93
94 python -m dis [-h] [-C] [-O] [-P] [-S] [infile]
95
96 The following options are accepted:
97
98 .. program:: dis
99
100 .. option:: -h, --help
101
102 Display usage and exit.
103
104 .. option:: -C, --show-caches
105
106 Show inline caches.
107
108 .. versionadded:: 3.13
109
110 .. option:: -O, --show-offsets
111
112 Show offsets of instructions.
113
114 .. versionadded:: 3.13
115
116 .. option:: -P, --show-positions
117
118 Show positions of instructions in the source code.
119
120 .. versionadded:: 3.14
121
122 .. option:: -S, --specialized
123
124 Show specialized bytecode.
125
126 .. versionadded:: 3.14
127
128 If :file:`infile` is specified, its disassembled code will be written to stdout.
129 Otherwise, disassembly is performed on compiled source code received from stdin.
130
131 Bytecode analysis
132 -----------------
133
134 .. versionadded:: 3.4
135
136 The bytecode analysis API allows pieces of Python code to be wrapped in a
137 :class:`Bytecode` object that provides easy access to details of the compiled
138 code.
139
140 .. class:: Bytecode(x, *, first_line=None, current_offset=None,\
141 show_caches=False, adaptive=False, show_offsets=False,\
142 show_positions=False)
143
144 Analyse the bytecode corresponding to a function, generator, asynchronous
145 generator, coroutine, method, string of source code, or a code object (as
146 returned by :func:`compile`).
147
148 This is a convenience wrapper around many of the functions listed below, most
149 notably :func:`get_instructions`, as iterating over a :class:`Bytecode`
150 instance yields the bytecode operations as :class:`Instruction` instances.
151
152 If *first_line* is not ``None``, it indicates the line number that should be
153 reported for the first source line in the disassembled code. Otherwise, the
154 source line information (if any) is taken directly from the disassembled code
155 object.
156
157 If *current_offset* is not ``None``, it refers to an instruction offset in the
158 disassembled code. Setting this means :meth:`.dis` will display a "current
159 instruction" marker against the specified opcode.
160
161 If *show_caches* is ``True``, :meth:`.dis` will display inline cache
162 entries used by the interpreter to specialize the bytecode.
163
164 If *adaptive* is ``True``, :meth:`.dis` will display specialized bytecode
165 that may be different from the original bytecode.
166
167 If *show_offsets* is ``True``, :meth:`.dis` will include instruction
168 offsets in the output.
169
170 If *show_positions* is ``True``, :meth:`.dis` will include instruction
171 source code positions in the output.
172
173 .. classmethod:: from_traceback(tb, *, show_caches=False)
174
175 Construct a :class:`Bytecode` instance from the given traceback, setting
176 *current_offset* to the instruction responsible for the exception.
177
178 .. data:: codeobj
179
180 The compiled code object.
181
182 .. data:: first_line
183
184 The first source line of the code object (if available)
185
186 .. method:: dis()
187
188 Return a formatted view of the bytecode operations (the same as printed by
189 :func:`dis.dis`, but returned as a multi-line string).
190
191 .. method:: info()
192
193 Return a formatted multi-line string with detailed information about the
194 code object, like :func:`code_info`.
195
196 .. versionchanged:: 3.7
197 This can now handle coroutine and asynchronous generator objects.
198
199 .. versionchanged:: 3.11
200 Added the *show_caches* and *adaptive* parameters.
201
202 .. versionchanged:: 3.13
203 Added the *show_offsets* parameter
204
205 .. versionchanged:: 3.14
206 Added the *show_positions* parameter.
207
208 Example:
209
210 .. doctest::
211
212 >>> bytecode = dis.Bytecode(myfunc)
213 >>> for instr in bytecode:
214 ... print(instr.opname)
215 ...
216 RESUME
217 LOAD_GLOBAL
218 LOAD_FAST_BORROW
219 CALL
220 RETURN_VALUE
221
222
223 Analysis functions
224 ------------------
225
226 The :mod:`!dis` module also defines the following analysis functions that convert
227 the input directly to the desired output. They can be useful if only a single
228 operation is being performed, so the intermediate analysis object isn't useful:
229
230 .. function:: code_info(x)
231
232 Return a formatted multi-line string with detailed code object information
233 for the supplied function, generator, asynchronous generator, coroutine,
234 method, source code string or code object.
235
236 Note that the exact contents of code info strings are highly implementation
237 dependent and they may change arbitrarily across Python VMs or Python
238 releases.
239
240 .. versionadded:: 3.2
241
242 .. versionchanged:: 3.7
243 This can now handle coroutine and asynchronous generator objects.
244
245
246 .. function:: show_code(x, *, file=None)
247
248 Print detailed code object information for the supplied function, method,
249 source code string or code object to *file* (or ``sys.stdout`` if *file*
250 is not specified).
251
252 This is a convenient shorthand for ``print(code_info(x), file=file)``,
253 intended for interactive exploration at the interpreter prompt.
254
255 .. versionadded:: 3.2
256
257 .. versionchanged:: 3.4
258 Added *file* parameter.
259
260
261 .. function:: dis(x=None, *, file=None, depth=None, show_caches=False,\
262 adaptive=False, show_offsets=False, show_positions=False)
263
264 Disassemble the *x* object. *x* can denote either a module, a class, a
265 method, a function, a generator, an asynchronous generator, a coroutine,
266 a code object, a string of source code or a byte sequence of raw bytecode.
267 For a module, it disassembles all functions. For a class, it disassembles
268 all methods (including class and static methods). For a code object or
269 sequence of raw bytecode, it prints one line per bytecode instruction.
270 It also recursively disassembles nested code objects. These can include
271 generator expressions, nested functions, the bodies of nested classes,
272 and the code objects used for :ref:`annotation scopes <annotation-scopes>`.
273 Strings are first compiled to code objects with the :func:`compile`
274 built-in function before being disassembled. If no object is provided, this
275 function disassembles the last traceback.
276
277 The disassembly is written as text to the supplied *file* argument if
278 provided and to ``sys.stdout`` otherwise.
279
280 The maximal depth of recursion is limited by *depth* unless it is ``None``.
281 ``depth=0`` means no recursion.
282
283 If *show_caches* is ``True``, this function will display inline cache
284 entries used by the interpreter to specialize the bytecode.
285
286 If *adaptive* is ``True``, this function will display specialized bytecode
287 that may be different from the original bytecode.
288
289 .. versionchanged:: 3.4
290 Added *file* parameter.
291
292 .. versionchanged:: 3.7
293 Implemented recursive disassembling and added *depth* parameter.
294
295 .. versionchanged:: 3.7
296 This can now handle coroutine and asynchronous generator objects.
297
298 .. versionchanged:: 3.11
299 Added the *show_caches* and *adaptive* parameters.
300
301 .. versionchanged:: 3.13
302 Added the *show_offsets* parameter.
303
304 .. versionchanged:: 3.14
305 Added the *show_positions* parameter.
306
307 .. function:: distb(tb=None, *, file=None, show_caches=False, adaptive=False,\
308 show_offset=False, show_positions=False)
309
310 Disassemble the top-of-stack function of a traceback, using the last
311 traceback if none was passed. The instruction causing the exception is
312 indicated.
313
314 The disassembly is written as text to the supplied *file* argument if
315 provided and to ``sys.stdout`` otherwise.
316
317 .. versionchanged:: 3.4
318 Added *file* parameter.
319
320 .. versionchanged:: 3.11
321 Added the *show_caches* and *adaptive* parameters.
322
323 .. versionchanged:: 3.13
324 Added the *show_offsets* parameter.
325
326 .. versionchanged:: 3.14
327 Added the *show_positions* parameter.
328
329 .. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False,\
330 adaptive=False, show_offsets=False, show_positions=False)
331 disco(code, lasti=-1, *, file=None, show_caches=False, adaptive=False,\
332 show_offsets=False, show_positions=False)
333
334 Disassemble a code object, indicating the last instruction if *lasti* was
335 provided. The output is divided in the following columns:
336
337 #. the source code location of the instruction. Complete location information
338 is shown if *show_positions* is true. Otherwise (the default) only the
339 line number is displayed.
340 #. the current instruction, indicated as ``-->``,
341 #. a labelled instruction, indicated with ``>>``,
342 #. the address of the instruction,
343 #. the operation code name,
344 #. operation parameters, and
345 #. interpretation of the parameters in parentheses.
346
347 The parameter interpretation recognizes local and global variable names,
348 constant values, branch targets, and compare operators.
349
350 The disassembly is written as text to the supplied *file* argument if
351 provided and to ``sys.stdout`` otherwise.
352
353 .. versionchanged:: 3.4
354 Added *file* parameter.
355
356 .. versionchanged:: 3.11
357 Added the *show_caches* and *adaptive* parameters.
358
359 .. versionchanged:: 3.13
360 Added the *show_offsets* parameter.
361
362 .. versionchanged:: 3.14
363 Added the *show_positions* parameter.
364
365 .. function:: get_instructions(x, *, first_line=None, show_caches=False, adaptive=False)
366
367 Return an iterator over the instructions in the supplied function, method,
368 source code string or code object.
369
370 The iterator generates a series of :class:`Instruction` named tuples giving
371 the details of each operation in the supplied code.
372
373 If *first_line* is not ``None``, it indicates the line number that should be
374 reported for the first source line in the disassembled code. Otherwise, the
375 source line information (if any) is taken directly from the disassembled code
376 object.
377
378 The *adaptive* parameter works as it does in :func:`dis`.
379
380 .. versionadded:: 3.4
381
382 .. versionchanged:: 3.11
383 Added the *show_caches* and *adaptive* parameters.
384
385 .. versionchanged:: 3.13
386 The *show_caches* parameter is deprecated and has no effect. The iterator
387 generates the :class:`Instruction` instances with the *cache_info*
388 field populated (regardless of the value of *show_caches*) and it no longer
389 generates separate items for the cache entries.
390
391 .. function:: findlinestarts(code)
392
393 This generator function uses the :meth:`~codeobject.co_lines` method
394 of the :ref:`code object <code-objects>` *code* to find the offsets which
395 are starts of
396 lines in the source code. They are generated as ``(offset, lineno)`` pairs.
397
398 .. versionchanged:: 3.6
399 Line numbers can be decreasing. Before, they were always increasing.
400
401 .. versionchanged:: 3.10
402 The :pep:`626` :meth:`~codeobject.co_lines` method is used instead of the
403 :attr:`~codeobject.co_firstlineno` and :attr:`~codeobject.co_lnotab`
404 attributes of the :ref:`code object <code-objects>`.
405
406 .. versionchanged:: 3.13
407 Line numbers can be ``None`` for bytecode that does not map to source lines.
408
409
410 .. function:: findlabels(code)
411
412 Detect all offsets in the raw compiled bytecode string *code* which are jump targets, and
413 return a list of these offsets.
414
415
416 .. function:: stack_effect(opcode, oparg=None, *, jump=None)
417
418 Compute the stack effect of *opcode* with argument *oparg*.
419
420 If the code has a jump target and *jump* is ``True``, :func:`~stack_effect`
421 will return the stack effect of jumping. If *jump* is ``False``,
422 it will return the stack effect of not jumping. And if *jump* is
423 ``None`` (default), it will return the maximal stack effect of both cases.
424
425 .. versionadded:: 3.4
426
427 .. versionchanged:: 3.8
428 Added *jump* parameter.
429
430 .. versionchanged:: 3.13
431 If ``oparg`` is omitted (or ``None``), the stack effect is now returned
432 for ``oparg=0``. Previously this was an error for opcodes that use their
433 arg. It is also no longer an error to pass an integer ``oparg`` when
434 the ``opcode`` does not use it; the ``oparg`` in this case is ignored.
435
436
437 .. _bytecodes:
438
439 Python Bytecode Instructions
440 ----------------------------
441
442 The :func:`get_instructions` function and :class:`Bytecode` class provide
443 details of bytecode instructions as :class:`Instruction` instances:
444
445 .. class:: Instruction
446
447 Details for a bytecode operation
448
449 .. data:: opcode
450
451 numeric code for operation, corresponding to the opcode values listed
452 below and the bytecode values in the :ref:`opcode_collections`.
453
454
455 .. data:: opname
456
457 human readable name for operation
458
459
460 .. data:: baseopcode
461
462 numeric code for the base operation if operation is specialized;
463 otherwise equal to :data:`opcode`
464
465
466 .. data:: baseopname
467
468 human readable name for the base operation if operation is specialized;
469 otherwise equal to :data:`opname`
470
471
472 .. data:: arg
473
474 numeric argument to operation (if any), otherwise ``None``
475
476 .. data:: oparg
477
478 alias for :data:`arg`
479
480 .. data:: argval
481
482 resolved arg value (if any), otherwise ``None``
483
484
485 .. data:: argrepr
486
487 human readable description of operation argument (if any),
488 otherwise an empty string.
489
490
491 .. data:: offset
492
493 start index of operation within bytecode sequence
494
495
496 .. data:: start_offset
497
498 start index of operation within bytecode sequence, including prefixed
499 ``EXTENDED_ARG`` operations if present; otherwise equal to :data:`offset`
500
501
502 .. data:: cache_offset
503
504 start index of the cache entries following the operation
505
506
507 .. data:: end_offset
508
509 end index of the cache entries following the operation
510
511
512 .. data:: starts_line
513
514 ``True`` if this opcode starts a source line, otherwise ``False``
515
516
517 .. data:: line_number
518
519 source line number associated with this opcode (if any), otherwise ``None``
520
521
522 .. data:: is_jump_target
523
524 ``True`` if other code jumps to here, otherwise ``False``
525
526
527 .. data:: jump_target
528
529 bytecode index of the jump target if this is a jump operation,
530 otherwise ``None``
531
532
533 .. data:: positions
534
535 :class:`dis.Positions` object holding the
536 start and end locations that are covered by this instruction.
537
538 .. data:: cache_info
539
540 Information about the cache entries of this instruction, as
541 triplets of the form ``(name, size, data)``, where the ``name``
542 and ``size`` describe the cache format and data is the contents
543 of the cache. ``cache_info`` is ``None`` if the instruction does not have
544 caches.
545
546 .. versionadded:: 3.4
547
548 .. versionchanged:: 3.11
549
550 Field ``positions`` is added.
551
552 .. versionchanged:: 3.13
553
554 Changed field ``starts_line``.
555
556 Added fields ``start_offset``, ``cache_offset``, ``end_offset``,
557 ``baseopname``, ``baseopcode``, ``jump_target``, ``oparg``,
558 ``line_number`` and ``cache_info``.
559
560
561 .. class:: Positions
562
563 In case the information is not available, some fields might be ``None``.
564
565 .. data:: lineno
566 .. data:: end_lineno
567 .. data:: col_offset
568 .. data:: end_col_offset
569
570 .. versionadded:: 3.11
571
572
573 The Python compiler currently generates the following bytecode instructions.
574
575
576 **General instructions**
577
578 In the following, We will refer to the interpreter stack as ``STACK`` and describe
579 operations on it as if it was a Python list. The top of the stack corresponds to
580 ``STACK[-1]`` in this language.
581
582 .. opcode:: NOP
583
584 Do nothing code. Used as a placeholder by the bytecode optimizer, and to
585 generate line tracing events.
586
587
588 .. opcode:: NOT_TAKEN
589
590 Do nothing code.
591 Used by the interpreter to record :monitoring-event:`BRANCH_LEFT`
592 and :monitoring-event:`BRANCH_RIGHT` events for :mod:`sys.monitoring`.
593
594 .. versionadded:: 3.14
595
596
597 .. opcode:: POP_ITER
598
599 Removes the iterator from the top of the stack.
600
601 .. versionadded:: 3.14
602
603
604 .. opcode:: POP_TOP
605
606 Removes the top-of-stack item::
607
608 STACK.pop()
609
610
611 .. opcode:: END_FOR
612
613 Removes the top-of-stack item.
614 Equivalent to ``POP_TOP``.
615 Used to clean up at the end of loops, hence the name.
616
617 .. versionadded:: 3.12
618
619
620 .. opcode:: END_SEND
621
622 Implements ``del STACK[-2]``.
623 Used to clean up when a generator exits.
624
625 .. versionadded:: 3.12
626
627
628 .. opcode:: COPY (i)
629
630 Push the i-th item to the top of the stack without removing it from its original
631 location::
632
633 assert i > 0
634 STACK.append(STACK[-i])
635
636 .. versionadded:: 3.11
637
638
639 .. opcode:: SWAP (i)
640
641 Swap the top of the stack with the i-th element::
642
643 STACK[-i], STACK[-1] = STACK[-1], STACK[-i]
644
645 .. versionadded:: 3.11
646
647
648 .. opcode:: CACHE
649
650 Rather than being an actual instruction, this opcode is used to mark extra
651 space for the interpreter to cache useful data directly in the bytecode
652 itself. It is automatically hidden by all ``dis`` utilities, but can be
653 viewed with ``show_caches=True``.
654
655 Logically, this space is part of the preceding instruction. Many opcodes
656 expect to be followed by an exact number of caches, and will instruct the
657 interpreter to skip over them at runtime.
658
659 Populated caches can look like arbitrary instructions, so great care should
660 be taken when reading or modifying raw, adaptive bytecode containing
661 quickened data.
662
663 .. versionadded:: 3.11
664
665
666 **Unary operations**
667
668 Unary operations take the top of the stack, apply the operation, and push the
669 result back on the stack.
670
671
672 .. opcode:: UNARY_NEGATIVE
673
674 Implements ``STACK[-1] = -STACK[-1]``.
675
676
677 .. opcode:: UNARY_NOT
678
679 Implements ``STACK[-1] = not STACK[-1]``.
680
681 .. versionchanged:: 3.13
682 This instruction now requires an exact :class:`bool` operand.
683
684
685 .. opcode:: UNARY_INVERT
686
687 Implements ``STACK[-1] = ~STACK[-1]``.
688
689
690 .. opcode:: GET_ITER
691
692 Implements ``STACK[-1] = iter(STACK[-1])``.
693
694
695 .. opcode:: GET_YIELD_FROM_ITER
696
697 If ``STACK[-1]`` is a :term:`generator iterator` or :term:`coroutine` object
698 it is left as is. Otherwise, implements ``STACK[-1] = iter(STACK[-1])``.
699
700 .. versionadded:: 3.5
701
702
703 .. opcode:: TO_BOOL
704
705 Implements ``STACK[-1] = bool(STACK[-1])``.
706
707 .. versionadded:: 3.13
708
709
710 **Binary and in-place operations**
711
712 Binary operations remove the top two items from the stack (``STACK[-1]`` and
713 ``STACK[-2]``). They perform the operation, then put the result back on the stack.
714
715 In-place operations are like binary operations, but the operation is done in-place
716 when ``STACK[-2]`` supports it, and the resulting ``STACK[-1]`` may be (but does
717 not have to be) the original ``STACK[-2]``.
718
719
720 .. opcode:: BINARY_OP (op)
721
722 Implements the binary and in-place operators (depending on the value of
723 *op*)::
724
725 rhs = STACK.pop()
726 lhs = STACK.pop()
727 STACK.append(lhs op rhs)
728
729 .. versionadded:: 3.11
730 .. versionchanged:: 3.14
731 With oparg :``NB_SUBSCR``, implements binary subscript (replaces opcode ``BINARY_SUBSCR``)
732
733
734 .. opcode:: STORE_SUBSCR
735
736 Implements::
737
738 key = STACK.pop()
739 container = STACK.pop()
740 value = STACK.pop()
741 container[key] = value
742
743
744 .. opcode:: DELETE_SUBSCR
745
746 Implements::
747
748 key = STACK.pop()
749 container = STACK.pop()
750 del container[key]
751
752 .. opcode:: BINARY_SLICE
753
754 Implements::
755
756 end = STACK.pop()
757 start = STACK.pop()
758 container = STACK.pop()
759 STACK.append(container[start:end])
760
761 .. versionadded:: 3.12
762
763
764 .. opcode:: STORE_SLICE
765
766 Implements::
767
768 end = STACK.pop()
769 start = STACK.pop()
770 container = STACK.pop()
771 value = STACK.pop()
772 container[start:end] = value
773
774 .. versionadded:: 3.12
775
776
777 **Coroutine opcodes**
778
779 .. opcode:: GET_AWAITABLE (where)
780
781 Implements ``STACK[-1] = get_awaitable(STACK[-1])``, where ``get_awaitable(o)``
782 returns ``o`` if ``o`` is a coroutine object or a generator object with
783 the :data:`~inspect.CO_ITERABLE_COROUTINE` flag, or resolves
784 ``o.__await__``.
785
786 If the ``where`` operand is nonzero, it indicates where the instruction
787 occurs:
788
789 * ``1``: After a call to ``__aenter__``
790 * ``2``: After a call to ``__aexit__``
791
792 .. versionadded:: 3.5
793
794 .. versionchanged:: 3.11
795 Previously, this instruction did not have an oparg.
796
797
798 .. opcode:: GET_AITER
799
800 Implements ``STACK[-1] = STACK[-1].__aiter__()``.
801
802 .. versionadded:: 3.5
803 .. versionchanged:: 3.7
804 Returning awaitable objects from ``__aiter__`` is no longer
805 supported.
806
807
808 .. opcode:: GET_ANEXT
809
810 Implement ``STACK.append(get_awaitable(STACK[-1].__anext__()))`` to the stack.
811 See ``GET_AWAITABLE`` for details about ``get_awaitable``.
812
813 .. versionadded:: 3.5
814
815
816 .. opcode:: END_ASYNC_FOR
817
818 Terminates an :keyword:`async for` loop. Handles an exception raised
819 when awaiting a next item. The stack contains the async iterable in
820 ``STACK[-2]`` and the raised exception in ``STACK[-1]``. Both are popped.
821 If the exception is not :exc:`StopAsyncIteration`, it is re-raised.
822
823 .. versionadded:: 3.8
824
825 .. versionchanged:: 3.11
826 Exception representation on the stack now consist of one, not three, items.
827
828
829 .. opcode:: CLEANUP_THROW
830
831 Handles an exception raised during a :meth:`~generator.throw` or
832 :meth:`~generator.close` call through the current frame. If ``STACK[-1]`` is an
833 instance of :exc:`StopIteration`, pop three values from the stack and push
834 its ``value`` member. Otherwise, re-raise ``STACK[-1]``.
835
836 .. versionadded:: 3.12
837
838
839
840 **Miscellaneous opcodes**
841
842 .. opcode:: SET_ADD (i)
843
844 Implements::
845
846 item = STACK.pop()
847 set.add(STACK[-i], item)
848
849 Used to implement set comprehensions.
850
851
852 .. opcode:: LIST_APPEND (i)
853
854 Implements::
855
856 item = STACK.pop()
857 list.append(STACK[-i], item)
858
859 Used to implement list comprehensions.
860
861
862 .. opcode:: MAP_ADD (i)
863
864 Implements::
865
866 value = STACK.pop()
867 key = STACK.pop()
868 dict.__setitem__(STACK[-i], key, value)
869
870 Used to implement dict comprehensions.
871
872 .. versionadded:: 3.1
873 .. versionchanged:: 3.8
874 Map value is ``STACK[-1]`` and map key is ``STACK[-2]``. Before, those
875 were reversed.
876
877 For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:`MAP_ADD`
878 instructions, while the added value or key/value pair is popped off, the
879 container object remains on the stack so that it is available for further
880 iterations of the loop.
881
882
883 .. opcode:: RETURN_VALUE
884
885 Returns with ``STACK[-1]`` to the caller of the function.
886
887
888 .. opcode:: YIELD_VALUE
889
890 Yields ``STACK.pop()`` from a :term:`generator`.
891
892 .. versionchanged:: 3.11
893 oparg set to be the stack depth.
894
895 .. versionchanged:: 3.12
896 oparg set to be the exception block depth, for efficient closing of generators.
897
898 .. versionchanged:: 3.13
899 oparg is ``1`` if this instruction is part of a yield-from or await, and ``0``
900 otherwise.
901
902 .. opcode:: SETUP_ANNOTATIONS
903
904 Checks whether ``__annotations__`` is defined in ``locals()``, if not it is
905 set up to an empty ``dict``. This opcode is only emitted if a class
906 or module body contains :term:`variable annotations <variable annotation>`
907 statically.
908
909 .. versionadded:: 3.6
910
911
912 .. opcode:: POP_EXCEPT
913
914 Pops a value from the stack, which is used to restore the exception state.
915
916 .. versionchanged:: 3.11
917 Exception representation on the stack now consist of one, not three, items.
918
919 .. opcode:: RERAISE
920
921 Re-raises the exception currently on top of the stack. If oparg is non-zero,
922 pops an additional value from the stack which is used to set
923 :attr:`~frame.f_lasti` of the current frame.
924
925 .. versionadded:: 3.9
926
927 .. versionchanged:: 3.11
928 Exception representation on the stack now consist of one, not three, items.
929
930 .. opcode:: PUSH_EXC_INFO
931
932 Pops a value from the stack. Pushes the current exception to the top of the stack.
933 Pushes the value originally popped back to the stack.
934 Used in exception handlers.
935
936 .. versionadded:: 3.11
937
938 .. opcode:: CHECK_EXC_MATCH
939
940 Performs exception matching for ``except``. Tests whether the ``STACK[-2]``
941 is an exception matching ``STACK[-1]``. Pops ``STACK[-1]`` and pushes the boolean
942 result of the test.
943
944 .. versionadded:: 3.11
945
946 .. opcode:: CHECK_EG_MATCH
947
948 Performs exception matching for ``except*``. Applies ``split(STACK[-1])`` on
949 the exception group representing ``STACK[-2]``.
950
951 In case of a match, pops two items from the stack and pushes the
952 non-matching subgroup (``None`` in case of full match) followed by the
953 matching subgroup. When there is no match, pops one item (the match
954 type) and pushes ``None``.
955
956 .. versionadded:: 3.11
957
958 .. opcode:: WITH_EXCEPT_START
959
960 Calls the function in position 4 on the stack with arguments (type, val, tb)
961 representing the exception at the top of the stack.
962 Used to implement the call ``context_manager.__exit__(*exc_info())`` when an exception
963 has occurred in a :keyword:`with` statement.
964
965 .. versionadded:: 3.9
966
967 .. versionchanged:: 3.11
968 The ``__exit__`` function is in position 4 of the stack rather than 7.
969 Exception representation on the stack now consist of one, not three, items.
970
971
972 .. opcode:: LOAD_COMMON_CONSTANT
973
974 Pushes a common constant onto the stack. The interpreter contains a hardcoded
975 list of constants supported by this instruction. Used by the :keyword:`assert`
976 statement to load :exc:`AssertionError`.
977
978 .. versionadded:: 3.14
979
980
981 .. opcode:: LOAD_BUILD_CLASS
982
983 Pushes :func:`!builtins.__build_class__` onto the stack. It is later called
984 to construct a class.
985
986 .. opcode:: GET_LEN
987
988 Perform ``STACK.append(len(STACK[-1]))``. Used in :keyword:`match` statements where
989 comparison with structure of pattern is needed.
990
991 .. versionadded:: 3.10
992
993
994 .. opcode:: MATCH_MAPPING
995
996 If ``STACK[-1]`` is an instance of :class:`collections.abc.Mapping` (or, more
997 technically: if it has the :c:macro:`Py_TPFLAGS_MAPPING` flag set in its
998 :c:member:`~PyTypeObject.tp_flags`), push ``True`` onto the stack. Otherwise,
999 push ``False``.
1000
1001 .. versionadded:: 3.10
1002
1003
1004 .. opcode:: MATCH_SEQUENCE
1005
1006 If ``STACK[-1]`` is an instance of :class:`collections.abc.Sequence` and is *not* an instance
1007 of :class:`str`/:class:`bytes`/:class:`bytearray` (or, more technically: if it has
1008 the :c:macro:`Py_TPFLAGS_SEQUENCE` flag set in its :c:member:`~PyTypeObject.tp_flags`),
1009 push ``True`` onto the stack. Otherwise, push ``False``.
1010
1011 .. versionadded:: 3.10
1012
1013
1014 .. opcode:: MATCH_KEYS
1015
1016 ``STACK[-1]`` is a tuple of mapping keys, and ``STACK[-2]`` is the match subject.
1017 If ``STACK[-2]`` contains all of the keys in ``STACK[-1]``, push a :class:`tuple`
1018 containing the corresponding values. Otherwise, push ``None``.
1019
1020 .. versionadded:: 3.10
1021
1022 .. versionchanged:: 3.11
1023 Previously, this instruction also pushed a boolean value indicating
1024 success (``True``) or failure (``False``).
1025
1026
1027 .. opcode:: STORE_NAME (namei)
1028
1029 Implements ``name = STACK.pop()``. *namei* is the index of *name* in the attribute
1030 :attr:`~codeobject.co_names` of the :ref:`code object <code-objects>`.
1031 The compiler tries to use :opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.
1032
1033
1034 .. opcode:: DELETE_NAME (namei)
1035
1036 Implements ``del name``, where *namei* is the index into :attr:`~codeobject.co_names`
1037 attribute of the :ref:`code object <code-objects>`.
1038
1039
1040 .. opcode:: UNPACK_SEQUENCE (count)
1041
1042 Unpacks ``STACK[-1]`` into *count* individual values, which are put onto the stack
1043 right-to-left. Require there to be exactly *count* values.::
1044
1045 assert(len(STACK[-1]) == count)
1046 STACK.extend(STACK.pop()[:-count-1:-1])
1047
1048
1049 .. opcode:: UNPACK_EX (counts)
1050
1051 Implements assignment with a starred target: Unpacks an iterable in ``STACK[-1]``
1052 into individual values, where the total number of values can be smaller than the
1053 number of items in the iterable: one of the new values will be a list of all
1054 leftover items.
1055
1056 The number of values before and after the list value is limited to 255.
1057
1058 The number of values before the list value is encoded in the argument of the
1059 opcode. The number of values after the list if any is encoded using an
1060 ``EXTENDED_ARG``. As a consequence, the argument can be seen as a two bytes values
1061 where the low byte of *counts* is the number of values before the list value, the
1062 high byte of *counts* the number of values after it.
1063
1064 The extracted values are put onto the stack right-to-left, i.e. ``a, *b, c = d``
1065 will be stored after execution as ``STACK.extend((a, b, c))``.
1066
1067
1068 .. opcode:: STORE_ATTR (namei)
1069
1070 Implements::
1071
1072 obj = STACK.pop()
1073 value = STACK.pop()
1074 obj.name = value
1075
1076 where *namei* is the index of name in :attr:`~codeobject.co_names` of the
1077 :ref:`code object <code-objects>`.
1078
1079 .. opcode:: DELETE_ATTR (namei)
1080
1081 Implements::
1082
1083 obj = STACK.pop()
1084 del obj.name
1085
1086 where *namei* is the index of name into :attr:`~codeobject.co_names` of the
1087 :ref:`code object <code-objects>`.
1088
1089
1090 .. opcode:: STORE_GLOBAL (namei)
1091
1092 Works as :opcode:`STORE_NAME`, but stores the name as a global.
1093
1094
1095 .. opcode:: DELETE_GLOBAL (namei)
1096
1097 Works as :opcode:`DELETE_NAME`, but deletes a global name.
1098
1099
1100 .. opcode:: LOAD_CONST (consti)
1101
1102 Pushes ``co_consts[consti]`` onto the stack.
1103
1104
1105 .. opcode:: LOAD_SMALL_INT (i)
1106
1107 Pushes the integer ``i`` onto the stack.
1108 ``i`` must be in ``range(256)``
1109
1110 .. versionadded:: 3.14
1111
1112
1113 .. opcode:: LOAD_NAME (namei)
1114
1115 Pushes the value associated with ``co_names[namei]`` onto the stack.
1116 The name is looked up within the locals, then the globals, then the builtins.
1117
1118
1119 .. opcode:: LOAD_LOCALS
1120
1121 Pushes a reference to the locals dictionary onto the stack. This is used
1122 to prepare namespace dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF`
1123 and :opcode:`LOAD_FROM_DICT_OR_GLOBALS`.
1124
1125 .. versionadded:: 3.12
1126
1127
1128 .. opcode:: LOAD_FROM_DICT_OR_GLOBALS (i)
1129
1130 Pops a mapping off the stack and looks up the value for ``co_names[namei]``.
1131 If the name is not found there, looks it up in the globals and then the builtins,
1132 similar to :opcode:`LOAD_GLOBAL`.
1133 This is used for loading global variables in
1134 :ref:`annotation scopes <annotation-scopes>` within class bodies.
1135
1136 .. versionadded:: 3.12
1137
1138
1139 .. opcode:: BUILD_TEMPLATE
1140
1141 Constructs a new :class:`~string.templatelib.Template` instance from a tuple
1142 of strings and a tuple of interpolations and pushes the resulting object
1143 onto the stack::
1144
1145 interpolations = STACK.pop()
1146 strings = STACK.pop()
1147 STACK.append(_build_template(strings, interpolations))
1148
1149 .. versionadded:: 3.14
1150
1151
1152 .. opcode:: BUILD_INTERPOLATION (format)
1153
1154 Constructs a new :class:`~string.templatelib.Interpolation` instance from a
1155 value and its source expression and pushes the resulting object onto the
1156 stack.
1157
1158 If no conversion or format specification is present, ``format`` is set to
1159 ``2``.
1160
1161 If the low bit of ``format`` is set, it indicates that the interpolation
1162 contains a format specification.
1163
1164 If ``format >> 2`` is non-zero, it indicates that the interpolation
1165 contains a conversion. The value of ``format >> 2`` is the conversion type
1166 (``0`` for no conversion, ``1`` for ``!s``, ``2`` for ``!r``, and
1167 ``3`` for ``!a``)::
1168
1169 conversion = format >> 2
1170 if format & 1:
1171 format_spec = STACK.pop()
1172 else:
1173 format_spec = None
1174 expression = STACK.pop()
1175 value = STACK.pop()
1176 STACK.append(_build_interpolation(value, expression, conversion, format_spec))
1177
1178 .. versionadded:: 3.14
1179
1180
1181 .. opcode:: BUILD_TUPLE (count)
1182
1183 Creates a tuple consuming *count* items from the stack, and pushes the
1184 resulting tuple onto the stack::
1185
1186 if count == 0:
1187 value = ()
1188 else:
1189 value = tuple(STACK[-count:])
1190 STACK = STACK[:-count]
1191
1192 STACK.append(value)
1193
1194
1195 .. opcode:: BUILD_LIST (count)
1196
1197 Works as :opcode:`BUILD_TUPLE`, but creates a list.
1198
1199
1200 .. opcode:: BUILD_SET (count)
1201
1202 Works as :opcode:`BUILD_TUPLE`, but creates a set.
1203
1204
1205 .. opcode:: BUILD_MAP (count)
1206
1207 Pushes a new dictionary object onto the stack. Pops ``2 * count`` items
1208 so that the dictionary holds *count* entries:
1209 ``{..., STACK[-4]: STACK[-3], STACK[-2]: STACK[-1]}``.
1210
1211 .. versionchanged:: 3.5
1212 The dictionary is created from stack items instead of creating an
1213 empty dictionary pre-sized to hold *count* items.
1214
1215
1216 .. opcode:: BUILD_STRING (count)
1217
1218 Concatenates *count* strings from the stack and pushes the resulting string
1219 onto the stack.
1220
1221 .. versionadded:: 3.6
1222
1223
1224 .. opcode:: LIST_EXTEND (i)
1225
1226 Implements::
1227
1228 seq = STACK.pop()
1229 list.extend(STACK[-i], seq)
1230
1231 Used to build lists.
1232
1233 .. versionadded:: 3.9
1234
1235
1236 .. opcode:: SET_UPDATE (i)
1237
1238 Implements::
1239
1240 seq = STACK.pop()
1241 set.update(STACK[-i], seq)
1242
1243 Used to build sets.
1244
1245 .. versionadded:: 3.9
1246
1247
1248 .. opcode:: DICT_UPDATE (i)
1249
1250 Implements::
1251
1252 map = STACK.pop()
1253 dict.update(STACK[-i], map)
1254
1255 Used to build dicts.
1256
1257 .. versionadded:: 3.9
1258
1259
1260 .. opcode:: DICT_MERGE (i)
1261
1262 Like :opcode:`DICT_UPDATE` but raises an exception for duplicate keys.
1263
1264 .. versionadded:: 3.9
1265
1266
1267 .. opcode:: LOAD_ATTR (namei)
1268
1269 If the low bit of ``namei`` is not set, this replaces ``STACK[-1]`` with
1270 ``getattr(STACK[-1], co_names[namei>>1])``.
1271
1272 If the low bit of ``namei`` is set, this will attempt to load a method named
1273 ``co_names[namei>>1]`` from the ``STACK[-1]`` object. ``STACK[-1]`` is popped.
1274 This bytecode distinguishes two cases: if ``STACK[-1]`` has a method with the
1275 correct name, the bytecode pushes the unbound method and ``STACK[-1]``.
1276 ``STACK[-1]`` will be used as the first argument (``self``) by :opcode:`CALL`
1277 or :opcode:`CALL_KW` when calling the unbound method.
1278 Otherwise, ``NULL`` and the object returned by
1279 the attribute lookup are pushed.
1280
1281 .. versionchanged:: 3.12
1282 If the low bit of ``namei`` is set, then a ``NULL`` or ``self`` is
1283 pushed to the stack before the attribute or unbound method respectively.
1284
1285
1286 .. opcode:: LOAD_SUPER_ATTR (namei)
1287
1288 This opcode implements :func:`super`, both in its zero-argument and
1289 two-argument forms (e.g. ``super().method()``, ``super().attr`` and
1290 ``super(cls, self).method()``, ``super(cls, self).attr``).
1291
1292 It pops three values from the stack (from top of stack down):
1293
1294 * ``self``: the first argument to the current method
1295 * ``cls``: the class within which the current method was defined
1296 * the global ``super``
1297
1298 With respect to its argument, it works similarly to :opcode:`LOAD_ATTR`,
1299 except that ``namei`` is shifted left by 2 bits instead of 1.
1300
1301 The low bit of ``namei`` signals to attempt a method load, as with
1302 :opcode:`LOAD_ATTR`, which results in pushing ``NULL`` and the loaded method.
1303 When it is unset a single value is pushed to the stack.
1304
1305 The second-low bit of ``namei``, if set, means that this was a two-argument
1306 call to :func:`super` (unset means zero-argument).
1307
1308 .. versionadded:: 3.12
1309
1310
1311 .. opcode:: COMPARE_OP (opname)
1312
1313 Performs a Boolean operation. The operation name can be found in
1314 ``cmp_op[opname >> 5]``. If the fifth-lowest bit of ``opname`` is set
1315 (``opname & 16``), the result should be coerced to ``bool``.
1316
1317 .. versionchanged:: 3.13
1318 The fifth-lowest bit of the oparg now indicates a forced conversion to
1319 :class:`bool`.
1320
1321
1322 .. opcode:: IS_OP (invert)
1323
1324 Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.
1325
1326 .. versionadded:: 3.9
1327
1328
1329 .. opcode:: CONTAINS_OP (invert)
1330
1331 Performs ``in`` comparison, or ``not in`` if ``invert`` is 1.
1332
1333 .. versionadded:: 3.9
1334
1335
1336 .. opcode:: IMPORT_NAME (namei)
1337
1338 Imports the module ``co_names[namei]``. ``STACK[-1]`` and ``STACK[-2]`` are
1339 popped and provide the *fromlist* and *level* arguments of :func:`__import__`.
1340 The module object is pushed onto the stack. The current namespace is not affected: for a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
1341 modifies the namespace.
1342
1343
1344 .. opcode:: IMPORT_FROM (namei)
1345
1346 Loads the attribute ``co_names[namei]`` from the module found in ``STACK[-1]``.
1347 The resulting object is pushed onto the stack, to be subsequently stored by a
1348 :opcode:`STORE_FAST` instruction.
1349
1350
1351 .. opcode:: JUMP_FORWARD (delta)
1352
1353 Increments bytecode counter by *delta*.
1354
1355
1356 .. opcode:: JUMP_BACKWARD (delta)
1357
1358 Decrements bytecode counter by *delta*. Checks for interrupts.
1359
1360 .. versionadded:: 3.11
1361
1362
1363 .. opcode:: JUMP_BACKWARD_NO_INTERRUPT (delta)
1364
1365 Decrements bytecode counter by *delta*. Does not check for interrupts.
1366
1367 .. versionadded:: 3.11
1368
1369
1370 .. opcode:: POP_JUMP_IF_TRUE (delta)
1371
1372 If ``STACK[-1]`` is true, increments the bytecode counter by *delta*.
1373 ``STACK[-1]`` is popped.
1374
1375 .. versionchanged:: 3.11
1376 The oparg is now a relative delta rather than an absolute target.
1377 This opcode is a pseudo-instruction, replaced in final bytecode by
1378 the directed versions (forward/backward).
1379
1380 .. versionchanged:: 3.12
1381 This is no longer a pseudo-instruction.
1382
1383 .. versionchanged:: 3.13
1384 This instruction now requires an exact :class:`bool` operand.
1385
1386 .. opcode:: POP_JUMP_IF_FALSE (delta)
1387
1388 If ``STACK[-1]`` is false, increments the bytecode counter by *delta*.
1389 ``STACK[-1]`` is popped.
1390
1391 .. versionchanged:: 3.11
1392 The oparg is now a relative delta rather than an absolute target.
1393 This opcode is a pseudo-instruction, replaced in final bytecode by
1394 the directed versions (forward/backward).
1395
1396 .. versionchanged:: 3.12
1397 This is no longer a pseudo-instruction.
1398
1399 .. versionchanged:: 3.13
1400 This instruction now requires an exact :class:`bool` operand.
1401
1402 .. opcode:: POP_JUMP_IF_NOT_NONE (delta)
1403
1404 If ``STACK[-1]`` is not ``None``, increments the bytecode counter by *delta*.
1405 ``STACK[-1]`` is popped.
1406
1407 .. versionadded:: 3.11
1408
1409 .. versionchanged:: 3.12
1410 This is no longer a pseudo-instruction.
1411
1412
1413 .. opcode:: POP_JUMP_IF_NONE (delta)
1414
1415 If ``STACK[-1]`` is ``None``, increments the bytecode counter by *delta*.
1416 ``STACK[-1]`` is popped.
1417
1418 .. versionadded:: 3.11
1419
1420 .. versionchanged:: 3.12
1421 This is no longer a pseudo-instruction.
1422
1423 .. opcode:: FOR_ITER (delta)
1424
1425 ``STACK[-1]`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` method.
1426 If this yields a new value, push it on the stack (leaving the iterator below
1427 it). If the iterator indicates it is exhausted then the byte code counter is
1428 incremented by *delta*.
1429
1430 .. versionchanged:: 3.12
1431 Up until 3.11 the iterator was popped when it was exhausted.
1432
1433 .. opcode:: LOAD_GLOBAL (namei)
1434
1435 Loads the global named ``co_names[namei>>1]`` onto the stack.
1436
1437 .. versionchanged:: 3.11
1438 If the low bit of ``namei`` is set, then a ``NULL`` is pushed to the
1439 stack before the global variable.
1440
1441 .. opcode:: LOAD_FAST (var_num)
1442
1443 Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
1444
1445 .. versionchanged:: 3.12
1446 This opcode is now only used in situations where the local variable is
1447 guaranteed to be initialized. It cannot raise :exc:`UnboundLocalError`.
1448
1449 .. opcode:: LOAD_FAST_BORROW (var_num)
1450
1451 Pushes a borrowed reference to the local ``co_varnames[var_num]`` onto the
1452 stack.
1453
1454 .. versionadded:: 3.14
1455
1456 .. opcode:: LOAD_FAST_LOAD_FAST (var_nums)
1457
1458 Pushes references to ``co_varnames[var_nums >> 4]`` and
1459 ``co_varnames[var_nums & 15]`` onto the stack.
1460
1461 .. versionadded:: 3.13
1462
1463
1464 .. opcode:: LOAD_FAST_BORROW_LOAD_FAST_BORROW (var_nums)
1465
1466 Pushes borrowed references to ``co_varnames[var_nums >> 4]`` and
1467 ``co_varnames[var_nums & 15]`` onto the stack.
1468
1469 .. versionadded:: 3.14
1470
1471 .. opcode:: LOAD_FAST_CHECK (var_num)
1472
1473 Pushes a reference to the local ``co_varnames[var_num]`` onto the stack,
1474 raising an :exc:`UnboundLocalError` if the local variable has not been
1475 initialized.
1476
1477 .. versionadded:: 3.12
1478
1479 .. opcode:: LOAD_FAST_AND_CLEAR (var_num)
1480
1481 Pushes a reference to the local ``co_varnames[var_num]`` onto the stack (or
1482 pushes ``NULL`` onto the stack if the local variable has not been
1483 initialized) and sets ``co_varnames[var_num]`` to ``NULL``.
1484
1485 .. versionadded:: 3.12
1486
1487 .. opcode:: STORE_FAST (var_num)
1488
1489 Stores ``STACK.pop()`` into the local ``co_varnames[var_num]``.
1490
1491 .. opcode:: STORE_FAST_STORE_FAST (var_nums)
1492
1493 Stores ``STACK[-1]`` into ``co_varnames[var_nums >> 4]``
1494 and ``STACK[-2]`` into ``co_varnames[var_nums & 15]``.
1495
1496 .. versionadded:: 3.13
1497
1498 .. opcode:: STORE_FAST_LOAD_FAST (var_nums)
1499
1500 Stores ``STACK.pop()`` into the local ``co_varnames[var_nums >> 4]``
1501 and pushes a reference to the local ``co_varnames[var_nums & 15]``
1502 onto the stack.
1503
1504 .. versionadded:: 3.13
1505
1506 .. opcode:: DELETE_FAST (var_num)
1507
1508 Deletes local ``co_varnames[var_num]``.
1509
1510
1511 .. opcode:: MAKE_CELL (i)
1512
1513 Creates a new cell in slot ``i``. If that slot is nonempty then
1514 that value is stored into the new cell.
1515
1516 .. versionadded:: 3.11
1517
1518
1519 .. opcode:: LOAD_DEREF (i)
1520
1521 Loads the cell contained in slot ``i`` of the "fast locals" storage.
1522 Pushes a reference to the object the cell contains on the stack.
1523
1524 .. versionchanged:: 3.11
1525 ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
1526
1527
1528 .. opcode:: LOAD_FROM_DICT_OR_DEREF (i)
1529
1530 Pops a mapping off the stack and looks up the name associated with
1531 slot ``i`` of the "fast locals" storage in this mapping.
1532 If the name is not found there, loads it from the cell contained in
1533 slot ``i``, similar to :opcode:`LOAD_DEREF`. This is used for loading
1534 :term:`closure variables <closure variable>` in class bodies (which previously used
1535 :opcode:`!LOAD_CLASSDEREF`) and in
1536 :ref:`annotation scopes <annotation-scopes>` within class bodies.
1537
1538 .. versionadded:: 3.12
1539
1540
1541 .. opcode:: STORE_DEREF (i)
1542
1543 Stores ``STACK.pop()`` into the cell contained in slot ``i`` of the "fast locals"
1544 storage.
1545
1546 .. versionchanged:: 3.11
1547 ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
1548
1549
1550 .. opcode:: DELETE_DEREF (i)
1551
1552 Empties the cell contained in slot ``i`` of the "fast locals" storage.
1553 Used by the :keyword:`del` statement.
1554
1555 .. versionadded:: 3.2
1556
1557 .. versionchanged:: 3.11
1558 ``i`` is no longer offset by the length of :attr:`~codeobject.co_varnames`.
1559
1560
1561 .. opcode:: COPY_FREE_VARS (n)
1562
1563 Copies the ``n`` :term:`free (closure) variables <closure variable>` from the closure
1564 into the frame. Removes the need for special code on the caller's side when calling
1565 closures.
1566
1567 .. versionadded:: 3.11
1568
1569
1570 .. opcode:: RAISE_VARARGS (argc)
1571
1572 Raises an exception using one of the 3 forms of the ``raise`` statement,
1573 depending on the value of *argc*:
1574
1575 * 0: ``raise`` (re-raise previous exception)
1576 * 1: ``raise STACK[-1]`` (raise exception instance or type at ``STACK[-1]``)
1577 * 2: ``raise STACK[-2] from STACK[-1]`` (raise exception instance or type at
1578 ``STACK[-2]`` with ``__cause__`` set to ``STACK[-1]``)
1579
1580
1581 .. opcode:: CALL (argc)
1582
1583 Calls a callable object with the number of arguments specified by ``argc``.
1584 On the stack are (in ascending order):
1585
1586 * The callable
1587 * ``self`` or ``NULL``
1588 * The remaining positional arguments
1589
1590 ``argc`` is the total of the positional arguments, excluding ``self``.
1591
1592 ``CALL`` pops all arguments and the callable object off the stack,
1593 calls the callable object with those arguments, and pushes the return value
1594 returned by the callable object.
1595
1596 .. versionadded:: 3.11
1597
1598 .. versionchanged:: 3.13
1599 The callable now always appears at the same position on the stack.
1600
1601 .. versionchanged:: 3.13
1602 Calls with keyword arguments are now handled by :opcode:`CALL_KW`.
1603
1604
1605 .. opcode:: CALL_KW (argc)
1606
1607 Calls a callable object with the number of arguments specified by ``argc``,
1608 including one or more named arguments. On the stack are (in ascending order):
1609
1610 * The callable
1611 * ``self`` or ``NULL``
1612 * The remaining positional arguments
1613 * The named arguments
1614 * A :class:`tuple` of keyword argument names
1615
1616 ``argc`` is the total of the positional and named arguments, excluding ``self``.
1617 The length of the tuple of keyword argument names is the number of named arguments.
1618
1619 ``CALL_KW`` pops all arguments, the keyword names, and the callable object
1620 off the stack, calls the callable object with those arguments, and pushes the
1621 return value returned by the callable object.
1622
1623 .. versionadded:: 3.13
1624
1625
1626 .. opcode:: CALL_FUNCTION_EX (flags)
1627
1628 Calls a callable object with variable set of positional and keyword
1629 arguments. If the lowest bit of *flags* is set, the top of the stack
1630 contains a mapping object containing additional keyword arguments.
1631 Before the callable is called, the mapping object and iterable object
1632 are each "unpacked" and their contents passed in as keyword and
1633 positional arguments respectively.
1634 ``CALL_FUNCTION_EX`` pops all arguments and the callable object off the stack,
1635 calls the callable object with those arguments, and pushes the return value
1636 returned by the callable object.
1637
1638 .. versionadded:: 3.6
1639
1640
1641 .. opcode:: PUSH_NULL
1642
1643 Pushes a ``NULL`` to the stack.
1644 Used in the call sequence to match the ``NULL`` pushed by
1645 :opcode:`!LOAD_METHOD` for non-method calls.
1646
1647 .. versionadded:: 3.11
1648
1649
1650 .. opcode:: MAKE_FUNCTION
1651
1652 Pushes a new function object on the stack built from the code object at ``STACK[-1]``.
1653
1654 .. versionchanged:: 3.10
1655 Flag value ``0x04`` is a tuple of strings instead of dictionary
1656
1657 .. versionchanged:: 3.11
1658 Qualified name at ``STACK[-1]`` was removed.
1659
1660 .. versionchanged:: 3.13
1661 Extra function attributes on the stack, signaled by oparg flags, were
1662 removed. They now use :opcode:`SET_FUNCTION_ATTRIBUTE`.
1663
1664
1665 .. opcode:: SET_FUNCTION_ATTRIBUTE (flag)
1666
1667 Sets an attribute on a function object. Expects the function at ``STACK[-1]``
1668 and the attribute value to set at ``STACK[-2]``; consumes both and leaves the
1669 function at ``STACK[-1]``. The flag determines which attribute to set:
1670
1671 * ``0x01`` a tuple of default values for positional-only and
1672 positional-or-keyword parameters in positional order
1673 * ``0x02`` a dictionary of keyword-only parameters' default values
1674 * ``0x04`` a tuple of strings containing parameters' annotations
1675 * ``0x08`` a tuple containing cells for free variables, making a closure
1676 * ``0x10`` the :term:`annotate function` for the function object
1677
1678 .. versionadded:: 3.13
1679
1680 .. versionchanged:: 3.14
1681 Added ``0x10`` to indicate the annotate function for the function object.
1682
1683
1684 .. opcode:: BUILD_SLICE (argc)
1685
1686 .. index:: pair: built-in function; slice
1687
1688 Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2, implements::
1689
1690 end = STACK.pop()
1691 start = STACK.pop()
1692 STACK.append(slice(start, end))
1693
1694 if it is 3, implements::
1695
1696 step = STACK.pop()
1697 end = STACK.pop()
1698 start = STACK.pop()
1699 STACK.append(slice(start, end, step))
1700
1701 See the :func:`slice` built-in function for more information.
1702
1703
1704 .. opcode:: EXTENDED_ARG (ext)
1705
1706 Prefixes any opcode which has an argument too big to fit into the default one
1707 byte. *ext* holds an additional byte which act as higher bits in the argument.
1708 For each opcode, at most three prefixal ``EXTENDED_ARG`` are allowed, forming
1709 an argument from two-byte to four-byte.
1710
1711
1712 .. opcode:: CONVERT_VALUE (oparg)
1713
1714 Convert value to a string, depending on ``oparg``::
1715
1716 value = STACK.pop()
1717 result = func(value)
1718 STACK.append(result)
1719
1720 * ``oparg == 1``: call :func:`str` on *value*
1721 * ``oparg == 2``: call :func:`repr` on *value*
1722 * ``oparg == 3``: call :func:`ascii` on *value*
1723
1724 Used for implementing formatted string literals (f-strings).
1725
1726 .. versionadded:: 3.13
1727
1728
1729 .. opcode:: FORMAT_SIMPLE
1730
1731 Formats the value on top of stack::
1732
1733 value = STACK.pop()
1734 result = value.__format__("")
1735 STACK.append(result)
1736
1737 Used for implementing formatted string literals (f-strings).
1738
1739 .. versionadded:: 3.13
1740
1741 .. opcode:: FORMAT_WITH_SPEC
1742
1743 Formats the given value with the given format spec::
1744
1745 spec = STACK.pop()
1746 value = STACK.pop()
1747 result = value.__format__(spec)
1748 STACK.append(result)
1749
1750 Used for implementing formatted string literals (f-strings).
1751
1752 .. versionadded:: 3.13
1753
1754
1755 .. opcode:: MATCH_CLASS (count)
1756
1757 ``STACK[-1]`` is a tuple of keyword attribute names, ``STACK[-2]`` is the class
1758 being matched against, and ``STACK[-3]`` is the match subject. *count* is the
1759 number of positional sub-patterns.
1760
1761 Pop ``STACK[-1]``, ``STACK[-2]``, and ``STACK[-3]``. If ``STACK[-3]`` is an
1762 instance of ``STACK[-2]`` and has the positional and keyword attributes
1763 required by *count* and ``STACK[-1]``, push a tuple of extracted attributes.
1764 Otherwise, push ``None``.
1765
1766 .. versionadded:: 3.10
1767
1768 .. versionchanged:: 3.11
1769 Previously, this instruction also pushed a boolean value indicating
1770 success (``True``) or failure (``False``).
1771
1772
1773 .. opcode:: RESUME (context)
1774
1775 A no-op. Performs internal tracing, debugging and optimization checks.
1776
1777 The ``context`` operand consists of two parts. The lowest two bits
1778 indicate where the ``RESUME`` occurs:
1779
1780 * ``0`` The start of a function, which is neither a generator, coroutine
1781 nor an async generator
1782 * ``1`` After a ``yield`` expression
1783 * ``2`` After a ``yield from`` expression
1784 * ``3`` After an ``await`` expression
1785
1786 The next bit is ``1`` if the RESUME is at except-depth ``1``, and ``0``
1787 otherwise.
1788
1789 .. versionadded:: 3.11
1790
1791 .. versionchanged:: 3.13
1792 The oparg value changed to include information about except-depth
1793
1794
1795 .. opcode:: RETURN_GENERATOR
1796
1797 Create a generator, coroutine, or async generator from the current frame.
1798 Used as first opcode of in code object for the above mentioned callables.
1799 Clear the current frame and return the newly created generator.
1800
1801 .. versionadded:: 3.11
1802
1803
1804 .. opcode:: SEND (delta)
1805
1806 Equivalent to ``STACK[-1] = STACK[-2].send(STACK[-1])``. Used in ``yield from``
1807 and ``await`` statements.
1808
1809 If the call raises :exc:`StopIteration`, pop the top value from the stack,
1810 push the exception's ``value`` attribute, and increment the bytecode counter
1811 by *delta*.
1812
1813 .. versionadded:: 3.11
1814
1815
1816 .. opcode:: HAVE_ARGUMENT
1817
1818 This is not really an opcode. It identifies the dividing line between
1819 opcodes in the range [0,255] which don't use their argument and those
1820 that do (``< HAVE_ARGUMENT`` and ``>= HAVE_ARGUMENT``, respectively).
1821
1822 If your application uses pseudo instructions or specialized instructions,
1823 use the :data:`hasarg` collection instead.
1824
1825 .. versionchanged:: 3.6
1826 Now every instruction has an argument, but opcodes ``< HAVE_ARGUMENT``
1827 ignore it. Before, only opcodes ``>= HAVE_ARGUMENT`` had an argument.
1828
1829 .. versionchanged:: 3.12
1830 Pseudo instructions were added to the :mod:`!dis` module, and for them
1831 it is not true that comparison with ``HAVE_ARGUMENT`` indicates whether
1832 they use their arg.
1833
1834 .. deprecated:: 3.13
1835 Use :data:`hasarg` instead.
1836
1837 .. opcode:: CALL_INTRINSIC_1
1838
1839 Calls an intrinsic function with one argument. Passes ``STACK[-1]`` as the
1840 argument and sets ``STACK[-1]`` to the result. Used to implement
1841 functionality that is not performance critical.
1842
1843 The operand determines which intrinsic function is called:
1844
1845 +-----------------------------------+-----------------------------------+
1846 | Operand | Description |
1847 +===================================+===================================+
1848 | ``INTRINSIC_1_INVALID`` | Not valid |
1849 +-----------------------------------+-----------------------------------+
1850 | ``INTRINSIC_PRINT`` | Prints the argument to standard |
1851 | | out. Used in the REPL. |
1852 +-----------------------------------+-----------------------------------+
1853 | ``INTRINSIC_IMPORT_STAR`` | Performs ``import *`` for the |
1854 | | named module. |
1855 +-----------------------------------+-----------------------------------+
1856 | ``INTRINSIC_STOPITERATION_ERROR`` | Extracts the return value from a |
1857 | | ``StopIteration`` exception. |
1858 +-----------------------------------+-----------------------------------+
1859 | ``INTRINSIC_ASYNC_GEN_WRAP`` | Wraps an async generator value |
1860 +-----------------------------------+-----------------------------------+
1861 | ``INTRINSIC_UNARY_POSITIVE`` | Performs the unary ``+`` |
1862 | | operation |
1863 +-----------------------------------+-----------------------------------+
1864 | ``INTRINSIC_LIST_TO_TUPLE`` | Converts a list to a tuple |
1865 +-----------------------------------+-----------------------------------+
1866 | ``INTRINSIC_TYPEVAR`` | Creates a :class:`typing.TypeVar` |
1867 +-----------------------------------+-----------------------------------+
1868 | ``INTRINSIC_PARAMSPEC`` | Creates a |
1869 | | :class:`typing.ParamSpec` |
1870 +-----------------------------------+-----------------------------------+
1871 | ``INTRINSIC_TYPEVARTUPLE`` | Creates a |
1872 | | :class:`typing.TypeVarTuple` |
1873 +-----------------------------------+-----------------------------------+
1874 | ``INTRINSIC_SUBSCRIPT_GENERIC`` | Returns :class:`typing.Generic` |
1875 | | subscripted with the argument |
1876 +-----------------------------------+-----------------------------------+
1877 | ``INTRINSIC_TYPEALIAS`` | Creates a |
1878 | | :class:`typing.TypeAliasType`; |
1879 | | used in the :keyword:`type` |
1880 | | statement. The argument is a tuple|
1881 | | of the type alias's name, |
1882 | | type parameters, and value. |
1883 +-----------------------------------+-----------------------------------+
1884
1885 .. versionadded:: 3.12
1886
1887 .. opcode:: CALL_INTRINSIC_2
1888
1889 Calls an intrinsic function with two arguments. Used to implement functionality
1890 that is not performance critical::
1891
1892 arg2 = STACK.pop()
1893 arg1 = STACK.pop()
1894 result = intrinsic2(arg1, arg2)
1895 STACK.append(result)
1896
1897 The operand determines which intrinsic function is called:
1898
1899 +----------------------------------------+-----------------------------------+
1900 | Operand | Description |
1901 +========================================+===================================+
1902 | ``INTRINSIC_2_INVALID`` | Not valid |
1903 +----------------------------------------+-----------------------------------+
1904 | ``INTRINSIC_PREP_RERAISE_STAR`` | Calculates the |
1905 | | :exc:`ExceptionGroup` to raise |
1906 | | from a ``try-except*``. |
1907 +----------------------------------------+-----------------------------------+
1908 | ``INTRINSIC_TYPEVAR_WITH_BOUND`` | Creates a :class:`typing.TypeVar` |
1909 | | with a bound. |
1910 +----------------------------------------+-----------------------------------+
1911 | ``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS`` | Creates a |
1912 | | :class:`typing.TypeVar` with |
1913 | | constraints. |
1914 +----------------------------------------+-----------------------------------+
1915 | ``INTRINSIC_SET_FUNCTION_TYPE_PARAMS`` | Sets the ``__type_params__`` |
1916 | | attribute of a function. |
1917 +----------------------------------------+-----------------------------------+
1918
1919 .. versionadded:: 3.12
1920
1921
1922 .. opcode:: LOAD_SPECIAL
1923
1924 Performs special method lookup on ``STACK[-1]``.
1925 If ``type(STACK[-1]).__xxx__`` is a method, leave
1926 ``type(STACK[-1]).__xxx__; STACK[-1]`` on the stack.
1927 If ``type(STACK[-1]).__xxx__`` is not a method, leave
1928 ``STACK[-1].__xxx__; NULL`` on the stack.
1929
1930 .. versionadded:: 3.14
1931
1932
1933 **Pseudo-instructions**
1934
1935 These opcodes do not appear in Python bytecode. They are used by the compiler
1936 but are replaced by real opcodes or removed before bytecode is generated.
1937
1938 .. opcode:: SETUP_FINALLY (target)
1939
1940 Set up an exception handler for the following code block. If an exception
1941 occurs, the value stack level is restored to its current state and control
1942 is transferred to the exception handler at ``target``.
1943
1944
1945 .. opcode:: SETUP_CLEANUP (target)
1946
1947 Like ``SETUP_FINALLY``, but in case of an exception also pushes the last
1948 instruction (``lasti``) to the stack so that ``RERAISE`` can restore it.
1949 If an exception occurs, the value stack level and the last instruction on
1950 the frame are restored to their current state, and control is transferred
1951 to the exception handler at ``target``.
1952
1953
1954 .. opcode:: SETUP_WITH (target)
1955
1956 Like ``SETUP_CLEANUP``, but in case of an exception one more item is popped
1957 from the stack before control is transferred to the exception handler at
1958 ``target``.
1959
1960 This variant is used in :keyword:`with` and :keyword:`async with`
1961 constructs, which push the return value of the context manager's
1962 :meth:`~object.__enter__` or :meth:`~object.__aenter__` to the stack.
1963
1964
1965 .. opcode:: POP_BLOCK
1966
1967 Marks the end of the code block associated with the last ``SETUP_FINALLY``,
1968 ``SETUP_CLEANUP`` or ``SETUP_WITH``.
1969
1970
1971 .. opcode:: LOAD_CONST_IMMORTAL (consti)
1972
1973 Works as :opcode:`LOAD_CONST`, but is more efficient for immortal objects.
1974
1975
1976 .. opcode:: JUMP
1977 JUMP_NO_INTERRUPT
1978
1979 Undirected relative jump instructions which are replaced by their
1980 directed (forward/backward) counterparts by the assembler.
1981
1982 .. opcode:: JUMP_IF_TRUE
1983 JUMP_IF_FALSE
1984
1985 Conditional jumps which do not impact the stack. Replaced by the sequence
1986 ``COPY 1``, ``TO_BOOL``, ``POP_JUMP_IF_TRUE/FALSE``.
1987
1988 .. opcode:: LOAD_CLOSURE (i)
1989
1990 Pushes a reference to the cell contained in slot ``i`` of the "fast locals"
1991 storage.
1992
1993 Note that ``LOAD_CLOSURE`` is replaced with ``LOAD_FAST`` in the assembler.
1994
1995 .. versionchanged:: 3.13
1996 This opcode is now a pseudo-instruction.
1997
1998
1999 .. _opcode_collections:
2000
2001 Opcode collections
2002 ------------------
2003
2004 These collections are provided for automatic introspection of bytecode
2005 instructions:
2006
2007 .. versionchanged:: 3.12
2008 The collections now contain pseudo instructions and instrumented
2009 instructions as well. These are opcodes with values ``>= MIN_PSEUDO_OPCODE``
2010 and ``>= MIN_INSTRUMENTED_OPCODE``.
2011
2012 .. data:: opname
2013
2014 Sequence of operation names, indexable using the bytecode.
2015
2016
2017 .. data:: opmap
2018
2019 Dictionary mapping operation names to bytecodes.
2020
2021
2022 .. data:: cmp_op
2023
2024 Sequence of all compare operation names.
2025
2026
2027 .. data:: hasarg
2028
2029 Sequence of bytecodes that use their argument.
2030
2031 .. versionadded:: 3.12
2032
2033
2034 .. data:: hasconst
2035
2036 Sequence of bytecodes that access a constant.
2037
2038
2039 .. data:: hasfree
2040
2041 Sequence of bytecodes that access a :term:`free (closure) variable <closure variable>`.
2042 'free' in this context refers to names in the current scope that are
2043 referenced by inner scopes or names in outer scopes that are referenced
2044 from this scope. It does *not* include references to global or builtin scopes.
2045
2046
2047 .. data:: hasname
2048
2049 Sequence of bytecodes that access an attribute by name.
2050
2051
2052 .. data:: hasjump
2053
2054 Sequence of bytecodes that have a jump target. All jumps
2055 are relative.
2056
2057 .. versionadded:: 3.13
2058
2059 .. data:: haslocal
2060
2061 Sequence of bytecodes that access a local variable.
2062
2063
2064 .. data:: hascompare
2065
2066 Sequence of bytecodes of Boolean operations.
2067
2068 .. data:: hasexc
2069
2070 Sequence of bytecodes that set an exception handler.
2071
2072 .. versionadded:: 3.12
2073
2074
2075 .. data:: hasjrel
2076
2077 Sequence of bytecodes that have a relative jump target.
2078
2079 .. deprecated:: 3.13
2080 All jumps are now relative. Use :data:`hasjump`.
2081
2082
2083 .. data:: hasjabs
2084
2085 Sequence of bytecodes that have an absolute jump target.
2086
2087 .. deprecated:: 3.13
2088 All jumps are now relative. This list is empty.