Source code: 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.
CPython implementation 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.
Changed in version 3.6: Use 2 bytes for each instruction. Previously the number of bytes varied by instruction.
Example: Given the function myfunc():
the following command can be used to display the disassembly of myfunc():
(The “2” is a line number).
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.
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.
Construct a Bytecode instance from the given traceback, setting current_offset to the instruction responsible for the exception.
The compiled code object.
The first source line of the code object (if available)
Return a formatted view of the bytecode operations (the same as printed by dis.dis(), but returned as a multi-line string).
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:
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:
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.
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.
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.
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.
Disassemble a code object, indicating the last instruction if lasti was provided. The output is divided in the following columns:
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.
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.
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. See Objects/lnotab_notes.txt for the co_lnotab format and how to decode it.
Changed in version 3.6: Line numbers can be decreasing. Before, they were always increasing.
Detect all offsets in the raw compiled bytecode string code which are jump targets, and return a list of these offsets.
Compute the stack effect of opcode with argument oparg.
If the code has a jump target and jump is True, stack_effect() will return the stack effect of jumping. If jump is False, it will return the stack effect of not jumping. And if jump is None (default), it will return the maximal stack effect of both cases.
New in version 3.4.
Changed in version 3.8: Added jump parameter.
The get_instructions() function and Bytecode class provide details of bytecode instructions as Instruction instances:
Details for a bytecode operation
numeric code for operation, corresponding to the opcode values listed below and the bytecode values in the Opcode collections.
human readable name for operation
numeric argument to operation (if any), otherwise None
resolved arg value (if known), otherwise same as arg
human readable description of operation argument
start index of operation within bytecode sequence
line started by this opcode (if any), otherwise None
True if other code jumps to here, otherwise False
New in version 3.4.
The Python compiler currently generates the following bytecode instructions.
General instructions
Do nothing code. Used as a placeholder by the bytecode optimizer.
Removes the top-of-stack (TOS) item.
Swaps the two top-most stack items.
Lifts second and third stack item one position up, moves top down to position three.
Lifts second, third and fourth stack items one position up, moves top down to position four.
New in version 3.8.
Duplicates the reference on top of the stack.
New in version 3.2.
Duplicates the two references on top of the stack, leaving them in the same order.
New in version 3.2.
Unary operations
Unary operations take the top of the stack, apply the operation, and push the result back on the stack.
Implements TOS = +TOS.
Implements TOS = -TOS.
Implements TOS = not TOS.
Implements TOS = ~TOS.
Implements TOS = iter(TOS).
If TOS is a generator iterator or coroutine object it is left as is. Otherwise, implements TOS = iter(TOS).
New in version 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.
Implements TOS = TOS1 ** TOS.
Implements TOS = TOS1 * TOS.
Implements TOS = TOS1 @ TOS.
New in version 3.5.
Implements TOS = TOS1 // TOS.
Implements TOS = TOS1 / TOS.
Implements TOS = TOS1 % TOS.
Implements TOS = TOS1 + TOS.
Implements TOS = TOS1 - TOS.
Implements TOS = TOS1[TOS].
Implements TOS = TOS1 << TOS.
Implements TOS = TOS1 >> TOS.
Implements TOS = TOS1 & TOS.
Implements TOS = TOS1 ^ TOS.
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.
Implements in-place TOS = TOS1 ** TOS.
Implements in-place TOS = TOS1 * TOS.
Implements in-place TOS = TOS1 @ TOS.
New in version 3.5.
Implements in-place TOS = TOS1 // TOS.
Implements in-place TOS = TOS1 / TOS.
Implements in-place TOS = TOS1 % TOS.
Implements in-place TOS = TOS1 + TOS.
Implements in-place TOS = TOS1 - TOS.
Implements in-place TOS = TOS1 << TOS.
Implements in-place TOS = TOS1 >> TOS.
Implements in-place TOS = TOS1 & TOS.
Implements in-place TOS = TOS1 ^ TOS.
Implements in-place TOS = TOS1 | TOS.
Implements TOS1[TOS] = TOS2.
Implements del TOS1[TOS].
Coroutine opcodes
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__.
New in version 3.5.
Implements TOS = TOS.__aiter__().
New in version 3.5.
Changed in version 3.7: Returning awaitable objects from __aiter__ is no longer supported.
Implements PUSH(get_awaitable(TOS.__anext__())). See GET_AWAITABLE for details about get_awaitable
New in version 3.5.
Terminates an async for loop. Handles an exception raised when awaiting a next item. If TOS is StopAsyncIteration pop 7 values from the stack and restore the exception state using the second three of them. Otherwise re-raise the exception using the three values from the stack. An exception handler block is removed from the block stack.
New in version 3.8.
Resolves __aenter__ and __aexit__ from the object on top of the stack. Pushes __aexit__ and result of __aenter__() to the stack.
New in version 3.5.
Creates a new frame object.
New in version 3.5.
Miscellaneous opcodes
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_TOP.
Calls set.add(TOS1[-i], TOS). Used to implement set comprehensions.
Calls list.append(TOS1[-i], TOS). Used to implement list comprehensions.
Calls dict.__setitem__(TOS1[-i], TOS1, TOS). Used to implement dict comprehensions.
New in version 3.1.
Changed in version 3.8: Map value is TOS and map key is TOS1. Before, those were reversed.
For all of the SET_ADD, LIST_APPEND and 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.
Returns with TOS to the caller of the function.
Pops TOS and yields it from a generator.
Pops TOS and delegates to it as a subiterator from a generator.
New in version 3.3.
Checks whether __annotations__ is defined in locals(), if not it is set up to an empty dict. This opcode is only emitted if a class or module body contains variable annotations statically.
New in version 3.6.
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 *.
Removes one block from the block stack. Per frame, there is a stack of blocks, denoting try statements, and such.
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.
Re-raises the exception currently on top of the stack.
New in version 3.9.
Calls the function in position 7 on the stack with the top three items on the stack as arguments. Used to implement the call context_manager.__exit__(*exc_info()) when an exception has occurred in a with statement.
New in version 3.9.
Pushes AssertionError onto the stack. Used by the assert statement.
New in version 3.9.
Pushes builtins.__build_class__() onto the stack. It is later called by CALL_FUNCTION to construct a class.
This opcode performs several operations before a with block starts. First, it loads __exit__() from the context manager and pushes it onto the stack for later use by WITH_CLEANUP_START. Then, __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 (POP_TOP), or store it in (a) variable(s) (STORE_FAST, STORE_NAME, or UNPACK_SEQUENCE).
New in version 3.2.
All of the following opcodes use their arguments.
Implements name = TOS. namei is the index of name in the attribute co_names of the code object. The compiler tries to use STORE_FAST or STORE_GLOBAL if possible.
Implements del name, where namei is the index into co_names attribute of the code object.
Unpacks TOS into count individual values, which are put onto the stack right-to-left.
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 of 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.
Implements TOS.name = TOS1, where namei is the index of name in co_names.
Implements del TOS.name, using namei as index into co_names.
Works as STORE_NAME, but stores the name as a global.
Works as DELETE_NAME, but deletes a global name.
Pushes co_consts[consti] onto the stack.
Pushes the value associated with co_names[namei] onto the stack.
Creates a tuple consuming count items from the stack, and pushes the resulting tuple onto the stack.
Works as BUILD_TUPLE, but creates a list.
Works as BUILD_TUPLE, but creates a set.
Pushes a new dictionary object onto the stack. Pops 2 * count items so that the dictionary holds count entries: {..., TOS3: TOS2, TOS1: TOS}.
Changed in version 3.5: The dictionary is created from stack items instead of creating an empty dictionary pre-sized to hold count items.
The version of BUILD_MAP specialized for constant keys. Pops the top element on the stack which contains a tuple of keys, then starting from TOS1, pops count values to form values in the built dictionary.
New in version 3.6.
Concatenates count strings from the stack and pushes the resulting string onto the stack.
New in version 3.6.
Pops a list from the stack and pushes a tuple containing the same values.
New in version 3.9.
Calls list.extend(TOS1[-i], TOS). Used to build lists.
New in version 3.9.
Calls set.update(TOS1[-i], TOS). Used to build sets.
New in version 3.9.
Calls dict.update(TOS1[-i], TOS). Used to build dicts.
New in version 3.9.
Like DICT_UPDATE but raises an exception for duplicate keys.
New in version 3.9.
Replaces TOS with getattr(TOS, co_names[namei]).
Performs a Boolean operation. The operation name can be found in cmp_op[opname].
Performs is comparison, or is not if invert is 1.
New in version 3.9.
Performs in comparison, or not in if invert is 1.
New in version 3.9.
Imports the module co_names[namei]. TOS and TOS1 are popped and provide the fromlist and level arguments of __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.
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.
Increments bytecode counter by delta.
If TOS is true, sets the bytecode counter to target. TOS is popped.
New in version 3.1.
If TOS is false, sets the bytecode counter to target. TOS is popped.
New in version 3.1.
Tests whether the second value on the stack is an exception matching TOS, and jumps if it is not. Pops two values from the stack.
New in version 3.9.
If TOS is true, sets the bytecode counter to target and leaves TOS on the stack. Otherwise (TOS is false), TOS is popped.
New in version 3.1.
If TOS is false, sets the bytecode counter to target and leaves TOS on the stack. Otherwise (TOS is true), TOS is popped.
New in version 3.1.
Set bytecode counter to target.
TOS is an iterator. Call its __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.
Loads the global named co_names[namei] onto the stack.
Pushes a try block from a try-finally or try-except clause onto the block stack. delta points to the finally block or the first except block.
Pushes a reference to the local co_varnames[var_num] onto the stack.
Stores TOS into the local co_varnames[var_num].
Deletes local co_varnames[var_num].
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)].
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.
Much like LOAD_DEREF but first checks the locals dictionary before consulting the cell. This is used for loading free variables in class bodies.
New in version 3.4.
Stores TOS into the cell contained in slot i of the cell and free variable storage.
Empties the cell contained in slot i of the cell and free variable storage. Used by the del statement.
New in version 3.2.
Raises an exception using one of the 3 forms of the raise statement, depending on the value of argc:
Calls a callable object with positional arguments. argc indicates the number of positional arguments. The top of the stack contains positional arguments, with the right-most argument on top. Below the arguments is a callable object to call. CALL_FUNCTION pops all arguments and the callable object off the stack, calls the callable object with those arguments, and pushes the return value returned by the callable object.
Changed in version 3.6: This opcode is used only for calls with positional arguments.
Calls a callable object with positional (if any) and keyword arguments. argc indicates the total number of positional and keyword arguments. The top element on the stack contains a tuple with the names of the keyword arguments, which must be strings. Below that are the values for the keyword arguments, in the order corresponding to the tuple. Below that are positional arguments, with the right-most parameter on top. Below the arguments is a callable object to call. CALL_FUNCTION_KW pops all arguments and the callable object off the stack, calls the callable object with those arguments, and pushes the return value returned by the callable object.
Changed in version 3.6: Keyword arguments are packed in a tuple instead of a dictionary, argc indicates the total number of arguments.
Calls a callable object with variable set of positional and keyword arguments. If the lowest bit of flags is set, the top of the stack contains a mapping object containing additional keyword arguments. Before the callable is called, the mapping object and iterable object are each “unpacked” and their contents passed in as keyword and positional arguments respectively. CALL_FUNCTION_EX pops all arguments and the callable object off the stack, calls the callable object with those arguments, and pushes the return value returned by the callable object.
New in version 3.6.
Loads a method named co_names[namei] from the TOS object. TOS is popped. This bytecode distinguishes two cases: if TOS has a method with the correct name, the bytecode pushes the unbound method and TOS. TOS will be used as the first argument (self) by CALL_METHOD when calling the unbound method. Otherwise, NULL and the object return by the attribute lookup are pushed.
New in version 3.7.
Calls a method. argc is the number of positional arguments. Keyword arguments are not supported. This opcode is designed to be used with LOAD_METHOD. Positional arguments are on top of the stack. Below them, the two items described in LOAD_METHOD are on the stack (either self and an unbound method object or NULL and an arbitrary callable). All of them are popped and the return value is pushed.
New in version 3.7.
Pushes a new function object on the stack. From bottom to top, the consumed stack must consist of values if the argument carries a specified flag value
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 slice() built-in function for more information.
Prefixes any opcode which has an argument too big to fit into the default one byte. ext holds an additional byte which act as higher bits in the argument. For each opcode, at most three prefixal EXTENDED_ARG are allowed, forming an argument from two-byte to four-byte.
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:
Formatting is performed using PyObject_Format(). The result is pushed on the stack.
New in version 3.6.
This is not really an opcode. It identifies the dividing line between opcodes which don’t use their argument and those that do (< HAVE_ARGUMENT and >= HAVE_ARGUMENT, respectively).
Changed in version 3.6: Now every instruction has an argument, but opcodes < HAVE_ARGUMENT ignore it. Before, only opcodes >= HAVE_ARGUMENT had an argument.
These collections are provided for automatic introspection of bytecode instructions:
Sequence of operation names, indexable using the bytecode.
Dictionary mapping operation names to bytecodes.
Sequence of all compare operation names.
Sequence of bytecodes that access a constant.
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).
Sequence of bytecodes that access an attribute by name.
Sequence of bytecodes that have a relative jump target.
Sequence of bytecodes that have an absolute jump target.
Sequence of bytecodes that access a local variable.
Sequence of bytecodes of Boolean operations.


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.
Construct a Bytecode instance from the given traceback, setting current_offset to the instruction responsible for the exception.
The compiled code object.
The first source line of the code object (if available)
Return a formatted view of the bytecode operations (the same as printed by dis.dis(), but returned as a multi-line string).
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.


