| :mod:`dis` --- Disassembler for Python bytecode |
| =============================================== |
| |
| .. module:: dis |
| :synopsis: Disassembler for Python bytecode. |
| |
| **Source code:** :source:`Lib/dis.py` |
| |
| -------------- |
| |
| The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by |
| disassembling it. The CPython 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. |
| |
| .. impl-detail:: |
| |
| Bytecode is an implementation detail of the CPython interpreter. No |
| guarantees are made that bytecode will not be added, removed, or changed |
| between versions of Python. Use of this module should not be considered to |
| work across Python VMs or Python releases. |
| |
| |
| Example: Given the function :func:`myfunc`:: |
| |
| def myfunc(alist): |
| return len(alist) |
| |
| the following command can be used to display 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). |
| |
| Bytecode analysis |
| ----------------- |
| |
| .. versionadded:: 3.4 |
| |
| The bytecode analysis API allows pieces of Python code to be wrapped in a |
| :class:`Bytecode` object that provides easy access to details of the compiled |
| code. |
| |
| .. class:: Bytecode(x, *, first_line=None, current_offset=None) |
| |
| |
| Analyse the bytecode corresponding to a function, generator, method, string |
| of source code, or a code object (as returned by :func:`compile`). |
| |
| This is a convenience wrapper around many of the functions listed below, most |
| notably :func:`get_instructions`, as iterating over a :class:`Bytecode` |
| instance yields the bytecode operations as :class:`Instruction` instances. |
| |
| If *first_line* is not None, it indicates the line number that should be |
| reported for the first source line in the disassembled code. Otherwise, the |
| source line information (if any) is taken directly from the disassembled code |
| object. |
| |
| If *current_offset* is not None, it refers to an instruction offset in the |
| disassembled code. Setting this means :meth:`.dis` will display a "current |
| instruction" marker against the specified opcode. |
| |
| .. classmethod:: from_traceback(tb) |
| |
| Construct a :class:`Bytecode` instance from the given traceback, setting |
| *current_offset* to the instruction responsible for the exception. |
| |
| .. data:: codeobj |
| |
| The compiled code object. |
| |
| .. data:: first_line |
| |
| The first source line of the code object (if available) |
| |
| .. method:: dis() |
| |
| Return a formatted view of the bytecode operations (the same as printed by |
| :func:`dis.dis`, but returned as a multi-line string). |
| |
| .. method:: info() |
| |
| Return a formatted multi-line string with detailed information about the |
| code object, like :func:`code_info`. |
| |
| Example:: |
| |
| >>> bytecode = dis.Bytecode(myfunc) |
| >>> for instr in bytecode: |
| ... print(instr.opname) |
| ... |
| LOAD_GLOBAL |
| LOAD_FAST |
| CALL_FUNCTION |
| RETURN_VALUE |
| |
| |
| Analysis functions |
| ------------------ |
| |
| The :mod:`dis` module also defines the following analysis functions that convert |
| the input directly to the desired output. They can be useful if only a single |
| operation is being performed, so the intermediate analysis object isn't useful: |
| |
| .. function:: code_info(x) |
| |
| Return a formatted multi-line string with detailed code object information |
| for the supplied function, generator, method, source code string or code object. |
| |
| Note that the exact contents of code info strings are highly implementation |
| dependent and they may change arbitrarily across Python VMs or Python |
| releases. |
| |
| .. versionadded:: 3.2 |
| |
| |
| .. function:: show_code(x, *, file=None) |
| |
| Print detailed code object information for the supplied function, method, |
| source code string or code object to *file* (or ``sys.stdout`` if *file* |
| is not specified). |
| |
| This is a convenient shorthand for ``print(code_info(x), file=file)``, |
| intended for interactive exploration at the interpreter prompt. |
| |
| .. versionadded:: 3.2 |
| |
| .. versionchanged:: 3.4 |
| Added *file* parameter. |
| |
| |
| .. function:: dis(x=None, *, file=None) |
| |
| Disassemble the *x* object. *x* can denote either a module, a class, a |
| method, a function, a generator, a code object, a string of source code or |
| a byte sequence of raw bytecode. For a module, it disassembles all functions. |
| For a class, it disassembles all methods. For a code object or sequence of |
| raw bytecode, it prints one line per bytecode instruction. Strings are first |
| compiled to code objects with the :func:`compile` built-in function before being |
| disassembled. If no object is provided, this function disassembles the last |
| traceback. |
| |
| The disassembly is written as text to the supplied *file* argument if |
| provided and to ``sys.stdout`` otherwise. |
| |
| .. versionchanged:: 3.4 |
| Added *file* parameter. |
| |
| |
| .. function:: distb(tb=None, *, file=None) |
| |
| Disassemble the top-of-stack function of a traceback, using the last |
| traceback if none was passed. The instruction causing the exception is |
| indicated. |
| |
| The disassembly is written as text to the supplied *file* argument if |
| provided and to ``sys.stdout`` otherwise. |
| |
| .. versionchanged:: 3.4 |
| Added *file* parameter. |
| |
| |
| .. function:: disassemble(code, lasti=-1, *, file=None) |
| disco(code, lasti=-1, *, file=None) |
| |
| Disassemble 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. |
| |
| The disassembly is written as text to the supplied *file* argument if |
| provided and to ``sys.stdout`` otherwise. |
| |
| .. versionchanged:: 3.4 |
| Added *file* parameter. |
| |
| |
| .. function:: get_instructions(x, *, first_line=None) |
| |
| Return an iterator over the instructions in the supplied function, method, |
| source code string or code object. |
| |
| The iterator generates a series of :class:`Instruction` named tuples giving |
| the details of each operation in the supplied code. |
| |
| If *first_line* is not None, it indicates the line number that should be |
| reported for the first source line in the disassembled code. Otherwise, the |
| source line information (if any) is taken directly from the disassembled code |
| object. |
| |
| .. versionadded:: 3.4 |
| |
| |
| .. function:: findlinestarts(code) |
| |
| This generator function uses the ``co_firstlineno`` and ``co_lnotab`` |
| attributes of the code object *code* to find the offsets which are starts of |
| lines in the source code. They are generated as ``(offset, lineno)`` pairs. |
| |
| |
| .. function:: findlabels(code) |
| |
| Detect all offsets in the code object *code* which are jump targets, and |
| return a list of these offsets. |
| |
| |
| .. function:: stack_effect(opcode, [oparg]) |
| |
| Compute the stack effect of *opcode* with argument *oparg*. |
| |
| .. versionadded:: 3.4 |
| |
| .. _bytecodes: |
| |
| Python Bytecode Instructions |
| ---------------------------- |
| |
| The :func:`get_instructions` function and :class:`Bytecode` class provide |
| details of bytecode instructions as :class:`Instruction` instances: |
| |
| .. class:: Instruction |
| |
| Details for a bytecode operation |
| |
| .. data:: opcode |
| |
| numeric code for operation, corresponding to the opcode values listed |
| below and the bytecode values in the :ref:`opcode_collections`. |
| |
| |
| .. data:: opname |
| |
| human readable name for operation |
| |
| |
| .. data:: arg |
| |
| numeric argument to operation (if any), otherwise None |
| |
| |
| .. data:: argval |
| |
| resolved arg value (if known), otherwise same as arg |
| |
| |
| .. data:: argrepr |
| |
| human readable description of operation argument |
| |
| |
| .. data:: offset |
| |
| start index of operation within bytecode sequence |
| |
| |
| .. data:: starts_line |
| |
| line started by this opcode (if any), otherwise None |
| |
| |
| .. data:: is_jump_target |
| |
| ``True`` if other code jumps to here, otherwise ``False`` |
| |
| .. versionadded:: 3.4 |
| |
| |
| The Python compiler currently generates the following bytecode instructions. |
| |
| |
| **General instructions** |
| |
| .. 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:: DUP_TOP |
| |
| Duplicates the reference on top of the stack. |
| |
| |
| .. opcode:: DUP_TOP_TWO |
| |
| Duplicates the two references on top of the stack, leaving them in the |
| same order. |
| |
| |
| **Unary operations** |
| |
| 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_INVERT |
| |
| Implements ``TOS = ~TOS``. |
| |
| |
| .. opcode:: GET_ITER |
| |
| Implements ``TOS = iter(TOS)``. |
| |
| |
| .. opcode:: GET_YIELD_FROM_ITER |
| |
| If ``TOS`` is a :term:`generator iterator` or :term:`coroutine` object |
| it is left as is. Otherwise, implements ``TOS = iter(TOS)``. |
| |
| .. versionadded:: 3.5 |
| |
| |
| **Binary operations** |
| |
| 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_MATRIX_MULTIPLY |
| |
| Implements ``TOS = TOS1 @ TOS``. |
| |
| .. versionadded:: 3.5 |
| |
| |
| .. opcode:: BINARY_FLOOR_DIVIDE |
| |
| Implements ``TOS = TOS1 // TOS``. |
| |
| |
| .. opcode:: BINARY_TRUE_DIVIDE |
| |
| Implements ``TOS = TOS1 / TOS``. |
| |
| |
| .. 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** |
| |
| 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_MATRIX_MULTIPLY |
| |
| Implements in-place ``TOS = TOS1 @ TOS``. |
| |
| .. versionadded:: 3.5 |
| |
| |
| .. opcode:: INPLACE_FLOOR_DIVIDE |
| |
| Implements in-place ``TOS = TOS1 // TOS``. |
| |
| |
| .. opcode:: INPLACE_TRUE_DIVIDE |
| |
| Implements in-place ``TOS = TOS1 / TOS``. |
| |
| |
| .. 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``. |
| |
| |
| .. opcode:: STORE_SUBSCR |
| |
| Implements ``TOS1[TOS] = TOS2``. |
| |
| |
| .. opcode:: DELETE_SUBSCR |
| |
| Implements ``del TOS1[TOS]``. |
| |
| |
| **Coroutine opcodes** |
| |
| .. opcode:: GET_AWAITABLE |
| |
| Implements ``TOS = get_awaitable(TOS)``, where ``get_awaitable(o)`` |
| returns ``o`` if ``o`` is a coroutine object or a generator object with |
| the CO_ITERABLE_COROUTINE flag, or resolves |
| ``o.__await__``. |
| |
| |
| .. opcode:: GET_AITER |
| |
| Implements ``TOS = get_awaitable(TOS.__aiter__())``. See ``GET_AWAITABLE`` |
| for details about ``get_awaitable`` |
| |
| |
| .. opcode:: GET_ANEXT |
| |
| Implements ``PUSH(get_awaitable(TOS.__anext__()))``. See ``GET_AWAITABLE`` |
| for details about ``get_awaitable`` |
| |
| |
| .. opcode:: BEFORE_ASYNC_WITH |
| |
| Resolves ``__aenter__`` and ``__aexit__`` from the object on top of the |
| stack. Pushes ``__aexit__`` and result of ``__aenter__()`` to the stack. |
| |
| |
| .. opcode:: SETUP_ASYNC_WITH |
| |
| Creates a new frame object. |
| |
| |
| |
| **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 :opcode:`POP_TOP`. |
| |
| |
| .. 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 :opcode:`FOR_ITER` instruction). |
| |
| |
| .. opcode:: SET_ADD (i) |
| |
| Calls ``set.add(TOS1[-i], TOS)``. Used to implement set comprehensions. |
| |
| |
| .. opcode:: LIST_APPEND (i) |
| |
| Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions. |
| |
| |
| .. opcode:: MAP_ADD (i) |
| |
| Calls ``dict.setitem(TOS1[-i], TOS, TOS1)``. Used to implement dict |
| comprehensions. |
| |
| For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:`MAP_ADD` |
| instructions, while the added value or key/value pair is popped off, the |
| container object remains on the stack so that it is available for further |
| iterations of the loop. |
| |
| |
| .. 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:: YIELD_FROM |
| |
| Pops TOS and delegates to it as a subiterator from a :term:`generator`. |
| |
| .. versionadded:: 3.3 |
| |
| |
| .. 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:: 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:: POP_EXCEPT |
| |
| Removes one block from the block stack. The popped block must be an exception |
| handler block, as implicitly created when entering an except handler. In |
| addition to popping extraneous values from the frame stack, the last three |
| popped values are used to restore the exception state. |
| |
| |
| .. 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:: LOAD_BUILD_CLASS |
| |
| Pushes :func:`builtins.__build_class__` onto the stack. It is later called |
| by :opcode:`CALL_FUNCTION` to construct a class. |
| |
| |
| .. opcode:: SETUP_WITH (delta) |
| |
| This opcode performs several operations before a with block starts. First, |
| it loads :meth:`~object.__exit__` from the context manager and pushes it onto |
| the stack for later use by :opcode:`WITH_CLEANUP`. Then, |
| :meth:`~object.__enter__` is called, and a finally block pointing to *delta* |
| is pushed. Finally, the result of calling the enter method is pushed onto |
| the stack. The next opcode will either ignore it (:opcode:`POP_TOP`), or |
| store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or |
| :opcode:`UNPACK_SEQUENCE`). |
| |
| |
| .. opcode:: WITH_CLEANUP_START |
| |
| Cleans up the stack when a :keyword:`with` statement block exits. TOS is the |
| context manager's :meth:`__exit__` bound method. Below TOS are 1--3 values |
| indicating how/why the finally clause was entered: |
| |
| * SECOND = ``None`` |
| * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval |
| * SECOND = ``WHY_*``; no retval below it |
| * (SECOND, THIRD, FOURTH) = exc_info() |
| |
| In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise |
| ``TOS(None, None, None)``. Pushes SECOND and result of the call |
| to the stack. |
| |
| |
| .. opcode:: WITH_CLEANUP_FINISH |
| |
| Pops exception type and result of 'exit' function call from the stack. |
| |
| If the stack represents an exception, *and* the function call returns a |
| 'true' value, this information is "zapped" and replaced with a single |
| ``WHY_SILENCED`` to prevent :opcode:`END_FINALLY` from re-raising the |
| exception. (But non-local gotos will 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 |
| :opcode:`STORE_FAST` or :opcode:`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:: UNPACK_EX (counts) |
| |
| Implements assignment with a starred target: Unpacks an iterable in TOS into |
| individual values, where the total number of values can be smaller than the |
| number of items in the iterable: one the new values will be a list of all |
| leftover items. |
| |
| The low byte of *counts* is the number of values before the list value, the |
| high byte of *counts* the number of values after it. The resulting values |
| are put onto the stack right-to-left. |
| |
| |
| .. 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 :opcode:`STORE_NAME`, but stores the name as a global. |
| |
| |
| .. opcode:: DELETE_GLOBAL (namei) |
| |
| Works as :opcode:`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 :opcode:`BUILD_TUPLE`, but creates a list. |
| |
| |
| .. opcode:: BUILD_SET (count) |
| |
| Works as :opcode:`BUILD_TUPLE`, but creates a set. |
| |
| |
| .. 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 :opcode:`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 |
| :opcode:`STORE_FAST` instruction. |
| |
| |
| .. opcode:: JUMP_FORWARD (delta) |
| |
| Increments bytecode counter by *delta*. |
| |
| |
| .. opcode:: POP_JUMP_IF_TRUE (target) |
| |
| If TOS is true, sets the bytecode counter to *target*. TOS is popped. |
| |
| |
| .. opcode:: POP_JUMP_IF_FALSE (target) |
| |
| If TOS is false, sets the bytecode counter to *target*. TOS is popped. |
| |
| |
| .. opcode:: JUMP_IF_TRUE_OR_POP (target) |
| |
| If TOS is true, sets the bytecode counter to *target* and leaves TOS on the |
| stack. Otherwise (TOS is false), TOS is popped. |
| |
| |
| .. opcode:: JUMP_IF_FALSE_OR_POP (target) |
| |
| If TOS is false, sets the bytecode counter to *target* and leaves TOS on the |
| stack. Otherwise (TOS is true), TOS is popped. |
| |
| |
| .. opcode:: JUMP_ABSOLUTE (target) |
| |
| Set bytecode counter to *target*. |
| |
| |
| .. opcode:: FOR_ITER (delta) |
| |
| TOS is an :term:`iterator`. Call its :meth:`~iterator.__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 byte |
| code 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:: 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:: LOAD_CLASSDEREF (i) |
| |
| Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before |
| consulting the cell. This is used for loading free variables in class |
| bodies. |
| |
| |
| .. opcode:: STORE_DEREF (i) |
| |
| Stores TOS into the cell contained in slot *i* of the cell and free variable |
| storage. |
| |
| |
| .. opcode:: DELETE_DEREF (i) |
| |
| Empties the cell contained in slot *i* of the cell and free variable storage. |
| Used by the :keyword:`del` statement. |
| |
| |
| .. 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. From bottom to top, the consumed |
| stack must consist of |
| |
| * ``argc & 0xFF`` default argument objects in positional order |
| * ``(argc >> 8) & 0xFF`` pairs of name and default argument, with the name |
| just below the object on the stack, for keyword-only parameters |
| * ``(argc >> 16) & 0x7FFF`` parameter annotation objects |
| * a tuple listing the parameter names for the annotations (only if there are |
| ony annotation objects) |
| * the code associated with the function (at TOS1) |
| * the :term:`qualified name` of the function (at TOS) |
| |
| |
| .. opcode:: MAKE_CLOSURE (argc) |
| |
| Creates a new function object, sets its *__closure__* slot, and pushes it on |
| the stack. TOS is the :term:`qualified name` of the function, TOS1 is the |
| code associated with the function, and TOS2 is the tuple containing cells for |
| the closure's free variables. *argc* is interpreted as in ``MAKE_FUNCTION``; |
| the annotations and defaults are also in the same order below TOS2. |
| |
| |
| .. 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 :opcode:`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 :opcode:`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 :opcode:`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:: FORMAT_VALUE (flags) |
| |
| Used for implementing formatted literal strings (f-strings). Pops |
| an optional *fmt_spec* from the stack, then a required *value*. |
| *flags* is interpreted as follows: |
| |
| * ``(flags & 0x03) == 0x00``: *value* is formatted as-is. |
| * ``(flags & 0x03) == 0x01``: call :func:`str` on *value* before |
| formatting it. |
| * ``(flags & 0x03) == 0x02``: call :func:`repr` on *value* before |
| formatting it. |
| * ``(flags & 0x03) == 0x03``: call :func:`ascii` on *value* before |
| formatting it. |
| * ``(flags & 0x04) == 0x04``: pop *fmt_spec* from the stack and use |
| it, else use an empty *fmt_spec*. |
| |
| Formatting is performed using :c:func:`PyObject_Format`. The |
| result is pushed on the stack. |
| |
| .. versionadded:: 3.6 |
| |
| |
| .. 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``. |
| |
| .. _opcode_collections: |
| |
| Opcode collections |
| ------------------ |
| |
| These collections are provided for automatic introspection of bytecode |
| instructions: |
| |
| .. data:: opname |
| |
| Sequence of operation names, indexable using the bytecode. |
| |
| |
| .. data:: opmap |
| |
| Dictionary mapping operation names to bytecodes. |
| |
| |
| .. 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 (note that 'free' in this |
| context refers to names in the current scope that are referenced by inner |
| scopes or names in outer scopes that are referenced from this scope. It does |
| *not* include references to global or builtin scopes). |
| |
| |
| .. 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. |