Docu for dis.py, written by Martin von Loewis.

1 files changed, 524 insertions, 0 deletions

diff --git a/Doc/libdis.tex b/Doc/libdis.tex
new file mode 100644
index 0000000..959c80f
--- /dev/null
+++ b/Doc/libdis.tex
@@ -0,0 +1,524 @@
+\section{Standard module \sectcode{dis}}	% If implemented in Python
+\stmodindex{dis}
+
+\label{module-dis}
+
+The \code{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 
+\code{Include/opcode.h} and used by the compiler and the interpreter.
+
+Example: Given the function myfunc
+
+\bcode\begin{verbatim}
+def myfunc(alist):
+  return len(alist)
+\end{verbatim}\ecode
+
+the following command can be used to get the disassembly of 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 \code{dis} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module dis)}
+
+% ---- 3.2. ----
+% For each function, use a ``funcdesc'' block.  This has exactly two
+% parameters (each parameters is contained in a set of curly braces):
+% the first parameter is the function name (this automatically
+% generates an index entry); the second parameter is the function's
+% argument list.  If there are no arguments, use an empty pair of
+% curly braces.  If there is more than one argument, separate the
+% arguments with backslash-comma.  Optional parts of the parameter
+% list are contained in \optional{...} (this generates a set of square
+% brackets around its parameter).  Arguments are automatically set in
+% italics in the parameter list.  Each argument should be mentioned at
+% least once in the description; each usage (even inside \code{...})
+% should be enclosed in \var{...}.
+
+\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{itemize}
+\item the current instruction, indicated as \code{-->},
+\item a labelled instruction, indicated with \code{>>},
+\item the address of the instruction,
+\item the operation code name,
+\item operation parameters, and
+\item interpretation of the parameters in parentheses.
+\end{itemize}
+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}
+
+The Python compiler currently generates the following byte code
+instructions.
+
+\renewcommand{\indexsubitem}{(byte code insns)}
+
+\begin{funcdesc}{STOP_CODE}{}
+Indicates end-of-code to the compiler, not used by the interpreter.
+\end{funcdesc}
+
+\begin{funcdesc}{POP_TOP}{}
+Removes the top-of-stack (TOS) item.
+\end{funcdesc}
+
+\begin{funcdesc}{ROT_TWO}{}
+Swaps the two top-most stack items.
+\end{funcdesc}
+
+\begin{funcdesc}{ROT_THREE}{}
+Lifts second and third stack item on position up, moves top down
+to position three.
+\end{funcdesc}
+
+\begin{funcdesc}{DUP_TOP}{}
+Duplicates the reference on top of the stack.
+\end{funcdesc}
+
+Unary Operations take the top of the stack, apply the operation, and
+push the result back on the stack.
+
+\begin{funcdesc}{UNARY_POSITIVE}{}
+Implements \code{TOS = +TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{UNARY_NEG}{}
+Implements \code{TOS = -TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{UNARY_NOT}{}
+Implements \code{TOS = not TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{UNARY_CONVERT}{}
+Implements \code{TOS = `TOS`}.
+\end{funcdesc}
+
+\begin{funcdesc}{UNARY_INVERT}{}
+Implements \code{TOS = ~TOS}.
+\end{funcdesc}
+
+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{funcdesc}{BINARY_POWER}{}
+Implements \code{TOS = TOS1 ** TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_MULTIPLY}{}
+Implements \code{TOS = TOS1 * TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_DIVIDE}{}
+Implements \code{TOS = TOS1 / TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_MODULO}{}
+Implements \code{TOS = TOS1 \% TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_ADD}{}
+Implements \code{TOS = TOS1 + TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_SUBTRACT}{}
+Implements \code{TOS = TOS1 - TOS}.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_SUBSCR}{}
+Implements \code{TOS = TOS1[TOS] }.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_LSHIFT}{}
+Implements \code{TOS = TOS1 << TOS }.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_RSHIFT}{}
+Implements \code{TOS = TOS1 << TOS }.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_AND}{}
+Implements \code{TOS = TOS1 and TOS }.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_XOR}{}
+Implements \code{TOS = TOS1 \^{ }TOS }.
+\end{funcdesc}
+
+\begin{funcdesc}{BINARY_OR}{}
+Implements \code{TOS = TOS1 or TOS }.
+\end{funcdesc}
+
+The slice opcodes take up to three parameters.
+
+\begin{funcdesc}{SLICE+0}{}
+Implements \code{TOS = TOS[:]}.
+\end{funcdesc}
+
+\begin{funcdesc}{SLICE+1}{}
+Implements \code{TOS = TOS1[TOS:]}.
+\end{funcdesc}
+
+\begin{funcdesc}{SLICE+2}{}
+Implements \code{TOS = TOS1[:TOS1]}.
+\end{funcdesc}
+
+\begin{funcdesc}{SLICE+3}{}
+Implements \code{TOS = TOS2[TOS1:TOS]}.
+\end{funcdesc}
+
+Slice assignment needs even an additional parameter.  As any statement,
+they put nothing on the stack.
+
+\begin{funcdesc}{STORE_SLICE+0}{}
+Implements \code{TOS[:]=TOS1}.
+\end{funcdesc}
+
+\begin{funcdesc}{STORE_SLICE+1}{}
+Implements \code{TOS1[TOS:]=TOS2}.
+\end{funcdesc}
+
+\begin{funcdesc}{STORE_SLICE+2}{}
+Implements \code{TOS1[:TOS]=TOS2}.
+\end{funcdesc}
+
+\begin{funcdesc}{STORE_SLICE+3}{}
+Implements \code{TOS2[TOS1:TOS]=TOS3}.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_SLICE+0}{}
+Implements \code{del TOS[:]}.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_SLICE+1}{}
+Implements \code{del TOS1[TOS:]}.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_SLICE+2}{}
+Implements \code{del TOS1[:TOS]}.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_SLICE+3}{}
+Implements \code{del TOS2[TOS1:TOS]}.
+\end{funcdesc}
+
+\begin{funcdesc}{STORE_SUBSCR}{}
+Implements \code{TOS1[TOS]=TOS2}.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_SUBSCR}{}
+Implements \code{del TOS1[TOS]}.
+\end{funcdesc}
+
+\begin{funcdesc}{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 POP_STACK.
+\end{funcdesc}
+
+\begin{funcdesc}{PRINT_ITEM}{}
+Prints TOS.  There is one such instruction for
+each item in the print statement.
+\end{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{BREAK_LOOP}{}
+Terminates a loop due to a break statement.
+\end{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{RETURN_VALUE}{}
+Returns with TOS to the caller of the function.
+\end{funcdesc}
+
+\begin{funcdesc}{EXEC_STMT}{}
+Implements \code{exec TOS2,TOS1,TOS}.  The compiler fills
+missing optional parameters with None.
+\end{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+All of the following opcodes expect arguments.  An argument is two
+bytes, with the more significant byte last.
+
+\begin{funcdesc}{STORE_NAME}{namei}
+Implements \code{name = TOS}. \var{namei} is the index of \var{name}
+in the attribute \code{co_names} of the code object.
+The compiler tries to use STORE_LOCAL or STORE_GLOBAL if possible.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_NAME}{namei}
+Implements \code{del name}, where \var{namei} is the index into
+\code{co_names} attribute of the code object.
+\end{funcdesc}
+
+\begin{funcdesc}{UNPACK_TUPLE}{count}
+Unpacks TOS into \var{count} individual values, which are put onto
+the stack right-to-left.
+\end{funcdesc}
+
+\begin{funcdesc}{UNPACK_LIST}{count}
+Unpacks TOS into \var{count} individual values.
+\end{funcdesc}
+
+%\begin{funcdesc}{UNPACK_ARG}{count}
+%This opcode is obsolete.
+%\end{funcdesc}
+
+\begin{funcdesc}{STORE_ATTR}{namei}
+Implements \code{TOS.name = TOS1}, where \var{namei} is the index
+of name in \code{co_names}.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_ATTR}{namei}
+Implements \code{del TOS.name}, using \var{namei} as index into
+\code{co_names}.
+\end{funcdesc}
+
+\begin{funcdesc}{STORE_GLOBAL}{namei}
+Works as STORE_NAME, but stores the name as a global.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_GLOBAL}{namei}
+Works as DELETE_NAME, but deletes a global name.
+\end{funcdesc}
+
+%\begin{funcdesc}{UNPACK_VARARG}{argc}
+%This opcode is obsolete.
+%\end{funcdesc}
+
+\begin{funcdesc}{LOAD_CONST}{consti}
+Pushes \code{co_consts[consti]} onto the stack.
+\end{funcdesc}
+
+\begin{funcdesc}{LOAD_NAME}{namei}
+Pushes the value associated with \code{co_names[namei]} onto the stack.
+\end{funcdesc}
+
+\begin{funcdesc}{BUILD_TUPLE}{count}
+Creates a tuple consuming \var{count} items from the stack, and pushes
+the resulting tuple onto the stack.
+\end{funcdesc}
+
+\begin{funcdesc}{BUILD_LIST}{count}
+Works as \code{BUILD_TUPLE}, but creates a list.
+\end{funcdesc}
+
+\begin{funcdesc}{BUILD_MAP}{zero}
+Pushes an empty dictionary object onto the stack.  The argument is ignored
+and set to zero by the compiler.
+\end{funcdesc}
+
+\begin{funcdesc}{LOAD_ATTR}{namei}
+Replaces TOS with \code{getattr(TOS,co_names[namei]}.
+\end{funcdesc}
+
+\begin{funcdesc}{COMPARE_OP}{opname}
+Performs a boolean operation.  The operation name can be found
+in \code{cmp_op[opname]}.
+\end{funcdesc}
+
+\begin{funcdesc}{IMPORT_NAME}{namei}
+Imports the module \code{co_names[namei]}.  The module object is
+pushed onto the stack.  The current name space is not affect: for a
+proper import statement, a subsequent \code{STORE_FAST} instruction
+modifies the name space.
+\end{funcdesc}
+
+\begin{funcdesc}{IMPORT_FROM}{namei}
+Imports the attribute \code{co_names[namei]}.  The module to import
+from is found in TOS and left there.
+\end{funcdesc}
+
+\begin{funcdesc}{JUMP_FORWARD}{delta}
+Increments byte code counter by \var{delta}.
+\end{funcdesc}
+
+\begin{funcdesc}{JUMP_IF_TRUE}{delta}
+If TOS is true, increment the byte code counter by \var{delta}.  TOS is
+left on the stack.
+\end{funcdesc}
+
+\begin{funcdesc}{JUMP_IF_FALSE}{delta}
+If TOS is false, increment the byte code counter by \var{delta}.  TOS
+is not changed. 
+\end{funcdesc}
+
+\begin{funcdesc}{JUMP_ABSOLUTE}{target}
+Set byte code counter to \var{target}.
+\end{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+%\begin{funcdesc}{LOAD_LOCAL}{namei}
+%This opcode is obsolete.
+%\end{funcdesc}
+
+\begin{funcdesc}{LOAD_GLOBAL}{namei}
+Loads the global named \code{co_names[namei]} onto the stack.
+\end{funcdesc}
+
+%\begin{funcdesc}{SET_FUNC_ARGS}{argc}
+%This opcode is obsolete.
+%\end{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{SETUP_FINALLY}{delta}
+Pushes a try block from a try-except clause onto the block stack.
+\var{delta} points to the finally block.
+\end{funcdesc}
+
+\begin{funcdesc}{LOAD_FAST}{var_num}
+Pushes a reference to the local \code{co_varnames[var_num]} onto
+the stack.
+\end{funcdesc}
+
+\begin{funcdesc}{STORE_FAST}{var_num}
+Stores TOS into the local \code{co_varnames[var_num]}.
+\end{funcdesc}
+
+\begin{funcdesc}{DELETE_FAST}{var_num}
+Deletes local \code{co_varnames[var_num]}.
+\end{funcdesc}
+
+\begin{funcdesc}{SET_LINE_NO}{lineno}
+Sets the current line number to \var{lineno}.
+\end{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{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{funcdesc}
+
+\begin{funcdesc}{BUILD_SLICE}{argc}
+Pushes a slice object on the stack.  If \var{argc} is three, creates
+\code{TOS3[TOS2:TOS1:TOS]}.  Otherwise, expects three arguments.
+\end{funcdesc}
+
+