Return a formatted view of the bytecode operations (the same as printed by dis.dis(), but returned as a multi-line string).


The first source line of the code object (if available)


Construct a Bytecode instance from the given traceback, setting current_offset to the instruction responsible for the exception.


Return a formatted multi-line string with detailed information about the code object, like code_info().


Sequence of all compare operation names.


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.


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.


Disassemble a code object, indicating the last instruction if lasti was provided. The output is divided in the following columns:
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.


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.


Detect all offsets in the raw compiled bytecode string code which are jump targets, and return a list of these offsets.


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. See Objects/lnotab_notes.txt for the co_lnotab format and how to decode it.
Changed in version 3.6: Line numbers can be decreasing. Before, they were always increasing.


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.


Sequence of bytecodes of Boolean operations.


Sequence of bytecodes that access a constant.


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).


Sequence of bytecodes that have an absolute jump target.


Sequence of bytecodes that have a relative jump target.


Sequence of bytecodes that access a local variable.


Sequence of bytecodes that access an attribute by name.


Details for a bytecode operation
numeric code for operation, corresponding to the opcode values listed below and the bytecode values in the Opcode collections.
human readable name for operation
numeric argument to operation (if any), otherwise None
resolved arg value (if known), otherwise same as arg
human readable description of operation argument
start index of operation within bytecode sequence
line started by this opcode (if any), otherwise None
True if other code jumps to here, otherwise False
New in version 3.4.


numeric argument to operation (if any), otherwise None


human readable description of operation argument


resolved arg value (if known), otherwise same as arg


True if other code jumps to here, otherwise False


start index of operation within bytecode sequence


numeric code for operation, corresponding to the opcode values listed below and the bytecode values in the Opcode collections.


line started by this opcode (if any), otherwise None


Dictionary mapping operation names to bytecodes.


Sequence of operation names, indexable using the bytecode.


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.


