Doc/lib/libdis.tex

   1 \section{\module{dis} ---
   2          Disassembler.}
   3 \declaremodule{standard}{dis}
   4
   5 \modulesynopsis{Disassembler.}
   6
   7
   8 The \module{dis} module supports the analysis of Python byte code by
   9 disassembling it.  Since there is no Python assembler, this module
  10 defines the Python assembly language.  The Python byte code which
  11 this module takes as an input is defined in the file
  12 \file{Include/opcode.h} and used by the compiler and the interpreter.
  13
  14 Example: Given the function \function{myfunc}:
  15
  16 \begin{verbatim}
  17 def myfunc(alist):
  18     return len(alist)
  19 \end{verbatim}
  20
  21 the following command can be used to get the disassembly of
  22 \function{myfunc()}:
  23
  24 \begin{verbatim}
  25 >>> dis.dis(myfunc)
  26           0 SET_LINENO          1
  27
  28           3 SET_LINENO          2
  29           6 LOAD_GLOBAL         0 (len)
  30           9 LOAD_FAST           0 (alist)
  31          12 CALL_FUNCTION       1
  32          15 RETURN_VALUE
  33          16 LOAD_CONST          0 (None)
  34          19 RETURN_VALUE
  35 \end{verbatim}
  36
  37 The \module{dis} module defines the following functions:
  38
  39 \begin{funcdesc}{dis}{\optional{bytesource}}
  40 Disassemble the \var{bytesource} object. \var{bytesource} can denote
  41 either a class, a method, a function, or a code object.  For a class,
  42 it disassembles all methods.  For a single code sequence, it prints
  43 one line per byte code instruction.  If no object is provided, it
  44 disassembles the last traceback.
  45 \end{funcdesc}
  46
  47 \begin{funcdesc}{distb}{\optional{tb}}
  48 Disassembles the top-of-stack function of a traceback, using the last
  49 traceback if none was passed.  The instruction causing the exception
  50 is indicated.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{disassemble}{code\optional{, lasti}}
  54 Disassembles a code object, indicating the last instruction if \var{lasti}
  55 was provided.  The output is divided in the following columns:
  56
  57 \begin{enumerate}
  58 \item the current instruction, indicated as \samp{-->},
  59 \item a labelled instruction, indicated with \samp{>>},
  60 \item the address of the instruction,
  61 \item the operation code name,
  62 \item operation parameters, and
  63 \item interpretation of the parameters in parentheses.
  64 \end{enumerate}
  65
  66 The parameter interpretation recognizes local and global
  67 variable names, constant values, branch targets, and compare
  68 operators.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{disco}{code\optional{, lasti}}
  72 A synonym for disassemble.  It is more convenient to type, and kept
  73 for compatibility with earlier Python releases.
  74 \end{funcdesc}
  75
  76 \begin{datadesc}{opname}
  77 Sequence of a operation names, indexable using the byte code.
  78 \end{datadesc}
  79
  80 \begin{datadesc}{cmp_op}
  81 Sequence of all compare operation names.
  82 \end{datadesc}
  83
  84 \begin{datadesc}{hasconst}
  85 Sequence of byte codes that have a constant parameter.
  86 \end{datadesc}
  87
  88 \begin{datadesc}{hasname}
  89 Sequence of byte codes that access a attribute by name.
  90 \end{datadesc}
  91
  92 \begin{datadesc}{hasjrel}
  93 Sequence of byte codes that have a relative jump target.
  94 \end{datadesc}
  95
  96 \begin{datadesc}{hasjabs}
  97 Sequence of byte codes that have an absolute jump target.
  98 \end{datadesc}
  99
 100 \begin{datadesc}{haslocal}
 101 Sequence of byte codes that access a a local variable.
 102 \end{datadesc}
 103
 104 \begin{datadesc}{hascompare}
 105 Sequence of byte codes of boolean operations.
 106 \end{datadesc}
 107
 108 \subsection{Python Byte Code Instructions}
 109 \label{bytecodes}
 110
 111 The Python compiler currently generates the following byte code
 112 instructions.
 113
 114 \setindexsubitem{(byte code insns)}
 115
 116 \begin{opcodedesc}{STOP_CODE}{}
 117 Indicates end-of-code to the compiler, not used by the interpreter.
 118 \end{opcodedesc}
 119
 120 \begin{opcodedesc}{POP_TOP}{}
 121 Removes the top-of-stack (TOS) item.
 122 \end{opcodedesc}
 123
 124 \begin{opcodedesc}{ROT_TWO}{}
 125 Swaps the two top-most stack items.
 126 \end{opcodedesc}
 127
 128 \begin{opcodedesc}{ROT_THREE}{}
 129 Lifts second and third stack item one position up, moves top down
 130 to position three.
 131 \end{opcodedesc}
 132
 133 \begin{opcodedesc}{DUP_TOP}{}
 134 Duplicates the reference on top of the stack.
 135 \end{opcodedesc}
 136
 137 Unary Operations take the top of the stack, apply the operation, and
 138 push the result back on the stack.
 139
 140 \begin{opcodedesc}{UNARY_POSITIVE}{}
 141 Implements \code{TOS = +TOS}.
 142 \end{opcodedesc}
 143
 144 \begin{opcodedesc}{UNARY_NEG}{}
 145 Implements \code{TOS = -TOS}.
 146 \end{opcodedesc}
 147
 148 \begin{opcodedesc}{UNARY_NOT}{}
 149 Implements \code{TOS = not TOS}.
 150 \end{opcodedesc}
 151
 152 \begin{opcodedesc}{UNARY_CONVERT}{}
 153 Implements \code{TOS = `TOS`}.
 154 \end{opcodedesc}
 155
 156 \begin{opcodedesc}{UNARY_INVERT}{}
 157 Implements \code{TOS = \~TOS}.
 158 \end{opcodedesc}
 159
 160 Binary operations remove the top of the stack (TOS) and the second top-most
 161 stack item (TOS1) from the stack.  They perform the operation, and put the
 162 result back on the stack.
 163
 164 \begin{opcodedesc}{BINARY_POWER}{}
 165 Implements \code{TOS = TOS1 ** TOS}.
 166 \end{opcodedesc}
 167
 168 \begin{opcodedesc}{BINARY_MULTIPLY}{}
 169 Implements \code{TOS = TOS1 * TOS}.
 170 \end{opcodedesc}
 171
 172 \begin{opcodedesc}{BINARY_DIVIDE}{}
 173 Implements \code{TOS = TOS1 / TOS}.
 174 \end{opcodedesc}
 175
 176 \begin{opcodedesc}{BINARY_MODULO}{}
 177 Implements \code{TOS = TOS1 \% TOS}.
 178 \end{opcodedesc}
 179
 180 \begin{opcodedesc}{BINARY_ADD}{}
 181 Implements \code{TOS = TOS1 + TOS}.
 182 \end{opcodedesc}
 183
 184 \begin{opcodedesc}{BINARY_SUBTRACT}{}
 185 Implements \code{TOS = TOS1 - TOS}.
 186 \end{opcodedesc}
 187
 188 \begin{opcodedesc}{BINARY_SUBSCR}{}
 189 Implements \code{TOS = TOS1[TOS]}.
 190 \end{opcodedesc}
 191
 192 \begin{opcodedesc}{BINARY_LSHIFT}{}
 193 Implements \code{TOS = TOS1 << TOS}.
 194 \end{opcodedesc}
 195
 196 \begin{opcodedesc}{BINARY_RSHIFT}{}
 197 Implements \code{TOS = TOS1 >> TOS}.
 198 \end{opcodedesc}
 199
 200 \begin{opcodedesc}{BINARY_AND}{}
 201 Implements \code{TOS = TOS1 and TOS}.
 202 \end{opcodedesc}
 203
 204 \begin{opcodedesc}{BINARY_XOR}{}
 205 Implements \code{TOS = TOS1 \^\ TOS}.
 206 \end{opcodedesc}
 207
 208 \begin{opcodedesc}{BINARY_OR}{}
 209 Implements \code{TOS = TOS1 or TOS}.
 210 \end{opcodedesc}
 211
 212 The slice opcodes take up to three parameters.
 213
 214 \begin{opcodedesc}{SLICE+0}{}
 215 Implements \code{TOS = TOS[:]}.
 216 \end{opcodedesc}
 217
 218 \begin{opcodedesc}{SLICE+1}{}
 219 Implements \code{TOS = TOS1[TOS:]}.
 220 \end{opcodedesc}
 221
 222 \begin{opcodedesc}{SLICE+2}{}
 223 Implements \code{TOS = TOS1[:TOS1]}.
 224 \end{opcodedesc}
 225
 226 \begin{opcodedesc}{SLICE+3}{}
 227 Implements \code{TOS = TOS2[TOS1:TOS]}.
 228 \end{opcodedesc}
 229
 230 Slice assignment needs even an additional parameter.  As any statement,
 231 they put nothing on the stack.
 232
 233 \begin{opcodedesc}{STORE_SLICE+0}{}
 234 Implements \code{TOS[:] = TOS1}.
 235 \end{opcodedesc}
 236
 237 \begin{opcodedesc}{STORE_SLICE+1}{}
 238 Implements \code{TOS1[TOS:] = TOS2}.
 239 \end{opcodedesc}
 240
 241 \begin{opcodedesc}{STORE_SLICE+2}{}
 242 Implements \code{TOS1[:TOS] = TOS2}.
 243 \end{opcodedesc}
 244
 245 \begin{opcodedesc}{STORE_SLICE+3}{}
 246 Implements \code{TOS2[TOS1:TOS] = TOS3}.
 247 \end{opcodedesc}
 248
 249 \begin{opcodedesc}{DELETE_SLICE+0}{}
 250 Implements \code{del TOS[:]}.
 251 \end{opcodedesc}
 252
 253 \begin{opcodedesc}{DELETE_SLICE+1}{}
 254 Implements \code{del TOS1[TOS:]}.
 255 \end{opcodedesc}
 256
 257 \begin{opcodedesc}{DELETE_SLICE+2}{}
 258 Implements \code{del TOS1[:TOS]}.
 259 \end{opcodedesc}
 260
 261 \begin{opcodedesc}{DELETE_SLICE+3}{}
 262 Implements \code{del TOS2[TOS1:TOS]}.
 263 \end{opcodedesc}
 264
 265 \begin{opcodedesc}{STORE_SUBSCR}{}
 266 Implements \code{TOS1[TOS] = TOS2}.
 267 \end{opcodedesc}
 268
 269 \begin{opcodedesc}{DELETE_SUBSCR}{}
 270 Implements \code{del TOS1[TOS]}.
 271 \end{opcodedesc}
 272
 273 \begin{opcodedesc}{PRINT_EXPR}{}
 274 Implements the expression statement for the interactive mode.  TOS is
 275 removed from the stack and printed.  In non-interactive mode, an
 276 expression statement is terminated with \code{POP_STACK}.
 277 \end{opcodedesc}
 278
 279 \begin{opcodedesc}{PRINT_ITEM}{}
 280 Prints TOS.  There is one such instruction for
 281 each item in the print statement.
 282 \end{opcodedesc}
 283
 284 \begin{opcodedesc}{PRINT_NEWLINE}{}
 285 Prints a new line on \code{sys.stdout}.  This is generated as the
 286 last operation of a print statement, unless the statement ends
 287 with a comma.
 288 \end{opcodedesc}
 289
 290 \begin{opcodedesc}{BREAK_LOOP}{}
 291 Terminates a loop due to a break statement.
 292 \end{opcodedesc}
 293
 294 \begin{opcodedesc}{LOAD_LOCALS}{}
 295 Pushes a reference to the locals of the current scope on the stack.
 296 This is used in the code for a class definition: After the class body
 297 is evaluated, the locals are passed to the class definition.
 298 \end{opcodedesc}
 299
 300 \begin{opcodedesc}{RETURN_VALUE}{}
 301 Returns with TOS to the caller of the function.
 302 \end{opcodedesc}
 303
 304 \begin{opcodedesc}{EXEC_STMT}{}
 305 Implements \code{exec TOS2,TOS1,TOS}.  The compiler fills
 306 missing optional parameters with None.
 307 \end{opcodedesc}
 308
 309 \begin{opcodedesc}{POP_BLOCK}{}
 310 Removes one block from the block stack.  Per frame, there is a
 311 stack of blocks, denoting nested loops, try statements, and such.
 312 \end{opcodedesc}
 313
 314 \begin{opcodedesc}{END_FINALLY}{}
 315 Terminates a finally-block.  The interpreter recalls whether the
 316 exception has to be re-raised, or whether the function returns,
 317 and continues with the outer-next block.
 318 \end{opcodedesc}
 319
 320 \begin{opcodedesc}{BUILD_CLASS}{}
 321 Creates a new class object.  TOS is the methods dictionary, TOS1
 322 the tuple of the names of the base classes, and TOS2 the class name.
 323 \end{opcodedesc}
 324
 325 All of the following opcodes expect arguments.  An argument is two
 326 bytes, with the more significant byte last.
 327
 328 \begin{opcodedesc}{STORE_NAME}{namei}
 329 Implements \code{name = TOS}. \var{namei} is the index of \var{name}
 330 in the attribute \member{co_names} of the code object.
 331 The compiler tries to use \code{STORE_LOCAL} or \code{STORE_GLOBAL}
 332 if possible.
 333 \end{opcodedesc}
 334
 335 \begin{opcodedesc}{DELETE_NAME}{namei}
 336 Implements \code{del name}, where \var{namei} is the index into
 337 \member{co_names} attribute of the code object.
 338 \end{opcodedesc}
 339
 340 \begin{opcodedesc}{UNPACK_TUPLE}{count}
 341 Unpacks TOS into \var{count} individual values, which are put onto
 342 the stack right-to-left.
 343 \end{opcodedesc}
 344
 345 \begin{opcodedesc}{UNPACK_LIST}{count}
 346 Unpacks TOS into \var{count} individual values.
 347 \end{opcodedesc}
 348
 349 %\begin{opcodedesc}{UNPACK_ARG}{count}
 350 %This opcode is obsolete.
 351 %\end{opcodedesc}
 352
 353 \begin{opcodedesc}{STORE_ATTR}{namei}
 354 Implements \code{TOS.name = TOS1}, where \var{namei} is the index
 355 of name in \member{co_names}.
 356 \end{opcodedesc}
 357
 358 \begin{opcodedesc}{DELETE_ATTR}{namei}
 359 Implements \code{del TOS.name}, using \var{namei} as index into
 360 \member{co_names}.
 361 \end{opcodedesc}
 362
 363 \begin{opcodedesc}{STORE_GLOBAL}{namei}
 364 Works as \code{STORE_NAME}, but stores the name as a global.
 365 \end{opcodedesc}
 366
 367 \begin{opcodedesc}{DELETE_GLOBAL}{namei}
 368 Works as \code{DELETE_NAME}, but deletes a global name.
 369 \end{opcodedesc}
 370
 371 %\begin{opcodedesc}{UNPACK_VARARG}{argc}
 372 %This opcode is obsolete.
 373 %\end{opcodedesc}
 374
 375 \begin{opcodedesc}{LOAD_CONST}{consti}
 376 Pushes \samp{co_consts[\var{consti}]} onto the stack.
 377 \end{opcodedesc}
 378
 379 \begin{opcodedesc}{LOAD_NAME}{namei}
 380 Pushes the value associated with \samp{co_names[\var{namei}]} onto the stack.
 381 \end{opcodedesc}
 382
 383 \begin{opcodedesc}{BUILD_TUPLE}{count}
 384 Creates a tuple consuming \var{count} items from the stack, and pushes
 385 the resulting tuple onto the stack.
 386 \end{opcodedesc}
 387
 388 \begin{opcodedesc}{BUILD_LIST}{count}
 389 Works as \code{BUILD_TUPLE}, but creates a list.
 390 \end{opcodedesc}
 391
 392 \begin{opcodedesc}{BUILD_MAP}{zero}
 393 Pushes an empty dictionary object onto the stack.  The argument is ignored
 394 and set to zero by the compiler.
 395 \end{opcodedesc}
 396
 397 \begin{opcodedesc}{LOAD_ATTR}{namei}
 398 Replaces TOS with \code{getattr(TOS,co_names[\var{namei}]}.
 399 \end{opcodedesc}
 400
 401 \begin{opcodedesc}{COMPARE_OP}{opname}
 402 Performs a boolean operation.  The operation name can be found
 403 in \code{cmp_op[\var{opname}]}.
 404 \end{opcodedesc}
 405
 406 \begin{opcodedesc}{IMPORT_NAME}{namei}
 407 Imports the module \code{co_names[\var{namei}]}.  The module object is
 408 pushed onto the stack.  The current name space is not affected: for a
 409 proper import statement, a subsequent \code{STORE_FAST} instruction
 410 modifies the name space.
 411 \end{opcodedesc}
 412
 413 \begin{opcodedesc}{IMPORT_FROM}{namei}
 414 Imports the attribute \code{co_names[\var{namei}]}.  The module to import
 415 from is found in TOS and left there.
 416 \end{opcodedesc}
 417
 418 \begin{opcodedesc}{JUMP_FORWARD}{delta}
 419 Increments byte code counter by \var{delta}.
 420 \end{opcodedesc}
 421
 422 \begin{opcodedesc}{JUMP_IF_TRUE}{delta}
 423 If TOS is true, increment the byte code counter by \var{delta}.  TOS is
 424 left on the stack.
 425 \end{opcodedesc}
 426
 427 \begin{opcodedesc}{JUMP_IF_FALSE}{delta}
 428 If TOS is false, increment the byte code counter by \var{delta}.  TOS
 429 is not changed.
 430 \end{opcodedesc}
 431
 432 \begin{opcodedesc}{JUMP_ABSOLUTE}{target}
 433 Set byte code counter to \var{target}.
 434 \end{opcodedesc}
 435
 436 \begin{opcodedesc}{FOR_LOOP}{delta}
 437 Iterate over a sequence.  TOS is the current index, TOS1 the sequence.
 438 First, the next element is computed.  If the sequence is exhausted,
 439 increment byte code counter by \var{delta}.  Otherwise, push the
 440 sequence, the incremented counter, and the current item onto the stack.
 441 \end{opcodedesc}
 442
 443 %\begin{opcodedesc}{LOAD_LOCAL}{namei}
 444 %This opcode is obsolete.
 445 %\end{opcodedesc}
 446
 447 \begin{opcodedesc}{LOAD_GLOBAL}{namei}
 448 Loads the global named \code{co_names[\var{namei}]} onto the stack.
 449 \end{opcodedesc}
 450
 451 %\begin{opcodedesc}{SET_FUNC_ARGS}{argc}
 452 %This opcode is obsolete.
 453 %\end{opcodedesc}
 454
 455 \begin{opcodedesc}{SETUP_LOOP}{delta}
 456 Pushes a block for a loop onto the block stack.  The block spans
 457 from the current instruction with a size of \var{delta} bytes.
 458 \end{opcodedesc}
 459
 460 \begin{opcodedesc}{SETUP_EXCEPT}{delta}
 461 Pushes a try block from a try-except clause onto the block stack.
 462 \var{delta} points to the first except block.
 463 \end{opcodedesc}
 464
 465 \begin{opcodedesc}{SETUP_FINALLY}{delta}
 466 Pushes a try block from a try-except clause onto the block stack.
 467 \var{delta} points to the finally block.
 468 \end{opcodedesc}
 469
 470 \begin{opcodedesc}{LOAD_FAST}{var_num}
 471 Pushes a reference to the local \code{co_varnames[\var{var_num}]} onto
 472 the stack.
 473 \end{opcodedesc}
 474
 475 \begin{opcodedesc}{STORE_FAST}{var_num}
 476 Stores TOS into the local \code{co_varnames[\var{var_num}]}.
 477 \end{opcodedesc}
 478
 479 \begin{opcodedesc}{DELETE_FAST}{var_num}
 480 Deletes local \code{co_varnames[\var{var_num}]}.
 481 \end{opcodedesc}
 482
 483 \begin{opcodedesc}{SET_LINENO}{lineno}
 484 Sets the current line number to \var{lineno}.
 485 \end{opcodedesc}
 486
 487 \begin{opcodedesc}{RAISE_VARARGS}{argc}
 488 Raises an exception. \var{argc} indicates the number of parameters
 489 to the raise statement, ranging from 1 to 3.  The handler will find
 490 the traceback as TOS2, the parameter as TOS1, and the exception
 491 as TOS.
 492 \end{opcodedesc}
 493
 494 \begin{opcodedesc}{CALL_FUNCTION}{argc}
 495 Calls a function.  The low byte of \var{argc} indicates the number of
 496 positional parameters, the high byte the number of keyword parameters.
 497 On the stack, the opcode finds the keyword parameters first.  For each
 498 keyword argument, the value is on top of the key.  Below the keyword
 499 parameters, the positional parameters are on the stack, with the
 500 right-most parameter on top.  Below the parameters, the function object
 501 to call is on the stack.
 502 \end{opcodedesc}
 503
 504 \begin{opcodedesc}{MAKE_FUNCTION}{argc}
 505 Pushes a new function object on the stack.  TOS is the code associated
 506 with the function.  The function object is defined to have \var{argc}
 507 default parameters, which are found below TOS.
 508 \end{opcodedesc}
 509
 510 \begin{opcodedesc}{BUILD_SLICE}{argc}
 511 Pushes a slice object on the stack.  \var{argc} must be 2 or 3.  If it
 512 is 2, \code{slice(TOS1, TOS)} is pushed; if it is 3,
 513 \code{slice(TOS2, TOS1, TOS)} is pushed.
 514 See the \code{slice()}\bifuncindex{slice} built-in function.
 515 \end{opcodedesc}