1 :mod:`dis` --- Disassembler for Python bytecode
2 ===============================================
5 :synopsis: Disassembler for Python bytecode.
7 **Source code:** :source:`Lib/dis.py`
11 The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
12 disassembling it. The CPython bytecode which this module takes as an
13 input is defined in the file :file:`Include/opcode.h` and used by the compiler
18 Bytecode is an implementation detail of the CPython interpreter! No
19 guarantees are made that bytecode will not be added, removed, or changed
20 between versions of Python. Use of this module should not be considered to
21 work across Python VMs or Python releases.
23 Example: Given the function :func:`myfunc`::
28 the following command can be used to get the disassembly of :func:`myfunc`::
31 2 0 LOAD_GLOBAL 0 (len)
36 (The "2" is a line number).
38 The :mod:`dis` module defines the following functions and constants:
41 .. function:: dis([bytesource])
43 Disassemble the *bytesource* object. *bytesource* can denote either a module, a
44 class, a method, a function, or a code object. For a module, it disassembles
45 all functions. For a class, it disassembles all methods. For a single code
46 sequence, it prints one line per bytecode instruction. If no object is
47 provided, it disassembles the last traceback.
50 .. function:: distb([tb])
52 Disassembles the top-of-stack function of a traceback, using the last traceback
53 if none was passed. The instruction causing the exception is indicated.
56 .. function:: disassemble(code[, lasti])
58 Disassembles a code object, indicating the last instruction if *lasti* was
59 provided. The output is divided in the following columns:
61 #. the line number, for the first instruction of each line
62 #. the current instruction, indicated as ``-->``,
63 #. a labelled instruction, indicated with ``>>``,
64 #. the address of the instruction,
65 #. the operation code name,
66 #. operation parameters, and
67 #. interpretation of the parameters in parentheses.
69 The parameter interpretation recognizes local and global variable names,
70 constant values, branch targets, and compare operators.
73 .. function:: disco(code[, lasti])
75 A synonym for :func:`disassemble`. It is more convenient to type, and kept
76 for compatibility with earlier Python releases.
79 .. function:: findlinestarts(code)
81 This generator function uses the ``co_firstlineno`` and ``co_lnotab``
82 attributes of the code object *code* to find the offsets which are starts of
83 lines in the source code. They are generated as ``(offset, lineno)`` pairs.
86 .. function:: findlabels(code)
88 Detect all offsets in the code object *code* which are jump targets, and
89 return a list of these offsets.
94 Sequence of operation names, indexable using the bytecode.
99 Dictionary mapping operation names to bytecodes.
104 Sequence of all compare operation names.
109 Sequence of bytecodes that have a constant parameter.
114 Sequence of bytecodes that access a free variable.
119 Sequence of bytecodes that access an attribute by name.
124 Sequence of bytecodes that have a relative jump target.
129 Sequence of bytecodes that have an absolute jump target.
134 Sequence of bytecodes that access a local variable.
139 Sequence of bytecodes of Boolean operations.
144 Python Bytecode Instructions
145 ----------------------------
147 The Python compiler currently generates the following bytecode instructions.
150 .. opcode:: STOP_CODE ()
152 Indicates end-of-code to the compiler, not used by the interpreter.
157 Do nothing code. Used as a placeholder by the bytecode optimizer.
160 .. opcode:: POP_TOP ()
162 Removes the top-of-stack (TOS) item.
165 .. opcode:: ROT_TWO ()
167 Swaps the two top-most stack items.
170 .. opcode:: ROT_THREE ()
172 Lifts second and third stack item one position up, moves top down to position
176 .. opcode:: ROT_FOUR ()
178 Lifts second, third and forth stack item one position up, moves top down to
182 .. opcode:: DUP_TOP ()
184 Duplicates the reference on top of the stack.
186 Unary Operations take the top of the stack, apply the operation, and push the
187 result back on the stack.
190 .. opcode:: UNARY_POSITIVE ()
192 Implements ``TOS = +TOS``.
195 .. opcode:: UNARY_NEGATIVE ()
197 Implements ``TOS = -TOS``.
200 .. opcode:: UNARY_NOT ()
202 Implements ``TOS = not TOS``.
205 .. opcode:: UNARY_CONVERT ()
207 Implements ``TOS = `TOS```.
210 .. opcode:: UNARY_INVERT ()
212 Implements ``TOS = ~TOS``.
215 .. opcode:: GET_ITER ()
217 Implements ``TOS = iter(TOS)``.
219 Binary operations remove the top of the stack (TOS) and the second top-most
220 stack item (TOS1) from the stack. They perform the operation, and put the
221 result back on the stack.
224 .. opcode:: BINARY_POWER ()
226 Implements ``TOS = TOS1 ** TOS``.
229 .. opcode:: BINARY_MULTIPLY ()
231 Implements ``TOS = TOS1 * TOS``.
234 .. opcode:: BINARY_DIVIDE ()
236 Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is not
240 .. opcode:: BINARY_FLOOR_DIVIDE ()
242 Implements ``TOS = TOS1 // TOS``.
245 .. opcode:: BINARY_TRUE_DIVIDE ()
247 Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is in
251 .. opcode:: BINARY_MODULO ()
253 Implements ``TOS = TOS1 % TOS``.
256 .. opcode:: BINARY_ADD ()
258 Implements ``TOS = TOS1 + TOS``.
261 .. opcode:: BINARY_SUBTRACT ()
263 Implements ``TOS = TOS1 - TOS``.
266 .. opcode:: BINARY_SUBSCR ()
268 Implements ``TOS = TOS1[TOS]``.
271 .. opcode:: BINARY_LSHIFT ()
273 Implements ``TOS = TOS1 << TOS``.
276 .. opcode:: BINARY_RSHIFT ()
278 Implements ``TOS = TOS1 >> TOS``.
281 .. opcode:: BINARY_AND ()
283 Implements ``TOS = TOS1 & TOS``.
286 .. opcode:: BINARY_XOR ()
288 Implements ``TOS = TOS1 ^ TOS``.
291 .. opcode:: BINARY_OR ()
293 Implements ``TOS = TOS1 | TOS``.
295 In-place operations are like binary operations, in that they remove TOS and
296 TOS1, and push the result back on the stack, but the operation is done in-place
297 when TOS1 supports it, and the resulting TOS may be (but does not have to be)
301 .. opcode:: INPLACE_POWER ()
303 Implements in-place ``TOS = TOS1 ** TOS``.
306 .. opcode:: INPLACE_MULTIPLY ()
308 Implements in-place ``TOS = TOS1 * TOS``.
311 .. opcode:: INPLACE_DIVIDE ()
313 Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
314 division`` is not in effect.
317 .. opcode:: INPLACE_FLOOR_DIVIDE ()
319 Implements in-place ``TOS = TOS1 // TOS``.
322 .. opcode:: INPLACE_TRUE_DIVIDE ()
324 Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
325 division`` is in effect.
328 .. opcode:: INPLACE_MODULO ()
330 Implements in-place ``TOS = TOS1 % TOS``.
333 .. opcode:: INPLACE_ADD ()
335 Implements in-place ``TOS = TOS1 + TOS``.
338 .. opcode:: INPLACE_SUBTRACT ()
340 Implements in-place ``TOS = TOS1 - TOS``.
343 .. opcode:: INPLACE_LSHIFT ()
345 Implements in-place ``TOS = TOS1 << TOS``.
348 .. opcode:: INPLACE_RSHIFT ()
350 Implements in-place ``TOS = TOS1 >> TOS``.
353 .. opcode:: INPLACE_AND ()
355 Implements in-place ``TOS = TOS1 & TOS``.
358 .. opcode:: INPLACE_XOR ()
360 Implements in-place ``TOS = TOS1 ^ TOS``.
363 .. opcode:: INPLACE_OR ()
365 Implements in-place ``TOS = TOS1 | TOS``.
367 The slice opcodes take up to three parameters.
370 .. opcode:: SLICE+0 ()
372 Implements ``TOS = TOS[:]``.
375 .. opcode:: SLICE+1 ()
377 Implements ``TOS = TOS1[TOS:]``.
380 .. opcode:: SLICE+2 ()
382 Implements ``TOS = TOS1[:TOS]``.
385 .. opcode:: SLICE+3 ()
387 Implements ``TOS = TOS2[TOS1:TOS]``.
389 Slice assignment needs even an additional parameter. As any statement, they put
390 nothing on the stack.
393 .. opcode:: STORE_SLICE+0 ()
395 Implements ``TOS[:] = TOS1``.
398 .. opcode:: STORE_SLICE+1 ()
400 Implements ``TOS1[TOS:] = TOS2``.
403 .. opcode:: STORE_SLICE+2 ()
405 Implements ``TOS1[:TOS] = TOS2``.
408 .. opcode:: STORE_SLICE+3 ()
410 Implements ``TOS2[TOS1:TOS] = TOS3``.
413 .. opcode:: DELETE_SLICE+0 ()
415 Implements ``del TOS[:]``.
418 .. opcode:: DELETE_SLICE+1 ()
420 Implements ``del TOS1[TOS:]``.
423 .. opcode:: DELETE_SLICE+2 ()
425 Implements ``del TOS1[:TOS]``.
428 .. opcode:: DELETE_SLICE+3 ()
430 Implements ``del TOS2[TOS1:TOS]``.
433 .. opcode:: STORE_SUBSCR ()
435 Implements ``TOS1[TOS] = TOS2``.
438 .. opcode:: DELETE_SUBSCR ()
440 Implements ``del TOS1[TOS]``.
442 Miscellaneous opcodes.
445 .. opcode:: PRINT_EXPR ()
447 Implements the expression statement for the interactive mode. TOS is removed
448 from the stack and printed. In non-interactive mode, an expression statement is
449 terminated with ``POP_STACK``.
452 .. opcode:: PRINT_ITEM ()
454 Prints TOS to the file-like object bound to ``sys.stdout``. There is one such
455 instruction for each item in the :keyword:`print` statement.
458 .. opcode:: PRINT_ITEM_TO ()
460 Like ``PRINT_ITEM``, but prints the item second from TOS to the file-like object
461 at TOS. This is used by the extended print statement.
464 .. opcode:: PRINT_NEWLINE ()
466 Prints a new line on ``sys.stdout``. This is generated as the last operation of
467 a :keyword:`print` statement, unless the statement ends with a comma.
470 .. opcode:: PRINT_NEWLINE_TO ()
472 Like ``PRINT_NEWLINE``, but prints the new line on the file-like object on the
473 TOS. This is used by the extended print statement.
476 .. opcode:: BREAK_LOOP ()
478 Terminates a loop due to a :keyword:`break` statement.
481 .. opcode:: CONTINUE_LOOP (target)
483 Continues a loop due to a :keyword:`continue` statement. *target* is the
484 address to jump to (which should be a ``FOR_ITER`` instruction).
487 .. opcode:: LIST_APPEND (i)
489 Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions.
490 While the appended value is popped off, the list object remains on the
491 stack so that it is available for further iterations of the loop.
494 .. opcode:: LOAD_LOCALS ()
496 Pushes a reference to the locals of the current scope on the stack. This is used
497 in the code for a class definition: After the class body is evaluated, the
498 locals are passed to the class definition.
501 .. opcode:: RETURN_VALUE ()
503 Returns with TOS to the caller of the function.
506 .. opcode:: YIELD_VALUE ()
508 Pops ``TOS`` and yields it from a :term:`generator`.
511 .. opcode:: IMPORT_STAR ()
513 Loads all symbols not starting with ``'_'`` directly from the module TOS to the
514 local namespace. The module is popped after loading all names. This opcode
515 implements ``from module import *``.
518 .. opcode:: EXEC_STMT ()
520 Implements ``exec TOS2,TOS1,TOS``. The compiler fills missing optional
521 parameters with ``None``.
524 .. opcode:: POP_BLOCK ()
526 Removes one block from the block stack. Per frame, there is a stack of blocks,
527 denoting nested loops, try statements, and such.
530 .. opcode:: END_FINALLY ()
532 Terminates a :keyword:`finally` clause. The interpreter recalls whether the
533 exception has to be re-raised, or whether the function returns, and continues
534 with the outer-next block.
537 .. opcode:: BUILD_CLASS ()
539 Creates a new class object. TOS is the methods dictionary, TOS1 the tuple of
540 the names of the base classes, and TOS2 the class name.
543 .. opcode:: SETUP_WITH (delta)
545 This opcode performs several operations before a with block starts. First,
546 it loads :meth:`~object.__exit__` from the context manager and pushes it onto
547 the stack for later use by :opcode:`WITH_CLEANUP`. Then,
548 :meth:`~object.__enter__` is called, and a finally block pointing to *delta*
549 is pushed. Finally, the result of calling the enter method is pushed onto
550 the stack. The next opcode will either ignore it (:opcode:`POP_TOP`), or
551 store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or
552 :opcode:`UNPACK_SEQUENCE`).
555 .. opcode:: WITH_CLEANUP ()
557 Cleans up the stack when a :keyword:`with` statement block exits. On top of
558 the stack are 1--3 values indicating how/why the finally clause was entered:
561 * (TOP, SECOND) = (``WHY_{RETURN,CONTINUE}``), retval
562 * TOP = ``WHY_*``; no retval below it
563 * (TOP, SECOND, THIRD) = exc_info()
565 Under them is EXIT, the context manager's :meth:`__exit__` bound method.
567 In the last case, ``EXIT(TOP, SECOND, THIRD)`` is called, otherwise
568 ``EXIT(None, None, None)``.
570 EXIT is removed from the stack, leaving the values above it in the same
571 order. In addition, if the stack represents an exception, *and* the function
572 call returns a 'true' value, this information is "zapped", to prevent
573 ``END_FINALLY`` from re-raising the exception. (But non-local gotos should
576 .. XXX explain the WHY stuff!
579 All of the following opcodes expect arguments. An argument is two bytes, with
580 the more significant byte last.
582 .. opcode:: STORE_NAME (namei)
584 Implements ``name = TOS``. *namei* is the index of *name* in the attribute
585 :attr:`co_names` of the code object. The compiler tries to use ``STORE_FAST``
586 or ``STORE_GLOBAL`` if possible.
589 .. opcode:: DELETE_NAME (namei)
591 Implements ``del name``, where *namei* is the index into :attr:`co_names`
592 attribute of the code object.
595 .. opcode:: UNPACK_SEQUENCE (count)
597 Unpacks TOS into *count* individual values, which are put onto the stack
601 .. opcode:: DUP_TOPX (count)
603 Duplicate *count* items, keeping them in the same order. Due to implementation
604 limits, *count* should be between 1 and 5 inclusive.
607 .. opcode:: STORE_ATTR (namei)
609 Implements ``TOS.name = TOS1``, where *namei* is the index of name in
613 .. opcode:: DELETE_ATTR (namei)
615 Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
618 .. opcode:: STORE_GLOBAL (namei)
620 Works as ``STORE_NAME``, but stores the name as a global.
623 .. opcode:: DELETE_GLOBAL (namei)
625 Works as ``DELETE_NAME``, but deletes a global name.
628 .. opcode:: LOAD_CONST (consti)
630 Pushes ``co_consts[consti]`` onto the stack.
633 .. opcode:: LOAD_NAME (namei)
635 Pushes the value associated with ``co_names[namei]`` onto the stack.
638 .. opcode:: BUILD_TUPLE (count)
640 Creates a tuple consuming *count* items from the stack, and pushes the resulting
641 tuple onto the stack.
644 .. opcode:: BUILD_LIST (count)
646 Works as ``BUILD_TUPLE``, but creates a list.
649 .. opcode:: BUILD_MAP (count)
651 Pushes a new dictionary object onto the stack. The dictionary is pre-sized
652 to hold *count* entries.
655 .. opcode:: LOAD_ATTR (namei)
657 Replaces TOS with ``getattr(TOS, co_names[namei])``.
660 .. opcode:: COMPARE_OP (opname)
662 Performs a Boolean operation. The operation name can be found in
666 .. opcode:: IMPORT_NAME (namei)
668 Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide
669 the *fromlist* and *level* arguments of :func:`__import__`. The module
670 object is pushed onto the stack. The current namespace is not affected:
671 for a proper import statement, a subsequent ``STORE_FAST`` instruction
672 modifies the namespace.
675 .. opcode:: IMPORT_FROM (namei)
677 Loads the attribute ``co_names[namei]`` from the module found in TOS. The
678 resulting object is pushed onto the stack, to be subsequently stored by a
679 ``STORE_FAST`` instruction.
682 .. opcode:: JUMP_FORWARD (delta)
684 Increments bytecode counter by *delta*.
687 .. opcode:: POP_JUMP_IF_TRUE (target)
689 If TOS is true, sets the bytecode counter to *target*. TOS is popped.
692 .. opcode:: POP_JUMP_IF_FALSE (target)
694 If TOS is false, sets the bytecode counter to *target*. TOS is popped.
697 .. opcode:: JUMP_IF_TRUE_OR_POP (target)
699 If TOS is true, sets the bytecode counter to *target* and leaves TOS
700 on the stack. Otherwise (TOS is false), TOS is popped.
703 .. opcode:: JUMP_IF_FALSE_OR_POP (target)
705 If TOS is false, sets the bytecode counter to *target* and leaves
706 TOS on the stack. Otherwise (TOS is true), TOS is popped.
709 .. opcode:: JUMP_ABSOLUTE (target)
711 Set bytecode counter to *target*.
714 .. opcode:: FOR_ITER (delta)
716 ``TOS`` is an :term:`iterator`. Call its :meth:`!next` method. If this
717 yields a new value, push it on the stack (leaving the iterator below it). If
718 the iterator indicates it is exhausted ``TOS`` is popped, and the bytecode
719 counter is incremented by *delta*.
722 .. opcode:: LOAD_GLOBAL (namei)
724 Loads the global named ``co_names[namei]`` onto the stack.
727 .. opcode:: SETUP_LOOP (delta)
729 Pushes a block for a loop onto the block stack. The block spans from the
730 current instruction with a size of *delta* bytes.
733 .. opcode:: SETUP_EXCEPT (delta)
735 Pushes a try block from a try-except clause onto the block stack. *delta* points
736 to the first except block.
739 .. opcode:: SETUP_FINALLY (delta)
741 Pushes a try block from a try-except clause onto the block stack. *delta* points
742 to the finally block.
744 .. opcode:: STORE_MAP ()
746 Store a key and value pair in a dictionary. Pops the key and value while leaving
747 the dictionary on the stack.
749 .. opcode:: LOAD_FAST (var_num)
751 Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
754 .. opcode:: STORE_FAST (var_num)
756 Stores TOS into the local ``co_varnames[var_num]``.
759 .. opcode:: DELETE_FAST (var_num)
761 Deletes local ``co_varnames[var_num]``.
764 .. opcode:: LOAD_CLOSURE (i)
766 Pushes a reference to the cell contained in slot *i* of the cell and free
767 variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is
768 less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
772 .. opcode:: LOAD_DEREF (i)
774 Loads the cell contained in slot *i* of the cell and free variable storage.
775 Pushes a reference to the object the cell contains on the stack.
778 .. opcode:: STORE_DEREF (i)
780 Stores TOS into the cell contained in slot *i* of the cell and free variable
784 .. opcode:: SET_LINENO (lineno)
786 This opcode is obsolete.
789 .. opcode:: RAISE_VARARGS (argc)
791 Raises an exception. *argc* indicates the number of parameters to the raise
792 statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
793 the parameter as TOS1, and the exception as TOS.
796 .. opcode:: CALL_FUNCTION (argc)
798 Calls a function. The low byte of *argc* indicates the number of positional
799 parameters, the high byte the number of keyword parameters. On the stack, the
800 opcode finds the keyword parameters first. For each keyword argument, the value
801 is on top of the key. Below the keyword parameters, the positional parameters
802 are on the stack, with the right-most parameter on top. Below the parameters,
803 the function object to call is on the stack. Pops all function arguments, and
804 the function itself off the stack, and pushes the return value.
807 .. opcode:: MAKE_FUNCTION (argc)
809 Pushes a new function object on the stack. TOS is the code associated with the
810 function. The function object is defined to have *argc* default parameters,
811 which are found below TOS.
814 .. opcode:: MAKE_CLOSURE (argc)
816 Creates a new function object, sets its *func_closure* slot, and pushes it on
817 the stack. TOS is the code associated with the function, TOS1 the tuple
818 containing cells for the closure's free variables. The function also has
819 *argc* default parameters, which are found below the cells.
822 .. opcode:: BUILD_SLICE (argc)
824 .. index:: builtin: slice
826 Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
827 ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
828 pushed. See the :func:`slice` built-in function for more information.
831 .. opcode:: EXTENDED_ARG (ext)
833 Prefixes any opcode which has an argument too big to fit into the default two
834 bytes. *ext* holds two additional bytes which, taken together with the
835 subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
836 most-significant bytes.
839 .. opcode:: CALL_FUNCTION_VAR (argc)
841 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
842 on the stack contains the variable argument list, followed by keyword and
843 positional arguments.
846 .. opcode:: CALL_FUNCTION_KW (argc)
848 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element
849 on the stack contains the keyword arguments dictionary, followed by explicit
850 keyword and positional arguments.
853 .. opcode:: CALL_FUNCTION_VAR_KW (argc)
855 Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top
856 element on the stack contains the keyword arguments dictionary, followed by the
857 variable-arguments tuple, followed by explicit keyword and positional arguments.
860 .. opcode:: HAVE_ARGUMENT ()
862 This is not really an opcode. It identifies the dividing line between opcodes
863 which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=