Compute the stack effect of opcode with argument oparg.
If the code has a jump target and jump is True, stack_effect() will return the stack effect of jumping. If jump is False, it will return the stack effect of not jumping. And if jump is None (default), it will return the maximal stack effect of both cases.
New in version 3.4.
Changed in version 3.8: Added jump parameter.


The distutils package provides support for building and installing additional modules into a Python installation. The new modules may be either 100%-pure Python, or may be extension modules written in C, or may be collections of Python packages which include modules coded in both Python and C.
Most Python users will not want to use this module directly, but instead use the cross-version tools maintained by the Python Packaging Authority. In particular, setuptools is an enhanced alternative to distutils that provides:
The recommended pip installer runs all setup.py scripts with setuptools, even if the script itself only imports distutils. Refer to the Python Packaging User Guide for more information.
For the benefits of packaging tool authors and users seeking a deeper understanding of the details of the current packaging and distribution system, the legacy distutils based user documentation and API reference remain available:


Take two (non complex) numbers as arguments and return a pair of numbers consisting of their quotient and remainder when using integer division. With mixed operand types, the rules for binary arithmetic operators apply. For integers, the result is the same as (a // b, a % b). For floating point numbers the result is (q, a % b), where q is usually math.floor(a /
b) but may be 1 less than that. In any case q * b + a % b is very close to a, if a % b is non-zero it has the same sign as b, and 0
<= abs(a % b) < abs(b).


