dis — Disassembler for Python bytecode — Python documentation
dis — Disassembler for Python bytecode
Source code: :source:`Lib/dis.py`
The dis module supports the analysis of CPython bytecode by disassembling it. The CPython bytecode which this module takes as an input is defined in the file Include/opcode.h
and used by the compiler and the interpreter.
Example: Given the function myfunc()
:
def myfunc(alist):
return len(alist)
the following command can be used to display the disassembly of myfunc()
:
>>> dis.dis(myfunc)
2 0 LOAD_GLOBAL 0 (len)
2 LOAD_FAST 0 (alist)
4 CALL_FUNCTION 1
6 RETURN_VALUE
(The “2” is a line number).
Bytecode analysis
New in version 3.4.
The bytecode analysis API allows pieces of Python code to be wrapped in a Bytecode object that provides easy access to details of the compiled code.
- class dis.Bytecode(x, *, first_line=None, current_offset=None)
Analyse the bytecode corresponding to a function, generator, asynchronous generator, coroutine, method, string of source code, or a code object (as returned by compile()).
This is a convenience wrapper around many of the functions listed below, most notably get_instructions(), as iterating over a Bytecode instance yields the bytecode operations as 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 dis() will display a “current instruction” marker against the specified opcode.- classmethod from_traceback(tb)
Construct a Bytecode instance from the given traceback, setting current_offset to the instruction responsible for the exception.
- codeobj
The compiled code object.
- first_line
The first source line of the code object (if available)
- dis()
Return a formatted view of the bytecode operations (the same as printed by dis.dis(), but returned as a multi-line string).
- info()
Return a formatted multi-line string with detailed information about the code object, like code_info().
Changed in version 3.7: This can now handle coroutine and asynchronous generator objects.
Example:
>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
... print(instr.opname)
...
LOAD_GLOBAL
LOAD_FAST
CALL_FUNCTION
RETURN_VALUE
Analysis functions
The 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:
- dis.code_info(x)
Return a formatted multi-line string with detailed code object information for the supplied function, generator, asynchronous generator, coroutine, 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.
New in version 3.2.
Changed in version 3.7: This can now handle coroutine and asynchronous generator objects.
- dis.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.New in version 3.2.
Changed in version 3.4: Added file parameter.
- dis.dis(x=None, *, file=None, depth=None)
Disassemble the x object. x can denote either a module, a class, a method, a function, a generator, an asynchronous generator, a coroutine, 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 (including class and static methods). For a code object or sequence of raw bytecode, it prints one line per bytecode instruction. It also recursively disassembles nested code objects (the code of comprehensions, generator expressions and nested functions, and the code used for building nested classes). Strings are first compiled to code objects with the 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.The maximal depth of recursion is limited by depth unless it is
None
.depth=0
means no recursion.Changed in version 3.4: Added file parameter.
Changed in version 3.7: Implemented recursive disassembling and added depth parameter.
Changed in version 3.7: This can now handle coroutine and asynchronous generator objects.
- dis.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.Changed in version 3.4: Added file parameter.
- dis.disassemble(code, lasti=- 1, *, file=None)
dis.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.Changed in version 3.4: Added file parameter.
- dis.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 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.New in version 3.4.
- dis.findlinestarts(code)
This generator function uses the
co_firstlineno
andco_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. See :source:`Objects/lnotab_notes.txt` for theco_lnotab
format and how to decode it.Changed in version 3.6: Line numbers can be decreasing. Before, they were always increasing.
- dis.findlabels(code)
- Detect all offsets in the raw compiled bytecode string code which are jump targets, and return a list of these offsets.
- dis.stack_effect(opcode[, oparg])
Compute the stack effect of opcode with argument oparg.
New in version 3.4.
Python Bytecode Instructions
The get_instructions() function and Bytecode class provide details of bytecode instructions as Instruction instances:
- class dis.Instruction
Details for a bytecode operation
- opcode
numeric code for operation, corresponding to the opcode values listed below and the bytecode values in the Opcode collections.
- opname
human readable name for operation
- arg
numeric argument to operation (if any), otherwise
None
- argval
resolved arg value (if known), otherwise same as arg
- argrepr
human readable description of operation argument
- offset
start index of operation within bytecode sequence
- starts_line
line started by this opcode (if any), otherwise
None
- is_jump_target
True
if other code jumps to here, otherwiseFalse
New in version 3.4.
The Python compiler currently generates the following bytecode instructions.
General instructions
Unary operations
Unary operations take the top of the stack, apply the operation, and push the result back on the stack.
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.
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.
Coroutine opcodes
Miscellaneous opcodes
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.
All of the following opcodes use their arguments.
Opcode collections
These collections are provided for automatic introspection of bytecode instructions:
- dis.opname
- Sequence of operation names, indexable using the bytecode.
- dis.opmap
- Dictionary mapping operation names to bytecodes.
- dis.cmp_op
- Sequence of all compare operation names.
- dis.hasconst
- Sequence of bytecodes that access a constant.
- dis.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).
- dis.hasname
- Sequence of bytecodes that access an attribute by name.
- dis.hasjrel
- Sequence of bytecodes that have a relative jump target.
- dis.hasjabs
- Sequence of bytecodes that have an absolute jump target.
- dis.haslocal
- Sequence of bytecodes that access a local variable.
- dis.hascompare
- Sequence of bytecodes of Boolean operations.