rest25/library/dis.rst => rest262/library/dis.rst
f1
n2-:mod:`dis` --- Disassembler for Python byte code
n2+:mod:`dis` --- Disassembler for Python bytecode
3-================================================
3+===============================================
4
5.. module:: dis
n6-   :synopsis: Disassembler for Python byte code.
n6+   :synopsis: Disassembler for Python bytecode.
7
8
n9-The :mod:`dis` module supports the analysis of Python byte code by disassembling
n9+The :mod:`dis` module supports the analysis of Python :term:`bytecode` by disassembling
10it.  Since there is no Python assembler, this module defines the Python assembly
n11-language.  The Python byte code which this module takes as an input is defined
n11+language.  The Python bytecode which this module takes as an input is defined
12in the file  :file:`Include/opcode.h` and used by the compiler and the
13interpreter.
14
15Example: Given the function :func:`myfunc`::
16
17   def myfunc(alist):
18       return len(alist)
19
30The :mod:`dis` module defines the following functions and constants:
31
32
33.. function:: dis([bytesource])
34
35   Disassemble the *bytesource* object. *bytesource* can denote either a module, a
36   class, a method, a function, or a code object.   For a module, it disassembles
37   all functions.  For a class, it disassembles all methods.  For a single code
n38-   sequence, it prints one line per byte code instruction.  If no object is
n38+   sequence, it prints one line per bytecode instruction.  If no object is
39   provided, it disassembles the last traceback.
40
41
42.. function:: distb([tb])
43
44   Disassembles the top-of-stack function of a traceback, using the last traceback
45   if none was passed.  The instruction causing the exception is indicated.
46
47
48.. function:: disassemble(code[, lasti])
49
50   Disassembles a code object, indicating the last instruction if *lasti* was
51   provided.  The output is divided in the following columns:
52
n53-#. the line number, for the first instruction of each line
n53+   #. the line number, for the first instruction of each line
54- 
55-#. the current instruction, indicated as ``-->``,
54+   #. the current instruction, indicated as ``-->``,
56- 
57-#. a labelled instruction, indicated with ``>>``,
55+   #. a labelled instruction, indicated with ``>>``,
58- 
59-#. the address of the instruction,
56+   #. the address of the instruction,
60- 
61-#. the operation code name,
57+   #. the operation code name,
62- 
63-#. operation parameters, and
58+   #. operation parameters, and
64- 
65-#. interpretation of the parameters in parentheses.
59+   #. interpretation of the parameters in parentheses.
66
67   The parameter interpretation recognizes local and global variable names,
68   constant values, branch targets, and compare operators.
69
70
71.. function:: disco(code[, lasti])
72
73   A synonym for disassemble.  It is more convenient to type, and kept for
74   compatibility with earlier Python releases.
75
76
77.. data:: opname
78
n79-   Sequence of operation names, indexable using the byte code.
n73+   Sequence of operation names, indexable using the bytecode.
80
81
82.. data:: opmap
83
n84-   Dictionary mapping byte codes to operation names.
n78+   Dictionary mapping bytecodes to operation names.
85
86
87.. data:: cmp_op
88
89   Sequence of all compare operation names.
90
91
92.. data:: hasconst
93
n94-   Sequence of byte codes that have a constant parameter.
n88+   Sequence of bytecodes that have a constant parameter.
95
96
97.. data:: hasfree
98
n99-   Sequence of byte codes that access a free variable.
n93+   Sequence of bytecodes that access a free variable.
100
101
102.. data:: hasname
103
n104-   Sequence of byte codes that access an attribute by name.
n98+   Sequence of bytecodes that access an attribute by name.
105
106
107.. data:: hasjrel
108
n109-   Sequence of byte codes that have a relative jump target.
n103+   Sequence of bytecodes that have a relative jump target.
110
111
112.. data:: hasjabs
113
n114-   Sequence of byte codes that have an absolute jump target.
n108+   Sequence of bytecodes that have an absolute jump target.
115
116
117.. data:: haslocal
118
n119-   Sequence of byte codes that access a local variable.
n113+   Sequence of bytecodes that access a local variable.
120
121
122.. data:: hascompare
123
n124-   Sequence of byte codes of Boolean operations.
n118+   Sequence of bytecodes of Boolean operations.
125
126
127.. _bytecodes:
128
n129-Python Byte Code Instructions
n123+Python Bytecode Instructions
130------------------------------
124+----------------------------
131
n132-The Python compiler currently generates the following byte code instructions.
n126+The Python compiler currently generates the following bytecode instructions.
133
134
135.. opcode:: STOP_CODE ()
136
137   Indicates end-of-code to the compiler, not used by the interpreter.
138
139
140.. opcode:: NOP ()
184
185.. opcode:: UNARY_NOT ()
186
187   Implements ``TOS = not TOS``.
188
189
190.. opcode:: UNARY_CONVERT ()
191
n192-   Implements ``TOS = `TOS```.
n186+   Implements ``TOS = `TOS```.
193
194
195.. opcode:: UNARY_INVERT ()
196
197   Implements ``TOS = ~TOS``.
198
199
200.. opcode:: GET_ITER ()
483
484.. opcode:: RETURN_VALUE ()
485
486   Returns with TOS to the caller of the function.
487
488
489.. opcode:: YIELD_VALUE ()
490
n491-   Pops ``TOS`` and yields it from a generator.
n485+   Pops ``TOS`` and yields it from a :term:`generator`.
492
493
494.. opcode:: IMPORT_STAR ()
495
496   Loads all symbols not starting with ``'_'`` directly from the module TOS to the
497   local namespace. The module is popped after loading all names. This opcode
498   implements ``from module import *``.
499
517   with the outer-next block.
518
519
520.. opcode:: BUILD_CLASS ()
521
522   Creates a new class object.  TOS is the methods dictionary, TOS1 the tuple of
523   the names of the base classes, and TOS2 the class name.
524
n519+ 
520+.. opcode:: WITH_CLEANUP ()
521+ 
522+   Cleans up the stack when a :keyword:`with` statement block exits.  On top of
523+   the stack are 1--3 values indicating how/why the finally clause was entered:
524+ 
525+   * TOP = ``None``
526+   * (TOP, SECOND) = (``WHY_{RETURN,CONTINUE}``), retval
527+   * TOP = ``WHY_*``; no retval below it
528+   * (TOP, SECOND, THIRD) = exc_info()
529+ 
530+   Under them is EXIT, the context manager's :meth:`__exit__` bound method.
531+ 
532+   In the last case, ``EXIT(TOP, SECOND, THIRD)`` is called, otherwise
533+   ``EXIT(None, None, None)``.
534+ 
535+   EXIT is removed from the stack, leaving the values above it in the same
536+   order. In addition, if the stack represents an exception, *and* the function
537+   call returns a 'true' value, this information is "zapped", to prevent
538+   ``END_FINALLY`` from re-raising the exception.  (But non-local gotos should
539+   still be resumed.)
540+ 
541+   .. XXX explain the WHY stuff!
542+ 
543+ 
525All of the following opcodes expect arguments.  An argument is two bytes, with
526the more significant byte last.
527
n528- 
529.. opcode:: STORE_NAME (namei)
530
531   Implements ``name = TOS``. *namei* is the index of *name* in the attribute
n532-   :attr:`co_names` of the code object. The compiler tries to use ``STORE_LOCAL``
n550+   :attr:`co_names` of the code object. The compiler tries to use ``STORE_FAST``
533   or ``STORE_GLOBAL`` if possible.
534
535
536.. opcode:: DELETE_NAME (namei)
537
538   Implements ``del name``, where *namei* is the index into :attr:`co_names`
539   attribute of the code object.
540
541
542.. opcode:: UNPACK_SEQUENCE (count)
543
n544-   Unpacks TOS into *count* individual values, which are put onto the stack right-
n562+   Unpacks TOS into *count* individual values, which are put onto the stack
545-   to-left.
563+   right-to-left.
546- 
547-.. % \begin{opcodedesc}{UNPACK_LIST}{count}
548-.. % This opcode is obsolete.
549-.. % \end{opcodedesc}
550-.. % \begin{opcodedesc}{UNPACK_ARG}{count}
551-.. % This opcode is obsolete.
552-.. % \end{opcodedesc}
553
554
555.. opcode:: DUP_TOPX (count)
556
557   Duplicate *count* items, keeping them in the same order. Due to implementation
558   limits, *count* should be between 1 and 5 inclusive.
559
560
573
574   Works as ``STORE_NAME``, but stores the name as a global.
575
576
577.. opcode:: DELETE_GLOBAL (namei)
578
579   Works as ``DELETE_NAME``, but deletes a global name.
580
n581-.. % \begin{opcodedesc}{UNPACK_VARARG}{argc}
582-.. % This opcode is obsolete.
583-.. % \end{opcodedesc}
584- 
585
586.. opcode:: LOAD_CONST (consti)
587
588   Pushes ``co_consts[consti]`` onto the stack.
589
590
591.. opcode:: LOAD_NAME (namei)
592
599   tuple onto the stack.
600
601
602.. opcode:: BUILD_LIST (count)
603
604   Works as ``BUILD_TUPLE``, but creates a list.
605
606
n607-.. opcode:: BUILD_MAP (zero)
n614+.. opcode:: BUILD_MAP (count)
608
n609-   Pushes a new empty dictionary object onto the stack.  The argument is ignored
n616+   Pushes a new dictionary object onto the stack.  The dictionary is pre-sized
610-   and set to zero by the compiler.
617+   to hold *count* entries.
611
612
613.. opcode:: LOAD_ATTR (namei)
614
615   Replaces TOS with ``getattr(TOS, co_names[namei])``.
616
617
618.. opcode:: COMPARE_OP (opname)
619
620   Performs a Boolean operation.  The operation name can be found in
621   ``cmp_op[opname]``.
622
623
624.. opcode:: IMPORT_NAME (namei)
625
n626-   Imports the module ``co_names[namei]``.  The module object is pushed onto the
n633+   Imports the module ``co_names[namei]``.  TOS and TOS1 are popped and provide
627-   stack.  The current namespace is not affected: for a proper import statement, a
634+   the *fromlist* and *level* arguments of :func:`__import__`.  The module
628-   subsequent ``STORE_FAST`` instruction modifies the namespace.
635+   object is pushed onto the stack.  The current namespace is not affected:
636+   for a proper import statement, a subsequent ``STORE_FAST`` instruction
637+   modifies the namespace.
629
630
631.. opcode:: IMPORT_FROM (namei)
632
633   Loads the attribute ``co_names[namei]`` from the module found in TOS. The
634   resulting object is pushed onto the stack, to be subsequently stored by a
635   ``STORE_FAST`` instruction.
636
637
638.. opcode:: JUMP_FORWARD (delta)
639
n640-   Increments byte code counter by *delta*.
n649+   Increments bytecode counter by *delta*.
641
642
643.. opcode:: JUMP_IF_TRUE (delta)
644
n645-   If TOS is true, increment the byte code counter by *delta*.  TOS is left on the
n654+   If TOS is true, increment the bytecode counter by *delta*.  TOS is left on the
646   stack.
647
648
649.. opcode:: JUMP_IF_FALSE (delta)
650
n651-   If TOS is false, increment the byte code counter by *delta*.  TOS is not
n660+   If TOS is false, increment the bytecode counter by *delta*.  TOS is not
652   changed.
653
654
655.. opcode:: JUMP_ABSOLUTE (target)
656
n657-   Set byte code counter to *target*.
n666+   Set bytecode counter to *target*.
658
659
660.. opcode:: FOR_ITER (delta)
661
n662-   ``TOS`` is an iterator.  Call its :meth:`next` method.  If this yields a new
n671+   ``TOS`` is an :term:`iterator`.  Call its :meth:`next` method.  If this
663-   value, push it on the stack (leaving the iterator below it).  If the iterator
672+   yields a new value, push it on the stack (leaving the iterator below it).  If
664-   indicates it is exhausted  ``TOS`` is popped, and the byte code counter is
673+   the iterator indicates it is exhausted ``TOS`` is popped, and the bytecode
665-   incremented by *delta*.
674+   counter is incremented by *delta*.
666- 
667-.. % \begin{opcodedesc}{FOR_LOOP}{delta}
668-.. % This opcode is obsolete.
669-.. % \end{opcodedesc}
670-.. % \begin{opcodedesc}{LOAD_LOCAL}{namei}
671-.. % This opcode is obsolete.
672-.. % \end{opcodedesc}
673
674
675.. opcode:: LOAD_GLOBAL (namei)
676
677   Loads the global named ``co_names[namei]`` onto the stack.
n678- 
679-.. % \begin{opcodedesc}{SET_FUNC_ARGS}{argc}
680-.. % This opcode is obsolete.
681-.. % \end{opcodedesc}
682
683
684.. opcode:: SETUP_LOOP (delta)
685
686   Pushes a block for a loop onto the block stack.  The block spans from the
687   current instruction with a size of *delta* bytes.
688
689
693   to the first except block.
694
695
696.. opcode:: SETUP_FINALLY (delta)
697
698   Pushes a try block from a try-except clause onto the block stack. *delta* points
699   to the finally block.
700
n699+.. opcode:: STORE_MAP ()
700+ 
701+   Store a key and value pair in a dictionary.  Pops the key and value while leaving
702+   the dictionary on the stack.
701
702.. opcode:: LOAD_FAST (var_num)
703
704   Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
705
706
707.. opcode:: STORE_FAST (var_num)
708
748
749.. opcode:: CALL_FUNCTION (argc)
750
751   Calls a function.  The low byte of *argc* indicates the number of positional
752   parameters, the high byte the number of keyword parameters. On the stack, the
753   opcode finds the keyword parameters first.  For each keyword argument, the value
754   is on top of the key.  Below the keyword parameters, the positional parameters
755   are on the stack, with the right-most parameter on top.  Below the parameters,
n756-   the function object to call is on the stack.
n758+   the function object to call is on the stack.  Pops all function arguments, and
759+   the function itself off the stack, and pushes the return value.
757
758
759.. opcode:: MAKE_FUNCTION (argc)
760
761   Pushes a new function object on the stack.  TOS is the code associated with the
762   function.  The function object is defined to have *argc* default parameters,
763   which are found below TOS.
764
765
766.. opcode:: MAKE_CLOSURE (argc)
767
768   Creates a new function object, sets its *func_closure* slot, and pushes it on
n769-   the stack.  TOS is the code associated with the function. If the code object has
n772+   the stack.  TOS is the code associated with the function, TOS1 the tuple
770-   N free variables, the next N items on the stack are the cells for these
773+   containing cells for the closure's free variables.  The function also has
771-   variables.  The function also has *argc* default parameters, where are found
774+   *argc* default parameters, which are found below the cells.
772-   before the cells.
773
774
775.. opcode:: BUILD_SLICE (argc)
776
777   .. index:: builtin: slice
778
779   Pushes a slice object on the stack.  *argc* must be 2 or 3.  If it is 2,
780   ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
t781-   pushed. See the ``slice()`` built-in function for more information.
t783+   pushed. See the :func:`slice` built-in function for more information.
782
783
784.. opcode:: EXTENDED_ARG (ext)
785
786   Prefixes any opcode which has an argument too big to fit into the default two
787   bytes.  *ext* holds two additional bytes which, taken together with the
788   subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
789   most-significant bytes.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op