Source code: Lib/doctest.py
The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use doctest:
Here’s a complete but small example module:
If you run example.py directly from the command line, doctest works its magic:
There’s no output! That’s normal, and it means all the examples worked. Pass -v to the script, and doctest prints a detailed log of what it’s trying, and prints a summary at the end:
And so on, eventually ending with:
That’s all you need to know to start making productive use of doctest! Jump in. The following sections provide full details. Note that there are many examples of doctests in the standard Python test suite and libraries. Especially useful examples can be found in the standard test file Lib/test/test_doctest.py.
The simplest way to start using doctest (but not necessarily the way you’ll continue to do it) is to end each module M with:
doctest then examines docstrings in module M.
Running the module as a script causes the examples in the docstrings to get executed and verified:
This won’t display anything unless an example fails, in which case the failing example(s) and the cause(s) of the failure(s) are printed to stdout, and the final line of output is ***Test Failed*** N failures., where N is the number of examples that failed.
Run it with the -v switch instead:
and a detailed report of all examples tried is printed to standard output, along with assorted summaries at the end.
You can force verbose mode by passing verbose=True to testmod(), or prohibit it by passing verbose=False. In either of those cases, sys.argv is not examined by testmod() (so passing -v or not has no effect).
There is also a command line shortcut for running testmod(). You can instruct the Python interpreter to run the doctest module directly from the standard library and pass the module name(s) on the command line:
This will import example.py as a standalone module and run testmod() on it. Note that this may not work correctly if the file is part of a package and imports other submodules from that package.
For more information on testmod(), see section Basic API.
Another simple application of doctest is testing interactive examples in a text file. This can be done with the testfile() function:
That short script executes and verifies any interactive Python examples contained in the file example.txt. The file content is treated as if it were a single giant docstring; the file doesn’t need to contain a Python program! For example, perhaps example.txt contains this:
Running doctest.testfile("example.txt") then finds the error in this documentation:
As with testmod(), testfile() won’t display anything unless an example fails. If an example does fail, then the failing example(s) and the cause(s) of the failure(s) are printed to stdout, using the same format as testmod().
By default, testfile() looks for files in the calling module’s directory. See section Basic API for a description of the optional arguments that can be used to tell it to look for files in other locations.
Like testmod(), testfile()’s verbosity can be set with the -v command-line switch or with the optional keyword argument verbose.
There is also a command line shortcut for running testfile(). You can instruct the Python interpreter to run the doctest module directly from the standard library and pass the file name(s) on the command line:
Because the file name does not end with .py, doctest infers that it must be run with testfile(), not testmod().
For more information on testfile(), see section Basic API.
This section examines in detail how doctest works: which docstrings it looks at, how it finds interactive examples, what execution context it uses, how it handles exceptions, and how option flags can be used to control its behavior. This is the information that you need to know to write doctest examples; for information about actually running doctest on these examples, see the following sections.
The module docstring, and all function, class and method docstrings are searched. Objects imported into the module are not searched.
In addition, if M.__test__ exists and “is true”, it must be a dict, and each entry maps a (string) name to a function object, class object, or string. Function and class object docstrings found from M.__test__ are searched, and strings are treated as if they were docstrings. In output, a key K in M.__test__ appears with name
Any classes found are recursively searched similarly, to test docstrings in their contained methods and nested classes.
CPython implementation detail: Prior to version 3.4, extension modules written in C were not fully searched by doctest.
In most cases a copy-and-paste of an interactive console session works fine, but doctest isn’t trying to do an exact emulation of any specific Python shell.
Any expected output must immediately follow the final '>>> ' or '... ' line containing the code, and the expected output (if any) extends to the next '>>> ' or all-whitespace line.
The fine print:
If you continue a line via backslashing in an interactive session, or for any other reason use a backslash, you should use a raw docstring, which will preserve your backslashes exactly as you type them:
Otherwise, the backslash will be interpreted as part of the string. For example, the \n above would be interpreted as a newline character. Alternatively, you can double each backslash in the doctest version (and not use a raw string):
The starting column doesn’t matter:
and as many leading whitespace characters are stripped from the expected output as appeared in the initial '>>> ' line that started the example.
By default, each time doctest finds a docstring to test, it uses a shallow copy of M’s globals, so that running tests doesn’t change the module’s real globals, and so that one test in M can’t leave behind crumbs that accidentally allow another test to work. This means examples can freely use any names defined at top-level in M, and names defined earlier in the docstring being run. Examples cannot see names defined in other docstrings.
You can force use of your own dict as the execution context by passing globs=your_dict to testmod() or testfile() instead.
No problem, provided that the traceback is the only output produced by the example: just paste in the traceback. 1 Since tracebacks contain details that are likely to change rapidly (for example, exact file paths and line numbers), this is one case where doctest works hard to be flexible in what it accepts.
Simple example:
That doctest succeeds if ValueError is raised, with the list.remove(x):
x not in list detail as shown.
The expected output for an exception must start with a traceback header, which may be either of the following two lines, indented the same as the first line of the example:
The traceback header is followed by an optional traceback stack, whose contents are ignored by doctest. The traceback stack is typically omitted, or copied verbatim from an interactive session.
The traceback stack is followed by the most interesting part: the line(s) containing the exception type and detail. This is usually the last line of a traceback, but can extend across multiple lines if the exception has a multi-line detail:
The last three lines (starting with ValueError) are compared against the exception’s type and detail, and the rest are ignored.
Best practice is to omit the traceback stack, unless it adds significant documentation value to the example. So the last example is probably better as:
Note that tracebacks are treated very specially. In particular, in the rewritten example, the use of ... is independent of doctest’s ELLIPSIS option. The ellipsis in that example could be left out, or could just as well be three (or three hundred) commas or digits, or an indented transcript of a Monty Python skit.
Some details you should read once, but won’t need to remember:
For some SyntaxErrors, Python displays the character position of the syntax error, using a ^ marker:
Since the lines showing the position of the error come before the exception type and detail, they are not checked by doctest. For example, the following test would pass, even though it puts the ^ marker in the wrong location:
A number of option flags control various aspects of doctest’s behavior. Symbolic names for the flags are supplied as module constants, which can be bitwise ORed together and passed to various functions. The names can also be used in doctest directives, and may be passed to the doctest command line interface via the -o option.
New in version 3.4: The -o command line option.
The first group of options define test semantics, controlling aspects of how doctest decides whether actual output matches an example’s expected output:
By default, if an expected output block contains just 1, an actual output block containing just 1 or just True is considered to be a match, and similarly for 0 versus False. When DONT_ACCEPT_TRUE_FOR_1 is specified, neither substitution is allowed. The default behavior caters to that Python changed the return type of many functions from integer to boolean; doctests expecting “little integer” output still work in these cases. This option will probably go away, but not for several years.
By default, if an expected output block contains a line containing only the string <BLANKLINE>, then that line will match a blank line in the actual output. Because a genuinely blank line delimits the expected output, this is the only way to communicate that a blank line is expected. When DONT_ACCEPT_BLANKLINE is specified, this substitution is not allowed.
When specified, all sequences of whitespace (blanks and newlines) are treated as equal. Any sequence of whitespace within the expected output will match any sequence of whitespace within the actual output. By default, whitespace must match exactly. NORMALIZE_WHITESPACE is especially useful when a line of expected output is very long, and you want to wrap it across multiple lines in your source.
When specified, an ellipsis marker (...) in the expected output can match any substring in the actual output. This includes substrings that span line boundaries, and empty substrings, so it’s best to keep usage of this simple. Complicated uses can lead to the same kinds of “oops, it matched too much!” surprises that .* is prone to in regular expressions.
When specified, an example that expects an exception passes if an exception of the expected type is raised, even if the exception detail does not match. For example, an example expecting ValueError: 42 will pass if the actual exception raised is ValueError: 3*14, but will fail, e.g., if TypeError is raised.
It will also ignore the module name used in Python 3 doctest reports. Hence both of these variations will work with the flag specified, regardless of whether the test is run under Python 2.7 or Python 3.2 (or later versions):
Note that ELLIPSIS can also be used to ignore the details of the exception message, but such a test may still fail based on whether or not the module details are printed as part of the exception name. Using IGNORE_EXCEPTION_DETAIL and the details from Python 2.3 is also the only clear way to write a doctest that doesn’t care about the exception detail yet continues to pass under Python 2.3 or earlier (those releases do not support doctest directives and ignore them as irrelevant comments). For example:
passes under Python 2.3 and later Python versions with the flag specified, even though the detail changed in Python 2.4 to say “does not” instead of “doesn’t”.
Changed in version 3.2: IGNORE_EXCEPTION_DETAIL now also ignores any information relating to the module containing the exception under test.
When specified, do not run the example at all. This can be useful in contexts where doctest examples serve as both documentation and test cases, and an example should be included for documentation purposes, but should not be checked. E.g., the example’s output might be random; or the example might depend on resources which would be unavailable to the test driver.
The SKIP flag can also be used for temporarily “commenting out” examples.
A bitmask or’ing together all the comparison flags above.
The second group of options controls how test failures are reported:
When specified, failures that involve multi-line expected and actual outputs are displayed using a unified diff.
When specified, failures that involve multi-line expected and actual outputs will be displayed using a context diff.
When specified, differences are computed by difflib.Differ, using the same algorithm as the popular ndiff.py utility. This is the only method that marks differences within lines as well as across lines. For example, if a line of expected output contains digit 1 where actual output contains letter l, a line is inserted with a caret marking the mismatching column positions.
When specified, display the first failing example in each doctest, but suppress output for all remaining examples. This will prevent doctest from reporting correct examples that break because of earlier failures; but it might also hide incorrect examples that fail independently of the first failure. When REPORT_ONLY_FIRST_FAILURE is specified, the remaining examples are still run, and still count towards the total number of failures reported; only the output is suppressed.
When specified, exit after the first failing example and don’t attempt to run the remaining examples. Thus, the number of failures reported will be at most 1. This flag may be useful during debugging, since examples after the first failure won’t even produce debugging output.
The doctest command line accepts the option -f as a shorthand for -o
FAIL_FAST.
New in version 3.4.
A bitmask or’ing together all the reporting flags above.
There is also a way to register new option flag names, though this isn’t useful unless you intend to extend doctest internals via subclassing:
Create a new option flag with a given name, and return the new flag’s integer value. register_optionflag() can be used when subclassing OutputChecker or DocTestRunner to create new options that are supported by your subclasses. register_optionflag() should always be called using the following idiom:
Doctest directives may be used to modify the option flags for an individual example. Doctest directives are special Python comments following an example’s source code:
Whitespace is not allowed between the + or - and the directive option name. The directive option name can be any of the option flag names explained above.
An example’s doctest directives modify doctest’s behavior for that single example. Use + to enable the named behavior, or - to disable it.
For example, this test passes:
Without the directive it would fail, both because the actual output doesn’t have two blanks before the single-digit list elements, and because the actual output is on a single line. This test also passes, and also requires a directive to do so:
Multiple directives can be used on a single physical line, separated by commas:
If multiple directive comments are used for a single example, then they are combined:
As the previous example shows, you can add ... lines to your example containing only directives. This can be useful when an example is too long for a directive to comfortably fit on the same line:
Note that since all options are disabled by default, and directives apply only to the example they appear in, enabling options (via + in a directive) is usually the only meaningful choice. However, option flags can also be passed to functions that run doctests, establishing different defaults. In such cases, disabling an option via - in a directive can be useful.
doctest is serious about requiring exact matches in expected output. If even a single character doesn’t match, the test fails. This will probably surprise you a few times, as you learn exactly what Python does and doesn’t guarantee about output. For example, when printing a set, Python doesn’t guarantee that the element is printed in any particular order, so a test like
is vulnerable! One workaround is to do
instead. Another is to do
Note
Before Python 3.6, when printing a dict, Python did not guarantee that the key-value pairs was printed in any particular order.
There are others, but you get the idea.
Another bad idea is to print things that embed an object address, like
The ELLIPSIS directive gives a nice approach for the last example:
Floating-point numbers are also subject to small output variations across platforms, because Python defers to the platform C library for float formatting, and C libraries vary widely in quality here.
Numbers of the form I/2.**J are safe across all platforms, and I often contrive doctest examples to produce numbers of that form:
Simple fractions are also easier for people to understand, and that makes for better documentation.
The functions testmod() and testfile() provide a simple interface to doctest that should be sufficient for most basic uses. For a less formal introduction to these two functions, see sections Simple Usage: Checking Examples in Docstrings and Simple Usage: Checking Examples in a Text File.
All arguments except filename are optional, and should be specified in keyword form.
Test examples in the file named filename. Return (failure_count,
test_count).
Optional argument module_relative specifies how the filename should be interpreted:
Optional argument name gives the name of the test; by default, or if None, os.path.basename(filename) is used.
Optional argument package is a Python package or the name of a Python package whose directory should be used as the base directory for a module-relative filename. If no package is specified, then the calling module’s directory is used as the base directory for module-relative filenames. It is an error to specify package if module_relative is False.
Optional argument globs gives a dict to be used as the globals when executing examples. A new shallow copy of this dict is created for the doctest, so its examples start with a clean slate. By default, or if None, a new empty dict is used.
Optional argument extraglobs gives a dict merged into the globals used to execute examples. This works like dict.update(): if globs and extraglobs have a common key, the associated value in extraglobs appears in the combined dict. By default, or if None, no extra globals are used. This is an advanced feature that allows parameterization of doctests. For example, a doctest can be written for a base class, using a generic name for the class, then reused to test any number of subclasses by passing an extraglobs dict mapping the generic name to the subclass to be tested.
Optional argument verbose prints lots of stuff if true, and prints only failures if false; by default, or if None, it’s true if and only if '-v' is in sys.argv.
Optional argument report prints a summary at the end when true, else prints nothing at the end. In verbose mode, the summary is detailed, else the summary is very brief (in fact, empty if all tests passed).
Optional argument optionflags (default value 0) takes the bitwise OR of option flags. See section Option Flags.
Optional argument raise_on_error defaults to false. If true, an exception is raised upon the first failure or unexpected exception in an example. This allows failures to be post-mortem debugged. Default behavior is to continue running examples.
Optional argument parser specifies a DocTestParser (or subclass) that should be used to extract tests from the files. It defaults to a normal parser (i.e., DocTestParser()).
Optional argument encoding specifies an encoding that should be used to convert the file to unicode.
All arguments are optional, and all except for m should be specified in keyword form.
Test examples in docstrings in functions and classes reachable from module m (or module __main__ if m is not supplied or is None), starting with m.__doc__.
Also test examples reachable from dict m.__test__, if it exists and is not None. m.__test__ maps names (strings) to functions, classes and strings; function and class docstrings are searched for examples; strings are searched directly, as if they were docstrings.
Only docstrings attached to objects belonging to module m are searched.
Return (failure_count, test_count).
Optional argument name gives the name of the module; by default, or if None, m.__name__ is used.
Optional argument exclude_empty defaults to false. If true, objects for which no doctests are found are excluded from consideration. The default is a backward compatibility hack, so that code still using doctest.master.summarize() in conjunction with testmod() continues to get output for objects with no tests. The exclude_empty argument to the newer DocTestFinder constructor defaults to true.
Optional arguments extraglobs, verbose, report, optionflags, raise_on_error, and globs are the same as for function testfile() above, except that globs defaults to m.__dict__.
Test examples associated with object f; for example, f may be a string, a module, a function, or a class object.
A shallow copy of dictionary argument globs is used for the execution context.
Optional argument name is used in failure messages, and defaults to "NoName".
If optional argument verbose is true, output is generated even if there are no failures. By default, output is generated only in case of an example failure.
Optional argument compileflags gives the set of flags that should be used by the Python compiler when running the examples. By default, or if None, flags are deduced corresponding to the set of future features found in globs.
Optional argument optionflags works as for function testfile() above.
As your collection of doctest’ed modules grows, you’ll want a way to run all their doctests systematically. doctest provides two functions that can be used to create unittest test suites from modules and text files containing doctests. To integrate with unittest test discovery, include a load_tests() function in your test module:
There are two main functions for creating unittest.TestSuite instances from text files and modules with doctests:
Convert doctest tests from one or more text files to a unittest.TestSuite.
The returned unittest.TestSuite is to be run by the unittest framework and runs the interactive examples in each file. If an example in any file fails, then the synthesized unit test fails, and a failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.
Pass one or more paths (as strings) to text files to be examined.
Options may be provided as keyword arguments:
Optional argument module_relative specifies how the filenames in paths should be interpreted:
Optional argument package is a Python package or the name of a Python package whose directory should be used as the base directory for module-relative filenames in paths. If no package is specified, then the calling module’s directory is used as the base directory for module-relative filenames. It is an error to specify package if module_relative is False.
Optional argument setUp specifies a set-up function for the test suite. This is called before running the tests in each file. The setUp function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed.
Optional argument tearDown specifies a tear-down function for the test suite. This is called after running the tests in each file. The tearDown function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed.
Optional argument globs is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, globs is a new empty dictionary.
Optional argument optionflags specifies the default doctest options for the tests, created by or-ing together individual option flags. See section Option Flags. See function set_unittest_reportflags() below for a better way to set reporting options.
Optional argument parser specifies a DocTestParser (or subclass) that should be used to extract tests from the files. It defaults to a normal parser (i.e., DocTestParser()).
Optional argument encoding specifies an encoding that should be used to convert the file to unicode.
The global __file__ is added to the globals provided to doctests loaded from a text file using DocFileSuite().
Convert doctest tests for a module to a unittest.TestSuite.
The returned unittest.TestSuite is to be run by the unittest framework and runs each doctest in the module. If any of the doctests fail, then the synthesized unit test fails, and a failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.
Optional argument module provides the module to be tested. It can be a module object or a (possibly dotted) module name. If not specified, the module calling this function is used.
Optional argument globs is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, globs is a new empty dictionary.
Optional argument extraglobs specifies an extra set of global variables, which is merged into globs. By default, no extra globals are used.
Optional argument test_finder is the DocTestFinder object (or a drop-in replacement) that is used to extract doctests from the module.
Optional arguments setUp, tearDown, and optionflags are the same as for function DocFileSuite() above.
This function uses the same search technique as testmod().
Changed in version 3.5: DocTestSuite() returns an empty unittest.TestSuite if module contains no docstrings instead of raising ValueError.
Under the covers, DocTestSuite() creates a unittest.TestSuite out of doctest.DocTestCase instances, and DocTestCase is a subclass of unittest.TestCase. DocTestCase isn’t documented here (it’s an internal detail), but studying its code can answer questions about the exact details of unittest integration.
Similarly, DocFileSuite() creates a unittest.TestSuite out of doctest.DocFileCase instances, and DocFileCase is a subclass of DocTestCase.
So both ways of creating a unittest.TestSuite run instances of DocTestCase. This is important for a subtle reason: when you run doctest functions yourself, you can control the doctest options in use directly, by passing option flags to doctest functions. However, if you’re writing a unittest framework, unittest ultimately controls when and how tests get run. The framework author typically wants to control doctest reporting options (perhaps, e.g., specified by command line options), but there’s no way to pass options through unittest to doctest test runners.
For this reason, doctest also supports a notion of doctest reporting flags specific to unittest support, via this function:
Set the doctest reporting flags to use.
Argument flags takes the bitwise OR of option flags. See section Option Flags. Only “reporting flags” can be used.
This is a module-global setting, and affects all future doctests run by module unittest: the runTest() method of DocTestCase looks at the option flags specified for the test case when the DocTestCase instance was constructed. If no reporting flags were specified (which is the typical and expected case), doctest’s unittest reporting flags are bitwise ORed into the option flags, and the option flags so augmented are passed to the DocTestRunner instance created to run the doctest. If any reporting flags were specified when the DocTestCase instance was constructed, doctest’s unittest reporting flags are ignored.
The value of the unittest reporting flags in effect before the function was called is returned by the function.
The basic API is a simple wrapper that’s intended to make doctest easy to use. It is fairly flexible, and should meet most users’ needs; however, if you require more fine-grained control over testing, or wish to extend doctest’s capabilities, then you should use the advanced API.
The advanced API revolves around two container classes, which are used to store the interactive examples extracted from doctest cases:
Additional processing classes are defined to find, parse, and run, and check doctest examples:
The relationships among these processing classes are summarized in the following diagram:
A collection of doctest examples that should be run in a single namespace. The constructor arguments are used to initialize the attributes of the same names.
DocTest defines the following attributes. They are initialized by the constructor, and should not be modified directly.
A list of Example objects encoding the individual interactive Python examples that should be run by this test.
The namespace (aka globals) that the examples should be run in. This is a dictionary mapping names to values. Any changes to the namespace made by the examples (such as binding new variables) will be reflected in globs after the test is run.
A string name identifying the DocTest. Typically, this is the name of the object or file that the test was extracted from.
The name of the file that this DocTest was extracted from; or None if the filename is unknown, or if the DocTest was not extracted from a file.
The line number within filename where this DocTest begins, or None if the line number is unavailable. This line number is zero-based with respect to the beginning of the file.
The string that the test was extracted from, or None if the string is unavailable, or if the test was not extracted from a string.
A single interactive example, consisting of a Python statement and its expected output. The constructor arguments are used to initialize the attributes of the same names.
Example defines the following attributes. They are initialized by the constructor, and should not be modified directly.
A string containing the example’s source code. This source code consists of a single Python statement, and always ends with a newline; the constructor adds a newline when necessary.
The expected output from running the example’s source code (either from stdout, or a traceback in case of exception). want ends with a newline unless no output is expected, in which case it’s an empty string. The constructor adds a newline when necessary.
The exception message generated by the example, if the example is expected to generate an exception; or None if it is not expected to generate an exception. This exception message is compared against the return value of traceback.format_exception_only(). exc_msg ends with a newline unless it’s None. The constructor adds a newline if needed.
The line number within the string containing this example where the example begins. This line number is zero-based with respect to the beginning of the containing string.
The example’s indentation in the containing string, i.e., the number of space characters that precede the example’s first prompt.
A dictionary mapping from option flags to True or False, which is used to override default options for this example. Any option flags not contained in this dictionary are left at their default value (as specified by the DocTestRunner’s optionflags). By default, no options are set.
A processing class used to extract the DocTests that are relevant to a given object, from its docstring and the docstrings of its contained objects. DocTests can be extracted from modules, classes, functions, methods, staticmethods, classmethods, and properties.
The optional argument verbose can be used to display the objects searched by the finder. It defaults to False (no output).
The optional argument parser specifies the DocTestParser object (or a drop-in replacement) that is used to extract doctests from docstrings.
If the optional argument recurse is false, then DocTestFinder.find() will only examine the given object, and not any contained objects.
If the optional argument exclude_empty is false, then DocTestFinder.find() will include tests for objects with empty docstrings.
DocTestFinder defines the following method:
Return a list of the DocTests that are defined by obj’s docstring, or by any of its contained objects’ docstrings.
The optional argument name specifies the object’s name; this name will be used to construct names for the returned DocTests. If name is not specified, then obj.__name__ is used.
The optional parameter module is the module that contains the given object. If the module is not specified or is None, then the test finder will attempt to automatically determine the correct module. The object’s module is used:
If module is False, no attempt to find the module will be made. This is obscure, of use mostly in testing doctest itself: if module is False, or is None but cannot be found automatically, then all objects are considered to belong to the (non-existent) module, so all contained objects will (recursively) be searched for doctests.
The globals for each DocTest is formed by combining globs and extraglobs (bindings in extraglobs override bindings in globs). A new shallow copy of the globals dictionary is created for each DocTest. If globs is not specified, then it defaults to the module’s __dict__, if specified, or {} otherwise. If extraglobs is not specified, then it defaults to {}.
A processing class used to extract interactive examples from a string, and use them to create a DocTest object.
DocTestParser defines the following methods:
Extract all doctest examples from the given string, and collect them into a DocTest object.
globs, name, filename, and lineno are attributes for the new DocTest object. See the documentation for DocTest for more information.
Extract all doctest examples from the given string, and return them as a list of Example objects. Line numbers are 0-based. The optional argument name is a name identifying this string, and is only used for error messages.
Divide the given string into examples and intervening text, and return them as a list of alternating Examples and strings. Line numbers for the Examples are 0-based. The optional argument name is a name identifying this string, and is only used for error messages.
A processing class used to execute and verify the interactive examples in a DocTest.
The comparison between expected outputs and actual outputs is done by an OutputChecker. This comparison may be customized with a number of option flags; see section Option Flags for more information. If the option flags are insufficient, then the comparison may also be customized by passing a subclass of OutputChecker to the constructor.
The test runner’s display output can be controlled in two ways. First, an output function can be passed to TestRunner.run(); this function will be called with strings that should be displayed. It defaults to sys.stdout.write. If capturing the output is not sufficient, then the display output can be also customized by subclassing DocTestRunner, and overriding the methods report_start(), report_success(), report_unexpected_exception(), and report_failure().
The optional keyword argument checker specifies the OutputChecker object (or drop-in replacement) that should be used to compare the expected outputs to the actual outputs of doctest examples.
The optional keyword argument verbose controls the DocTestRunner’s verbosity. If verbose is True, then information is printed about each example, as it is run. If verbose is False, then only failures are printed. If verbose is unspecified, or None, then verbose output is used iff the command-line switch -v is used.
The optional keyword argument optionflags can be used to control how the test runner compares expected output to actual output, and how it displays failures. For more information, see section Option Flags.
DocTestParser defines the following methods:
Report that the test runner is about to process the given example. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Report that the given example ran successfully. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Report that the given example failed. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Report that the given example raised an unexpected exception. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. exc_info is a tuple containing information about the unexpected exception (as returned by sys.exc_info()). test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Run the examples in test (a DocTest object), and display the results using the writer function out.
The examples are run in the namespace test.globs. If clear_globs is true (the default), then this namespace will be cleared after the test runs, to help with garbage collection. If you would like to examine the namespace after the test completes, then use clear_globs=False.
compileflags gives the set of flags that should be used by the Python compiler when running the examples. If not specified, then it will default to the set of future-import flags that apply to globs.
The output of each example is checked using the DocTestRunner’s output checker, and the results are formatted by the DocTestRunner.report_*() methods.
Print a summary of all the test cases that have been run by this DocTestRunner, and return a named tuple TestResults(failed, attempted).
The optional verbose argument controls how detailed the summary is. If the verbosity is not specified, then the DocTestRunner’s verbosity is used.
A class used to check the whether the actual output from a doctest example matches the expected output. OutputChecker defines two methods: check_output(), which compares a given pair of outputs, and returns True if they match; and output_difference(), which returns a string describing the differences between two outputs.
OutputChecker defines the following methods:
Return True iff the actual output from an example (got) matches the expected output (want). These strings are always considered to match if they are identical; but depending on what option flags the test runner is using, several non-exact match types are also possible. See section Option Flags for more information about option flags.
Return a string describing the differences between the expected output for a given example (example) and the actual output (got). optionflags is the set of option flags used to compare want and got.
Doctest provides several mechanisms for debugging doctest examples:
You can add a call to pdb.set_trace() in a doctest example, and you’ll drop into the Python debugger when that line is executed. Then you can inspect current values of variables, and so on. For example, suppose a.py contains just this module docstring:
Then an interactive Python session may look like this:
Functions that convert doctests to Python code, and possibly run the synthesized code under the debugger:
Convert text with examples to a script.
Argument s is a string containing doctest examples. The string is converted to a Python script, where doctest examples in s are converted to regular code, and everything else is converted to Python comments. The generated script is returned as a string. For example,
displays:
This function is used internally by other functions (see below), but can also be useful when you want to transform an interactive Python session into a Python script.
Convert the doctest for an object to a script.
Argument module is a module object, or dotted name of a module, containing the object whose doctests are of interest. Argument name is the name (within the module) of the object with the doctests of interest. The result is a string, containing the object’s docstring converted to a Python script, as described for script_from_examples() above. For example, if module a.py contains a top-level function f(), then
prints a script version of function f()’s docstring, with doctests converted to code, and the rest placed in comments.
Debug the doctests for an object.
The module and name arguments are the same as for function testsource() above. The synthesized Python script for the named object’s docstring is written to a temporary file, and then that file is run under the control of the Python debugger, pdb.
A shallow copy of module.__dict__ is used for both local and global execution context.
Optional argument pm controls whether post-mortem debugging is used. If pm has a true value, the script file is run directly, and the debugger gets involved only if the script terminates via raising an unhandled exception. If it does, then post-mortem debugging is invoked, via pdb.post_mortem(), passing the traceback object from the unhandled exception. If pm is not specified, or is false, the script is run under the debugger from the start, via passing an appropriate exec() call to pdb.run().
Debug the doctests in a string.
This is like function debug() above, except that a string containing doctest examples is specified directly, via the src argument.
Optional argument pm has the same meaning as in function debug() above.
Optional argument globs gives a dictionary to use as both local and global execution context. If not specified, or None, an empty dictionary is used. If specified, a shallow copy of the dictionary is used.
The DebugRunner class, and the special exceptions it may raise, are of most interest to testing framework authors, and will only be sketched here. See the source code, and especially DebugRunner’s docstring (which is a doctest!) for more details:
A subclass of DocTestRunner that raises an exception as soon as a failure is encountered. If an unexpected exception occurs, an UnexpectedException exception is raised, containing the test, the example, and the original exception. If the output doesn’t match, then a DocTestFailure exception is raised, containing the test, the example, and the actual output.
For information about the constructor parameters and methods, see the documentation for DocTestRunner in section Advanced API.
There are two exceptions that may be raised by DebugRunner instances:
An exception raised by DocTestRunner to signal that a doctest example’s actual output did not match its expected output. The constructor arguments are used to initialize the attributes of the same names.
DocTestFailure defines the following attributes:
The DocTest object that was being run when the example failed.
The Example that failed.
The example’s actual output.
An exception raised by DocTestRunner to signal that a doctest example raised an unexpected exception. The constructor arguments are used to initialize the attributes of the same names.
UnexpectedException defines the following attributes:
The DocTest object that was being run when the example failed.
The Example that failed.
A tuple containing information about the unexpected exception, as returned by sys.exc_info().
As mentioned in the introduction, doctest has grown to have three primary uses:
These uses have different requirements, and it is important to distinguish them. In particular, filling your docstrings with obscure test cases makes for bad documentation.
When writing a docstring, choose docstring examples with care. There’s an art to this that needs to be learned—it may not be natural at first. Examples should add genuine value to the documentation. A good example can often be worth many words. If done with care, the examples will be invaluable for your users, and will pay back the time it takes to collect them many times over as the years go by and things change. I’m still amazed at how often one of my doctest examples stops working after a “harmless” change.
Doctest also makes an excellent tool for regression testing, especially if you don’t skimp on explanatory text. By interleaving prose and examples, it becomes much easier to keep track of what’s actually being tested, and why. When a test fails, good prose can make it much easier to figure out what the problem is, and how it should be fixed. It’s true that you could write extensive comments in code-based testing, but few programmers do. Many have found that using doctest approaches instead leads to much clearer tests. Perhaps this is simply because doctest makes writing prose a little easier than writing code, while writing comments in code is a little harder. I think it goes deeper than just that: the natural attitude when writing a doctest-based test is that you want to explain the fine points of your software, and illustrate them with examples. This in turn naturally leads to test files that start with the simplest features, and logically progress to complications and edge cases. A coherent narrative is the result, instead of a collection of isolated functions that test isolated bits of functionality seemingly at random. It’s a different attitude, and produces different results, blurring the distinction between testing and explaining.
Regression testing is best confined to dedicated objects or files. There are several options for organizing tests:
When you have placed your tests in a module, the module can itself be the test runner. When a test fails, you can arrange for your test runner to re-run only the failing doctest while you debug the problem. Here is a minimal example of such a test runner:
Examples containing both expected output and an exception are not supported. Trying to guess where one ends and the other begins is too error-prone, and that also makes for a confusing test.


