| \section{\module{dis} --- |
| Disassembler.} |
| \declaremodule{standard}{dis} |
| |
| \modulesynopsis{Disassembler.} |
| |
| |
| The \module{dis} module supports the analysis of Python byte code by |
| disassembling it. Since there is no Python assembler, this module |
| defines the Python assembly language. The Python byte code which |
| this module takes as an input is defined in the file |
| \file{Include/opcode.h} and used by the compiler and the interpreter. |
| |
| Example: Given the function \function{myfunc}: |
| |
| \begin{verbatim} |
| def myfunc(alist): |
| return len(alist) |
| \end{verbatim} |
| |
| the following command can be used to get the disassembly of |
| \function{myfunc()}: |
| |
| \begin{verbatim} |
| >>> dis.dis(myfunc) |
| 0 SET_LINENO 1 |
| |
| 3 SET_LINENO 2 |
| 6 LOAD_GLOBAL 0 (len) |
| 9 LOAD_FAST 0 (alist) |
| 12 CALL_FUNCTION 1 |
| 15 RETURN_VALUE |
| 16 LOAD_CONST 0 (None) |
| 19 RETURN_VALUE |
| \end{verbatim} |
| |
| The \module{dis} module defines the following functions: |
| |
| \begin{funcdesc}{dis}{\optional{bytesource}} |
| Disassemble the \var{bytesource} object. \var{bytesource} can denote |
| either a class, a method, a function, or a code object. For a class, |
| it disassembles all methods. For a single code sequence, it prints |
| one line per byte code instruction. If no object is provided, it |
| disassembles the last traceback. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{distb}{\optional{tb}} |
| Disassembles the top-of-stack function of a traceback, using the last |
| traceback if none was passed. The instruction causing the exception |
| is indicated. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{disassemble}{code\optional{, lasti}} |
| Disassembles a code object, indicating the last instruction if \var{lasti} |
| was provided. The output is divided in the following columns: |
| |
| \begin{enumerate} |
| \item the current instruction, indicated as \samp{-->}, |
| \item a labelled instruction, indicated with \samp{>>}, |
| \item the address of the instruction, |
| \item the operation code name, |
| \item operation parameters, and |
| \item interpretation of the parameters in parentheses. |
| \end{enumerate} |
| |
| The parameter interpretation recognizes local and global |
| variable names, constant values, branch targets, and compare |
| operators. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{disco}{code\optional{, lasti}} |
| A synonym for disassemble. It is more convenient to type, and kept |
| for compatibility with earlier Python releases. |
| \end{funcdesc} |
| |
| \begin{datadesc}{opname} |
| Sequence of a operation names, indexable using the byte code. |
| \end{datadesc} |
| |
| \begin{datadesc}{cmp_op} |
| Sequence of all compare operation names. |
| \end{datadesc} |
| |
| \begin{datadesc}{hasconst} |
| Sequence of byte codes that have a constant parameter. |
| \end{datadesc} |
| |
| \begin{datadesc}{hasname} |
| Sequence of byte codes that access a attribute by name. |
| \end{datadesc} |
| |
| \begin{datadesc}{hasjrel} |
| Sequence of byte codes that have a relative jump target. |
| \end{datadesc} |
| |
| \begin{datadesc}{hasjabs} |
| Sequence of byte codes that have an absolute jump target. |
| \end{datadesc} |
| |
| \begin{datadesc}{haslocal} |
| Sequence of byte codes that access a a local variable. |
| \end{datadesc} |
| |
| \begin{datadesc}{hascompare} |
| Sequence of byte codes of boolean operations. |
| \end{datadesc} |
| |
| \subsection{Python Byte Code Instructions} |
| \label{bytecodes} |
| |
| The Python compiler currently generates the following byte code |
| instructions. |
| |
| \setindexsubitem{(byte code insns)} |
| |
| \begin{opcodedesc}{STOP_CODE}{} |
| Indicates end-of-code to the compiler, not used by the interpreter. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{POP_TOP}{} |
| Removes the top-of-stack (TOS) item. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{ROT_TWO}{} |
| Swaps the two top-most stack items. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{ROT_THREE}{} |
| Lifts second and third stack item one position up, moves top down |
| to position three. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DUP_TOP}{} |
| Duplicates the reference on top of the stack. |
| \end{opcodedesc} |
| |
| Unary Operations take the top of the stack, apply the operation, and |
| push the result back on the stack. |
| |
| \begin{opcodedesc}{UNARY_POSITIVE}{} |
| Implements \code{TOS = +TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{UNARY_NEG}{} |
| Implements \code{TOS = -TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{UNARY_NOT}{} |
| Implements \code{TOS = not TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{UNARY_CONVERT}{} |
| Implements \code{TOS = `TOS`}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{UNARY_INVERT}{} |
| Implements \code{TOS = \~{}TOS}. |
| \end{opcodedesc} |
| |
| Binary operations remove the top of the stack (TOS) and the second top-most |
| stack item (TOS1) from the stack. They perform the operation, and put the |
| result back on the stack. |
| |
| \begin{opcodedesc}{BINARY_POWER}{} |
| Implements \code{TOS = TOS1 ** TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_MULTIPLY}{} |
| Implements \code{TOS = TOS1 * TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_DIVIDE}{} |
| Implements \code{TOS = TOS1 / TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_MODULO}{} |
| Implements \code{TOS = TOS1 \%{} TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_ADD}{} |
| Implements \code{TOS = TOS1 + TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_SUBTRACT}{} |
| Implements \code{TOS = TOS1 - TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_SUBSCR}{} |
| Implements \code{TOS = TOS1[TOS]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_LSHIFT}{} |
| Implements \code{TOS = TOS1 << TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_RSHIFT}{} |
| Implements \code{TOS = TOS1 >> TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_AND}{} |
| Implements \code{TOS = TOS1 \&\ TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_XOR}{} |
| Implements \code{TOS = TOS1 \^\ TOS}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BINARY_OR}{} |
| Implements \code{TOS = TOS1 | TOS}. |
| \end{opcodedesc} |
| |
| The slice opcodes take up to three parameters. |
| |
| \begin{opcodedesc}{SLICE+0}{} |
| Implements \code{TOS = TOS[:]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{SLICE+1}{} |
| Implements \code{TOS = TOS1[TOS:]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{SLICE+2}{} |
| Implements \code{TOS = TOS1[:TOS1]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{SLICE+3}{} |
| Implements \code{TOS = TOS2[TOS1:TOS]}. |
| \end{opcodedesc} |
| |
| Slice assignment needs even an additional parameter. As any statement, |
| they put nothing on the stack. |
| |
| \begin{opcodedesc}{STORE_SLICE+0}{} |
| Implements \code{TOS[:] = TOS1}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{STORE_SLICE+1}{} |
| Implements \code{TOS1[TOS:] = TOS2}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{STORE_SLICE+2}{} |
| Implements \code{TOS1[:TOS] = TOS2}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{STORE_SLICE+3}{} |
| Implements \code{TOS2[TOS1:TOS] = TOS3}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_SLICE+0}{} |
| Implements \code{del TOS[:]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_SLICE+1}{} |
| Implements \code{del TOS1[TOS:]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_SLICE+2}{} |
| Implements \code{del TOS1[:TOS]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_SLICE+3}{} |
| Implements \code{del TOS2[TOS1:TOS]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{STORE_SUBSCR}{} |
| Implements \code{TOS1[TOS] = TOS2}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_SUBSCR}{} |
| Implements \code{del TOS1[TOS]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{PRINT_EXPR}{} |
| Implements the expression statement for the interactive mode. TOS is |
| removed from the stack and printed. In non-interactive mode, an |
| expression statement is terminated with \code{POP_STACK}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{PRINT_ITEM}{} |
| Prints TOS. There is one such instruction for |
| each item in the print statement. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{PRINT_NEWLINE}{} |
| Prints a new line on \code{sys.stdout}. This is generated as the |
| last operation of a print statement, unless the statement ends |
| with a comma. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BREAK_LOOP}{} |
| Terminates a loop due to a break statement. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{LOAD_LOCALS}{} |
| Pushes a reference to the locals of the current scope on the stack. |
| This is used in the code for a class definition: After the class body |
| is evaluated, the locals are passed to the class definition. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{RETURN_VALUE}{} |
| Returns with TOS to the caller of the function. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{EXEC_STMT}{} |
| Implements \code{exec TOS2,TOS1,TOS}. The compiler fills |
| missing optional parameters with None. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{POP_BLOCK}{} |
| Removes one block from the block stack. Per frame, there is a |
| stack of blocks, denoting nested loops, try statements, and such. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{END_FINALLY}{} |
| Terminates a finally-block. The interpreter recalls whether the |
| exception has to be re-raised, or whether the function returns, |
| and continues with the outer-next block. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BUILD_CLASS}{} |
| Creates a new class object. TOS is the methods dictionary, TOS1 |
| the tuple of the names of the base classes, and TOS2 the class name. |
| \end{opcodedesc} |
| |
| All of the following opcodes expect arguments. An argument is two |
| bytes, with the more significant byte last. |
| |
| \begin{opcodedesc}{STORE_NAME}{namei} |
| Implements \code{name = TOS}. \var{namei} is the index of \var{name} |
| in the attribute \member{co_names} of the code object. |
| The compiler tries to use \code{STORE_LOCAL} or \code{STORE_GLOBAL} |
| if possible. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_NAME}{namei} |
| Implements \code{del name}, where \var{namei} is the index into |
| \member{co_names} attribute of the code object. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{UNPACK_SEQUENCE}{count} |
| Unpacks TOS into \var{count} individual values, which are put onto |
| the stack right-to-left. |
| \end{opcodedesc} |
| |
| %\begin{opcodedesc}{UNPACK_LIST}{count} |
| %This opcode is obsolete. |
| %\end{opcodedesc} |
| |
| %\begin{opcodedesc}{UNPACK_ARG}{count} |
| %This opcode is obsolete. |
| %\end{opcodedesc} |
| |
| \begin{opcodedesc}{STORE_ATTR}{namei} |
| Implements \code{TOS.name = TOS1}, where \var{namei} is the index |
| of name in \member{co_names}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_ATTR}{namei} |
| Implements \code{del TOS.name}, using \var{namei} as index into |
| \member{co_names}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{STORE_GLOBAL}{namei} |
| Works as \code{STORE_NAME}, but stores the name as a global. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_GLOBAL}{namei} |
| Works as \code{DELETE_NAME}, but deletes a global name. |
| \end{opcodedesc} |
| |
| %\begin{opcodedesc}{UNPACK_VARARG}{argc} |
| %This opcode is obsolete. |
| %\end{opcodedesc} |
| |
| \begin{opcodedesc}{LOAD_CONST}{consti} |
| Pushes \samp{co_consts[\var{consti}]} onto the stack. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{LOAD_NAME}{namei} |
| Pushes the value associated with \samp{co_names[\var{namei}]} onto the stack. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BUILD_TUPLE}{count} |
| Creates a tuple consuming \var{count} items from the stack, and pushes |
| the resulting tuple onto the stack. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BUILD_LIST}{count} |
| Works as \code{BUILD_TUPLE}, but creates a list. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BUILD_MAP}{zero} |
| Pushes an empty dictionary object onto the stack. The argument is ignored |
| and set to zero by the compiler. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{LOAD_ATTR}{namei} |
| Replaces TOS with \code{getattr(TOS,co_names[\var{namei}]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{COMPARE_OP}{opname} |
| Performs a boolean operation. The operation name can be found |
| in \code{cmp_op[\var{opname}]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{IMPORT_NAME}{namei} |
| Imports the module \code{co_names[\var{namei}]}. The module object is |
| pushed onto the stack. The current name space is not affected: for a |
| proper import statement, a subsequent \code{STORE_FAST} instruction |
| modifies the name space. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{IMPORT_FROM}{namei} |
| Imports the attribute \code{co_names[\var{namei}]}. The module to import |
| from is found in TOS and left there. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{JUMP_FORWARD}{delta} |
| Increments byte code counter by \var{delta}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{JUMP_IF_TRUE}{delta} |
| If TOS is true, increment the byte code counter by \var{delta}. TOS is |
| left on the stack. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{JUMP_IF_FALSE}{delta} |
| If TOS is false, increment the byte code counter by \var{delta}. TOS |
| is not changed. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{JUMP_ABSOLUTE}{target} |
| Set byte code counter to \var{target}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{FOR_LOOP}{delta} |
| Iterate over a sequence. TOS is the current index, TOS1 the sequence. |
| First, the next element is computed. If the sequence is exhausted, |
| increment byte code counter by \var{delta}. Otherwise, push the |
| sequence, the incremented counter, and the current item onto the stack. |
| \end{opcodedesc} |
| |
| %\begin{opcodedesc}{LOAD_LOCAL}{namei} |
| %This opcode is obsolete. |
| %\end{opcodedesc} |
| |
| \begin{opcodedesc}{LOAD_GLOBAL}{namei} |
| Loads the global named \code{co_names[\var{namei}]} onto the stack. |
| \end{opcodedesc} |
| |
| %\begin{opcodedesc}{SET_FUNC_ARGS}{argc} |
| %This opcode is obsolete. |
| %\end{opcodedesc} |
| |
| \begin{opcodedesc}{SETUP_LOOP}{delta} |
| Pushes a block for a loop onto the block stack. The block spans |
| from the current instruction with a size of \var{delta} bytes. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{SETUP_EXCEPT}{delta} |
| Pushes a try block from a try-except clause onto the block stack. |
| \var{delta} points to the first except block. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{SETUP_FINALLY}{delta} |
| Pushes a try block from a try-except clause onto the block stack. |
| \var{delta} points to the finally block. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{LOAD_FAST}{var_num} |
| Pushes a reference to the local \code{co_varnames[\var{var_num}]} onto |
| the stack. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{STORE_FAST}{var_num} |
| Stores TOS into the local \code{co_varnames[\var{var_num}]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{DELETE_FAST}{var_num} |
| Deletes local \code{co_varnames[\var{var_num}]}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{SET_LINENO}{lineno} |
| Sets the current line number to \var{lineno}. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{RAISE_VARARGS}{argc} |
| Raises an exception. \var{argc} indicates the number of parameters |
| to the raise statement, ranging from 1 to 3. The handler will find |
| the traceback as TOS2, the parameter as TOS1, and the exception |
| as TOS. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{CALL_FUNCTION}{argc} |
| Calls a function. The low byte of \var{argc} indicates the number of |
| positional parameters, the high byte the number of keyword parameters. |
| On the stack, the opcode finds the keyword parameters first. For each |
| keyword argument, the value is on top of the key. Below the keyword |
| parameters, the positional parameters are on the stack, with the |
| right-most parameter on top. Below the parameters, the function object |
| to call is on the stack. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{MAKE_FUNCTION}{argc} |
| Pushes a new function object on the stack. TOS is the code associated |
| with the function. The function object is defined to have \var{argc} |
| default parameters, which are found below TOS. |
| \end{opcodedesc} |
| |
| \begin{opcodedesc}{BUILD_SLICE}{argc} |
| Pushes a slice object on the stack. \var{argc} must be 2 or 3. If it |
| is 2, \code{slice(TOS1, TOS)} is pushed; if it is 3, |
| \code{slice(TOS2, TOS1, TOS)} is pushed. |
| See the \code{slice()}\bifuncindex{slice} built-in function. |
| \end{opcodedesc} |