source: trunk/essentials/dev-lang/python/Doc/lib/libdis.tex@ 3398

\section{\module{dis} ---
         Disassembler for Python byte code}

\declaremodule{standard}{dis}
\modulesynopsis{Disassembler for Python byte code.}


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)
  2           0 LOAD_GLOBAL              0 (len)
              3 LOAD_FAST                0 (alist)
              6 CALL_FUNCTION            1
              9 RETURN_VALUE
\end{verbatim}

(The ``2'' is a line number).

The \module{dis} module defines the following functions and constants:

\begin{funcdesc}{dis}{\optional{bytesource}}
Disassemble the \var{bytesource} object. \var{bytesource} can denote
either a module, a class, a method, a function, or a code object.  
For a module, it disassembles all functions.  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 line number, for the first instruction of each line
\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 operation names, indexable using the byte code.
\end{datadesc}

\begin{datadesc}{opmap}
Dictionary mapping byte codes to operation names.
\end{datadesc}

\begin{datadesc}{cmp_op}
Sequence of all compare operation names.