A bitmask or’ing together all the comparison flags above.


Debug the doctests for an object.
The module and name arguments are the same as for function testsource() above. The synthesized Python script for the named object’s docstring is written to a temporary file, and then that file is run under the control of the Python debugger, pdb.
A shallow copy of module.__dict__ is used for both local and global execution context.
Optional argument pm controls whether post-mortem debugging is used. If pm has a true value, the script file is run directly, and the debugger gets involved only if the script terminates via raising an unhandled exception. If it does, then post-mortem debugging is invoked, via pdb.post_mortem(), passing the traceback object from the unhandled exception. If pm is not specified, or is false, the script is run under the debugger from the start, via passing an appropriate exec() call to pdb.run().


A subclass of DocTestRunner that raises an exception as soon as a failure is encountered. If an unexpected exception occurs, an UnexpectedException exception is raised, containing the test, the example, and the original exception. If the output doesn’t match, then a DocTestFailure exception is raised, containing the test, the example, and the actual output.
For information about the constructor parameters and methods, see the documentation for DocTestRunner in section Advanced API.


Debug the doctests in a string.
This is like function debug() above, except that a string containing doctest examples is specified directly, via the src argument.
Optional argument pm has the same meaning as in function debug() above.
Optional argument globs gives a dictionary to use as both local and global execution context. If not specified, or None, an empty dictionary is used. If specified, a shallow copy of the dictionary is used.


