diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/dis.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/dis.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,820 @@ + +:mod:`dis` --- Disassembler for Python bytecode +=============================================== + +.. module:: dis + :synopsis: Disassembler for Python bytecode. + + +The :mod:`dis` module supports the analysis of Python :term:`bytecode` by disassembling +it. Since there is no Python assembler, this module defines the Python assembly +language. The Python bytecode 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 :func:`myfunc`:: + + def myfunc(alist): + return len(alist) + +the following command can be used to get the disassembly of :func:`myfunc`:: + + >>> dis.dis(myfunc) + 2 0 LOAD_GLOBAL 0 (len) + 3 LOAD_FAST 0 (alist) + 6 CALL_FUNCTION 1 + 9 RETURN_VALUE + +(The "2" is a line number). + +The :mod:`dis` module defines the following functions and constants: + + +.. function:: dis([bytesource]) + + Disassemble the *bytesource* object. *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 bytecode instruction. If no object is + provided, it disassembles the last traceback. + + +.. function:: distb([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. + + +.. function:: disassemble(code[, lasti]) + + Disassembles a code object, indicating the last instruction if *lasti* was + provided. The output is divided in the following columns: + + #. the line number, for the first instruction of each line + #. the current instruction, indicated as ``-->``, + #. a labelled instruction, indicated with ``>>``, + #. the address of the instruction, + #. the operation code name, + #. operation parameters, and + #. interpretation of the parameters in parentheses. + + The parameter interpretation recognizes local and global variable names, + constant values, branch targets, and compare operators. + + +.. function:: disco(code[, lasti]) + + A synonym for disassemble. It is more convenient to type, and kept for + compatibility with earlier Python releases. + + +.. data:: opname + + Sequence of operation names, indexable using the bytecode. + + +.. data:: opmap + + Dictionary mapping bytecodes to operation names. + + +.. data:: cmp_op + + Sequence of all compare operation names. + + +.. data:: hasconst + + Sequence of bytecodes that have a constant parameter. + + +.. data:: hasfree + + Sequence of bytecodes that access a free variable. + + +.. data:: hasname + + Sequence of bytecodes that access an attribute by name. + + +.. data:: hasjrel + + Sequence of bytecodes that have a relative jump target. + + +.. data:: hasjabs + + Sequence of bytecodes that have an absolute jump target. + + +.. data:: haslocal + + Sequence of bytecodes that access a local variable. + + +.. data:: hascompare + + Sequence of bytecodes of Boolean operations. + + +.. _bytecodes: + +Python Bytecode Instructions +---------------------------- + +The Python compiler currently generates the following bytecode instructions. + + +.. opcode:: STOP_CODE () + + Indicates end-of-code to the compiler, not used by the interpreter. + + +.. opcode:: NOP () + + Do nothing code. Used as a placeholder by the bytecode optimizer. + + +.. opcode:: POP_TOP () + + Removes the top-of-stack (TOS) item. + + +.. opcode:: ROT_TWO () + + Swaps the two top-most stack items. + + +.. opcode:: ROT_THREE () + + Lifts second and third stack item one position up, moves top down to position + three. + + +.. opcode:: ROT_FOUR () + + Lifts second, third and forth stack item one position up, moves top down to + position four. + + +.. opcode:: DUP_TOP () + + Duplicates the reference on top of the stack. + +Unary Operations take the top of the stack, apply the operation, and push the +result back on the stack. + + +.. opcode:: UNARY_POSITIVE () + + Implements ``TOS = +TOS``. + + +.. opcode:: UNARY_NEGATIVE () + + Implements ``TOS = -TOS``. + + +.. opcode:: UNARY_NOT () + + Implements ``TOS = not TOS``. + + +.. opcode:: UNARY_CONVERT () + + Implements ``TOS = `TOS```. + + +.. opcode:: UNARY_INVERT () + + Implements ``TOS = ~TOS``. + + +.. opcode:: GET_ITER () + + Implements ``TOS = iter(TOS)``. + +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. + + +.. opcode:: BINARY_POWER () + + Implements ``TOS = TOS1 ** TOS``. + + +.. opcode:: BINARY_MULTIPLY () + + Implements ``TOS = TOS1 * TOS``. + + +.. opcode:: BINARY_DIVIDE () + + Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is not + in effect. + + +.. opcode:: BINARY_FLOOR_DIVIDE () + + Implements ``TOS = TOS1 // TOS``. + + +.. opcode:: BINARY_TRUE_DIVIDE () + + Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is in + effect. + + +.. opcode:: BINARY_MODULO () + + Implements ``TOS = TOS1 % TOS``. + + +.. opcode:: BINARY_ADD () + + Implements ``TOS = TOS1 + TOS``. + + +.. opcode:: BINARY_SUBTRACT () + + Implements ``TOS = TOS1 - TOS``. + + +.. opcode:: BINARY_SUBSCR () + + Implements ``TOS = TOS1[TOS]``. + + +.. opcode:: BINARY_LSHIFT () + + Implements ``TOS = TOS1 << TOS``. + + +.. opcode:: BINARY_RSHIFT () + + Implements ``TOS = TOS1 >> TOS``. + + +.. opcode:: BINARY_AND () + + Implements ``TOS = TOS1 & TOS``. + + +.. opcode:: BINARY_XOR () + + Implements ``TOS = TOS1 ^ TOS``. + + +.. opcode:: BINARY_OR () + + Implements ``TOS = TOS1 | TOS``. + +In-place operations are like binary operations, in that they remove TOS and +TOS1, and push the result back on the stack, but the operation is done in-place +when TOS1 supports it, and the resulting TOS may be (but does not have to be) +the original TOS1. + + +.. opcode:: INPLACE_POWER () + + Implements in-place ``TOS = TOS1 ** TOS``. + + +.. opcode:: INPLACE_MULTIPLY () + + Implements in-place ``TOS = TOS1 * TOS``. + + +.. opcode:: INPLACE_DIVIDE () + + Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import + division`` is not in effect. + + +.. opcode:: INPLACE_FLOOR_DIVIDE () + + Implements in-place ``TOS = TOS1 // TOS``. + + +.. opcode:: INPLACE_TRUE_DIVIDE () + + Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import + division`` is in effect. + + +.. opcode:: INPLACE_MODULO () + + Implements in-place ``TOS = TOS1 % TOS``. + + +.. opcode:: INPLACE_ADD () + + Implements in-place ``TOS = TOS1 + TOS``. + + +.. opcode:: INPLACE_SUBTRACT () + + Implements in-place ``TOS = TOS1 - TOS``. + + +.. opcode:: INPLACE_LSHIFT () + + Implements in-place ``TOS = TOS1 << TOS``. + + +.. opcode:: INPLACE_RSHIFT () + + Implements in-place ``TOS = TOS1 >> TOS``. + + +.. opcode:: INPLACE_AND () + + Implements in-place ``TOS = TOS1 & TOS``. + + +.. opcode:: INPLACE_XOR () + + Implements in-place ``TOS = TOS1 ^ TOS``. + + +.. opcode:: INPLACE_OR () + + Implements in-place ``TOS = TOS1 | TOS``. + +The slice opcodes take up to three parameters. + + +.. opcode:: SLICE+0 () + + Implements ``TOS = TOS[:]``. + + +.. opcode:: SLICE+1 () + + Implements ``TOS = TOS1[TOS:]``. + + +.. opcode:: SLICE+2 () + + Implements ``TOS = TOS1[:TOS]``. + + +.. opcode:: SLICE+3 () + + Implements ``TOS = TOS2[TOS1:TOS]``. + +Slice assignment needs even an additional parameter. As any statement, they put +nothing on the stack. + + +.. opcode:: STORE_SLICE+0 () + + Implements ``TOS[:] = TOS1``. + + +.. opcode:: STORE_SLICE+1 () + + Implements ``TOS1[TOS:] = TOS2``. + + +.. opcode:: STORE_SLICE+2 () + + Implements ``TOS1[:TOS] = TOS2``. + + +.. opcode:: STORE_SLICE+3 () + + Implements ``TOS2[TOS1:TOS] = TOS3``. + + +.. opcode:: DELETE_SLICE+0 () + + Implements ``del TOS[:]``. + + +.. opcode:: DELETE_SLICE+1 () + + Implements ``del TOS1[TOS:]``. + + +.. opcode:: DELETE_SLICE+2 () + + Implements ``del TOS1[:TOS]``. + + +.. opcode:: DELETE_SLICE+3 () + + Implements ``del TOS2[TOS1:TOS]``. + + +.. opcode:: STORE_SUBSCR () + + Implements ``TOS1[TOS] = TOS2``. + + +.. opcode:: DELETE_SUBSCR () + + Implements ``del TOS1[TOS]``. + +Miscellaneous opcodes. + + +.. opcode:: 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``. + + +.. opcode:: PRINT_ITEM () + + Prints TOS to the file-like object bound to ``sys.stdout``. There is one such + instruction for each item in the :keyword:`print` statement. + + +.. opcode:: PRINT_ITEM_TO () + + Like ``PRINT_ITEM``, but prints the item second from TOS to the file-like object + at TOS. This is used by the extended print statement. + + +.. opcode:: PRINT_NEWLINE () + + Prints a new line on ``sys.stdout``. This is generated as the last operation of + a :keyword:`print` statement, unless the statement ends with a comma. + + +.. opcode:: PRINT_NEWLINE_TO () + + Like ``PRINT_NEWLINE``, but prints the new line on the file-like object on the + TOS. This is used by the extended print statement. + + +.. opcode:: BREAK_LOOP () + + Terminates a loop due to a :keyword:`break` statement. + + +.. opcode:: CONTINUE_LOOP (target) + + Continues a loop due to a :keyword:`continue` statement. *target* is the + address to jump to (which should be a ``FOR_ITER`` instruction). + + +.. opcode:: LIST_APPEND () + + Calls ``list.append(TOS1, TOS)``. Used to implement list comprehensions. + + +.. opcode:: 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. + + +.. opcode:: RETURN_VALUE () + + Returns with TOS to the caller of the function. + + +.. opcode:: YIELD_VALUE () + + Pops ``TOS`` and yields it from a :term:`generator`. + + +.. opcode:: IMPORT_STAR () + + Loads all symbols not starting with ``'_'`` directly from the module TOS to the + local namespace. The module is popped after loading all names. This opcode + implements ``from module import *``. + + +.. opcode:: EXEC_STMT () + + Implements ``exec TOS2,TOS1,TOS``. The compiler fills missing optional + parameters with ``None``. + + +.. opcode:: POP_BLOCK () + + Removes one block from the block stack. Per frame, there is a stack of blocks, + denoting nested loops, try statements, and such. + + +.. opcode:: END_FINALLY () + + Terminates a :keyword:`finally` clause. The interpreter recalls whether the + exception has to be re-raised, or whether the function returns, and continues + with the outer-next block. + + +.. opcode:: 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. + + +.. opcode:: WITH_CLEANUP () + + Cleans up the stack when a :keyword:`with` statement block exits. On top of + the stack are 1--3 values indicating how/why the finally clause was entered: + + * TOP = ``None`` + * (TOP, SECOND) = (``WHY_{RETURN,CONTINUE}``), retval + * TOP = ``WHY_*``; no retval below it + * (TOP, SECOND, THIRD) = exc_info() + + Under them is EXIT, the context manager's :meth:`__exit__` bound method. + + In the last case, ``EXIT(TOP, SECOND, THIRD)`` is called, otherwise + ``EXIT(None, None, None)``. + + EXIT is removed from the stack, leaving the values above it in the same + order. In addition, if the stack represents an exception, *and* the function + call returns a 'true' value, this information is "zapped", to prevent + ``END_FINALLY`` from re-raising the exception. (But non-local gotos should + still be resumed.) + + .. XXX explain the WHY stuff! + + +All of the following opcodes expect arguments. An argument is two bytes, with +the more significant byte last. + +.. opcode:: STORE_NAME (namei) + + Implements ``name = TOS``. *namei* is the index of *name* in the attribute + :attr:`co_names` of the code object. The compiler tries to use ``STORE_FAST`` + or ``STORE_GLOBAL`` if possible. + + +.. opcode:: DELETE_NAME (namei) + + Implements ``del name``, where *namei* is the index into :attr:`co_names` + attribute of the code object. + + +.. opcode:: UNPACK_SEQUENCE (count) + + Unpacks TOS into *count* individual values, which are put onto the stack + right-to-left. + + +.. opcode:: DUP_TOPX (count) + + Duplicate *count* items, keeping them in the same order. Due to implementation + limits, *count* should be between 1 and 5 inclusive. + + +.. opcode:: STORE_ATTR (namei) + + Implements ``TOS.name = TOS1``, where *namei* is the index of name in + :attr:`co_names`. + + +.. opcode:: DELETE_ATTR (namei) + + Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`. + + +.. opcode:: STORE_GLOBAL (namei) + + Works as ``STORE_NAME``, but stores the name as a global. + + +.. opcode:: DELETE_GLOBAL (namei) + + Works as ``DELETE_NAME``, but deletes a global name. + + +.. opcode:: LOAD_CONST (consti) + + Pushes ``co_consts[consti]`` onto the stack. + + +.. opcode:: LOAD_NAME (namei) + + Pushes the value associated with ``co_names[namei]`` onto the stack. + + +.. opcode:: BUILD_TUPLE (count) + + Creates a tuple consuming *count* items from the stack, and pushes the resulting + tuple onto the stack. + + +.. opcode:: BUILD_LIST (count) + + Works as ``BUILD_TUPLE``, but creates a list. + + +.. opcode:: BUILD_MAP (count) + + Pushes a new dictionary object onto the stack. The dictionary is pre-sized + to hold *count* entries. + + +.. opcode:: LOAD_ATTR (namei) + + Replaces TOS with ``getattr(TOS, co_names[namei])``. + + +.. opcode:: COMPARE_OP (opname) + + Performs a Boolean operation. The operation name can be found in + ``cmp_op[opname]``. + + +.. opcode:: IMPORT_NAME (namei) + + Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide + the *fromlist* and *level* arguments of :func:`__import__`. The module + object is pushed onto the stack. The current namespace is not affected: + for a proper import statement, a subsequent ``STORE_FAST`` instruction + modifies the namespace. + + +.. opcode:: IMPORT_FROM (namei) + + Loads the attribute ``co_names[namei]`` from the module found in TOS. The + resulting object is pushed onto the stack, to be subsequently stored by a + ``STORE_FAST`` instruction. + + +.. opcode:: JUMP_FORWARD (delta) + + Increments bytecode counter by *delta*. + + +.. opcode:: JUMP_IF_TRUE (delta) + + If TOS is true, increment the bytecode counter by *delta*. TOS is left on the + stack. + + +.. opcode:: JUMP_IF_FALSE (delta) + + If TOS is false, increment the bytecode counter by *delta*. TOS is not + changed. + + +.. opcode:: JUMP_ABSOLUTE (target) + + Set bytecode counter to *target*. + + +.. opcode:: FOR_ITER (delta) + + ``TOS`` is an :term:`iterator`. Call its :meth:`next` method. If this + yields a new value, push it on the stack (leaving the iterator below it). If + the iterator indicates it is exhausted ``TOS`` is popped, and the bytecode + counter is incremented by *delta*. + + +.. opcode:: LOAD_GLOBAL (namei) + + Loads the global named ``co_names[namei]`` onto the stack. + + +.. opcode:: SETUP_LOOP (delta) + + Pushes a block for a loop onto the block stack. The block spans from the + current instruction with a size of *delta* bytes. + + +.. opcode:: SETUP_EXCEPT (delta) + + Pushes a try block from a try-except clause onto the block stack. *delta* points + to the first except block. + + +.. opcode:: SETUP_FINALLY (delta) + + Pushes a try block from a try-except clause onto the block stack. *delta* points + to the finally block. + +.. opcode:: STORE_MAP () + + Store a key and value pair in a dictionary. Pops the key and value while leaving + the dictionary on the stack. + +.. opcode:: LOAD_FAST (var_num) + + Pushes a reference to the local ``co_varnames[var_num]`` onto the stack. + + +.. opcode:: STORE_FAST (var_num) + + Stores TOS into the local ``co_varnames[var_num]``. + + +.. opcode:: DELETE_FAST (var_num) + + Deletes local ``co_varnames[var_num]``. + + +.. opcode:: LOAD_CLOSURE (i) + + Pushes a reference to the cell contained in slot *i* of the cell and free + variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is + less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i - + len(co_cellvars)]``. + + +.. opcode:: LOAD_DEREF (i) + + Loads the cell contained in slot *i* of the cell and free variable storage. + Pushes a reference to the object the cell contains on the stack. + + +.. opcode:: STORE_DEREF (i) + + Stores TOS into the cell contained in slot *i* of the cell and free variable + storage. + + +.. opcode:: SET_LINENO (lineno) + + This opcode is obsolete. + + +.. opcode:: RAISE_VARARGS (argc) + + Raises an exception. *argc* indicates the number of parameters to the raise + statement, ranging from 0 to 3. The handler will find the traceback as TOS2, + the parameter as TOS1, and the exception as TOS. + + +.. opcode:: CALL_FUNCTION (argc) + + Calls a function. The low byte of *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. Pops all function arguments, and + the function itself off the stack, and pushes the return value. + + +.. opcode:: 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 *argc* default parameters, + which are found below TOS. + + +.. opcode:: MAKE_CLOSURE (argc) + + Creates a new function object, sets its *func_closure* slot, and pushes it on + the stack. TOS is the code associated with the function, TOS1 the tuple + containing cells for the closure's free variables. The function also has + *argc* default parameters, which are found below the cells. + + +.. opcode:: BUILD_SLICE (argc) + + .. index:: builtin: slice + + Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2, + ``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is + pushed. See the :func:`slice` built-in function for more information. + + +.. opcode:: EXTENDED_ARG (ext) + + Prefixes any opcode which has an argument too big to fit into the default two + bytes. *ext* holds two additional bytes which, taken together with the + subsequent opcode's argument, comprise a four-byte argument, *ext* being the two + most-significant bytes. + + +.. opcode:: CALL_FUNCTION_VAR (argc) + + Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element + on the stack contains the variable argument list, followed by keyword and + positional arguments. + + +.. opcode:: CALL_FUNCTION_KW (argc) + + Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top element + on the stack contains the keyword arguments dictionary, followed by explicit + keyword and positional arguments. + + +.. opcode:: CALL_FUNCTION_VAR_KW (argc) + + Calls a function. *argc* is interpreted as in ``CALL_FUNCTION``. The top + element on the stack contains the keyword arguments dictionary, followed by the + variable-arguments tuple, followed by explicit keyword and positional arguments. + + +.. opcode:: HAVE_ARGUMENT () + + This is not really an opcode. It identifies the dividing line between opcodes + which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>= + HAVE_ARGUMENT``. +