Convert doctest tests from one or more text files to a unittest.TestSuite.
The returned unittest.TestSuite is to be run by the unittest framework and runs the interactive examples in each file. If an example in any file fails, then the synthesized unit test fails, and a failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.
Pass one or more paths (as strings) to text files to be examined.
Options may be provided as keyword arguments:
Optional argument module_relative specifies how the filenames in paths should be interpreted:
Optional argument package is a Python package or the name of a Python package whose directory should be used as the base directory for module-relative filenames in paths. If no package is specified, then the calling module’s directory is used as the base directory for module-relative filenames. It is an error to specify package if module_relative is False.
Optional argument setUp specifies a set-up function for the test suite. This is called before running the tests in each file. The setUp function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed.
Optional argument tearDown specifies a tear-down function for the test suite. This is called after running the tests in each file. The tearDown function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed.
Optional argument globs is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, globs is a new empty dictionary.
Optional argument optionflags specifies the default doctest options for the tests, created by or-ing together individual option flags. See section Option Flags. See function set_unittest_reportflags() below for a better way to set reporting options.
Optional argument parser specifies a DocTestParser (or subclass) that should be used to extract tests from the files. It defaults to a normal parser (i.e., DocTestParser()).
Optional argument encoding specifies an encoding that should be used to convert the file to unicode.
The global __file__ is added to the globals provided to doctests loaded from a text file using DocFileSuite().


A collection of doctest examples that should be run in a single namespace. The constructor arguments are used to initialize the attributes of the same names.
DocTest defines the following attributes. They are initialized by the constructor, and should not be modified directly.
A list of Example objects encoding the individual interactive Python examples that should be run by this test.
The namespace (aka globals) that the examples should be run in. This is a dictionary mapping names to values. Any changes to the namespace made by the examples (such as binding new variables) will be reflected in globs after the test is run.
A string name identifying the DocTest. Typically, this is the name of the object or file that the test was extracted from.
The name of the file that this DocTest was extracted from; or None if the filename is unknown, or if the DocTest was not extracted from a file.
The line number within filename where this DocTest begins, or None if the line number is unavailable. This line number is zero-based with respect to the beginning of the file.
The string that the test was extracted from, or None if the string is unavailable, or if the test was not extracted from a string.


The string that the test was extracted from, or None if the string is unavailable, or if the test was not extracted from a string.


A list of Example objects encoding the individual interactive Python examples that should be run by this test.


The name of the file that this DocTest was extracted from; or None if the filename is unknown, or if the DocTest was not extracted from a file.


The namespace (aka globals) that the examples should be run in. This is a dictionary mapping names to values. Any changes to the namespace made by the examples (such as binding new variables) will be reflected in globs after the test is run.


The line number within filename where this DocTest begins, or None if the line number is unavailable. This line number is zero-based with respect to the beginning of the file.


A string name identifying the DocTest. Typically, this is the name of the object or file that the test was extracted from.


An exception raised by DocTestRunner to signal that a doctest example’s actual output did not match its expected output. The constructor arguments are used to initialize the attributes of the same names.


The DocTest object that was being run when the example failed.


A processing class used to extract the DocTests that are relevant to a given object, from its docstring and the docstrings of its contained objects. DocTests can be extracted from modules, classes, functions, methods, staticmethods, classmethods, and properties.
The optional argument verbose can be used to display the objects searched by the finder. It defaults to False (no output).
The optional argument parser specifies the DocTestParser object (or a drop-in replacement) that is used to extract doctests from docstrings.
If the optional argument recurse is false, then DocTestFinder.find() will only examine the given object, and not any contained objects.
If the optional argument exclude_empty is false, then DocTestFinder.find() will include tests for objects with empty docstrings.
DocTestFinder defines the following method:
Return a list of the DocTests that are defined by obj’s docstring, or by any of its contained objects’ docstrings.
The optional argument name specifies the object’s name; this name will be used to construct names for the returned DocTests. If name is not specified, then obj.__name__ is used.
The optional parameter module is the module that contains the given object. If the module is not specified or is None, then the test finder will attempt to automatically determine the correct module. The object’s module is used:
If module is False, no attempt to find the module will be made. This is obscure, of use mostly in testing doctest itself: if module is False, or is None but cannot be found automatically, then all objects are considered to belong to the (non-existent) module, so all contained objects will (recursively) be searched for doctests.
The globals for each DocTest is formed by combining globs and extraglobs (bindings in extraglobs override bindings in globs). A new shallow copy of the globals dictionary is created for each DocTest. If globs is not specified, then it defaults to the module’s __dict__, if specified, or {} otherwise. If extraglobs is not specified, then it defaults to {}.


Return a list of the DocTests that are defined by obj’s docstring, or by any of its contained objects’ docstrings.
The optional argument name specifies the object’s name; this name will be used to construct names for the returned DocTests. If name is not specified, then obj.__name__ is used.
The optional parameter module is the module that contains the given object. If the module is not specified or is None, then the test finder will attempt to automatically determine the correct module. The object’s module is used:
If module is False, no attempt to find the module will be made. This is obscure, of use mostly in testing doctest itself: if module is False, or is None but cannot be found automatically, then all objects are considered to belong to the (non-existent) module, so all contained objects will (recursively) be searched for doctests.
The globals for each DocTest is formed by combining globs and extraglobs (bindings in extraglobs override bindings in globs). A new shallow copy of the globals dictionary is created for each DocTest. If globs is not specified, then it defaults to the module’s __dict__, if specified, or {} otherwise. If extraglobs is not specified, then it defaults to {}.


A processing class used to extract interactive examples from a string, and use them to create a DocTest object.
DocTestParser defines the following methods:
Extract all doctest examples from the given string, and collect them into a DocTest object.
globs, name, filename, and lineno are attributes for the new DocTest object. See the documentation for DocTest for more information.
Extract all doctest examples from the given string, and return them as a list of Example objects. Line numbers are 0-based. The optional argument name is a name identifying this string, and is only used for error messages.
Divide the given string into examples and intervening text, and return them as a list of alternating Examples and strings. Line numbers for the Examples are 0-based. The optional argument name is a name identifying this string, and is only used for error messages.


Extract all doctest examples from the given string, and collect them into a DocTest object.
globs, name, filename, and lineno are attributes for the new DocTest object. See the documentation for DocTest for more information.


Extract all doctest examples from the given string, and return them as a list of Example objects. Line numbers are 0-based. The optional argument name is a name identifying this string, and is only used for error messages.


Divide the given string into examples and intervening text, and return them as a list of alternating Examples and strings. Line numbers for the Examples are 0-based. The optional argument name is a name identifying this string, and is only used for error messages.


A processing class used to execute and verify the interactive examples in a DocTest.
The comparison between expected outputs and actual outputs is done by an OutputChecker. This comparison may be customized with a number of option flags; see section Option Flags for more information. If the option flags are insufficient, then the comparison may also be customized by passing a subclass of OutputChecker to the constructor.
The test runner’s display output can be controlled in two ways. First, an output function can be passed to TestRunner.run(); this function will be called with strings that should be displayed. It defaults to sys.stdout.write. If capturing the output is not sufficient, then the display output can be also customized by subclassing DocTestRunner, and overriding the methods report_start(), report_success(), report_unexpected_exception(), and report_failure().
The optional keyword argument checker specifies the OutputChecker object (or drop-in replacement) that should be used to compare the expected outputs to the actual outputs of doctest examples.
The optional keyword argument verbose controls the DocTestRunner’s verbosity. If verbose is True, then information is printed about each example, as it is run. If verbose is False, then only failures are printed. If verbose is unspecified, or None, then verbose output is used iff the command-line switch -v is used.
The optional keyword argument optionflags can be used to control how the test runner compares expected output to actual output, and how it displays failures. For more information, see section Option Flags.
DocTestParser defines the following methods:
Report that the test runner is about to process the given example. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Report that the given example ran successfully. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Report that the given example failed. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Report that the given example raised an unexpected exception. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. exc_info is a tuple containing information about the unexpected exception (as returned by sys.exc_info()). test is the test containing example. out is the output function that was passed to DocTestRunner.run().
Run the examples in test (a DocTest object), and display the results using the writer function out.
The examples are run in the namespace test.globs. If clear_globs is true (the default), then this namespace will be cleared after the test runs, to help with garbage collection. If you would like to examine the namespace after the test completes, then use clear_globs=False.
compileflags gives the set of flags that should be used by the Python compiler when running the examples. If not specified, then it will default to the set of future-import flags that apply to globs.
The output of each example is checked using the DocTestRunner’s output checker, and the results are formatted by the DocTestRunner.report_*() methods.
Print a summary of all the test cases that have been run by this DocTestRunner, and return a named tuple TestResults(failed, attempted).
The optional verbose argument controls how detailed the summary is. If the verbosity is not specified, then the DocTestRunner’s verbosity is used.


Report that the given example failed. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to DocTestRunner.run().


Report that the test runner is about to process the given example. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. test is the test containing example. out is the output function that was passed to DocTestRunner.run().


Report that the given example ran successfully. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to DocTestRunner.run().


Report that the given example raised an unexpected exception. This method is provided to allow subclasses of DocTestRunner to customize their output; it should not be called directly.
example is the example about to be processed. exc_info is a tuple containing information about the unexpected exception (as returned by sys.exc_info()). test is the test containing example. out is the output function that was passed to DocTestRunner.run().


Run the examples in test (a DocTest object), and display the results using the writer function out.
The examples are run in the namespace test.globs. If clear_globs is true (the default), then this namespace will be cleared after the test runs, to help with garbage collection. If you would like to examine the namespace after the test completes, then use clear_globs=False.
compileflags gives the set of flags that should be used by the Python compiler when running the examples. If not specified, then it will default to the set of future-import flags that apply to globs.
The output of each example is checked using the DocTestRunner’s output checker, and the results are formatted by the DocTestRunner.report_*() methods.


Print a summary of all the test cases that have been run by this DocTestRunner, and return a named tuple TestResults(failed, attempted).
The optional verbose argument controls how detailed the summary is. If the verbosity is not specified, then the DocTestRunner’s verbosity is used.


Convert doctest tests for a module to a unittest.TestSuite.
The returned unittest.TestSuite is to be run by the unittest framework and runs each doctest in the module. If any of the doctests fail, then the synthesized unit test fails, and a failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.
Optional argument module provides the module to be tested. It can be a module object or a (possibly dotted) module name. If not specified, the module calling this function is used.
Optional argument globs is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, globs is a new empty dictionary.
Optional argument extraglobs specifies an extra set of global variables, which is merged into globs. By default, no extra globals are used.
Optional argument test_finder is the DocTestFinder object (or a drop-in replacement) that is used to extract doctests from the module.
Optional arguments setUp, tearDown, and optionflags are the same as for function DocFileSuite() above.
This function uses the same search technique as testmod().
Changed in version 3.5: DocTestSuite() returns an empty unittest.TestSuite if module contains no docstrings instead of raising ValueError.


By default, if an expected output block contains a line containing only the string <BLANKLINE>, then that line will match a blank line in the actual output. Because a genuinely blank line delimits the expected output, this is the only way to communicate that a blank line is expected. When DONT_ACCEPT_BLANKLINE is specified, this substitution is not allowed.


By default, if an expected output block contains just 1, an actual output block containing just 1 or just True is considered to be a match, and similarly for 0 versus False. When DONT_ACCEPT_TRUE_FOR_1 is specified, neither substitution is allowed. The default behavior caters to that Python changed the return type of many functions from integer to boolean; doctests expecting “little integer” output still work in these cases. This option will probably go away, but not for several years.


When specified, an ellipsis marker (...) in the expected output can match any substring in the actual output. This includes substrings that span line boundaries, and empty substrings, so it’s best to keep usage of this simple. Complicated uses can lead to the same kinds of “oops, it matched too much!” surprises that .* is prone to in regular expressions.