Important

This documentation covers IPython versions 6.0 and higher. Beginning with version 6.0, IPython stopped supporting compatibility with Python versions lower than 3.3 including all versions of Python 2.7.

If you are looking for an IPython version compatible with Python 2.7, please use the IPython 5.x LTS release and refer to its documentation (LTS is the long term support release).

Module: `core.debugger`

Pdb debugger class.

This is an extension to PDB which adds a number of new features. Note that there is also the IPython.terminal.debugger class which provides UI improvements.

We also strongly recommend to use this via the ipdb package, which provides extra configuration options.

Among other things, this subclass of PDB:

supports many IPython magics like pdef/psource
hide frames in tracebacks based on __tracebackhide__
allows to skip frames based on __debuggerskip__

Global Configuration

The IPython debugger will by read the global ~/.pdbrc file. That is to say you can list all commands supported by ipdb in your ~/.pdbrc configuration file, to globally configure pdb.

Example:

# ~/.pdbrc
skip_predicates debuggerskip false
skip_hidden false
context 25

Features

The IPython debugger can hide and skip frames when printing or moving through the stack. This can have a performance impact, so can be configures.

The skipping and hiding frames are configurable via the skip_predicates command.

By default, frames from readonly files will be hidden, frames containing __tracebackhide__ = True will be hidden.

Frames containing __debuggerskip__ will be stepped over, frames whose parent frames value of __debuggerskip__ is True will also be skipped.

>>> def helpers_helper():
...     pass
...
... def helper_1():
...     print("don't step in me")
...     helpers_helpers() # will be stepped over unless breakpoint set.
...
...
... def helper_2():
...     print("in me neither")
...

One can define a decorator that wraps a function between the two helpers:

>>> def pdb_skipped_decorator(function):
...
...
...     def wrapped_fn(*args, **kwargs):
...         __debuggerskip__ = True
...         helper_1()
...         __debuggerskip__ = False
...         result = function(*args, **kwargs)
...         __debuggerskip__ = True
...         helper_2()
...         # setting __debuggerskip__ to False again is not necessary
...         return result
...
...     return wrapped_fn

When decorating a function, ipdb will directly step into bar() by default:

>>> @foo_decorator
... def bar(x, y):
...     return x * y

You can toggle the behavior with

ipdb> skip_predicates debuggerskip false

or configure it in your .pdbrc

License

Modified from the standard pdb.Pdb class to avoid including readline, so that the command line completion of other programs which include this isn’t damaged.

In the future, this class will be expanded with improvements over the standard pdb.

The original code in this file is mainly lifted out of cmd.py in Python 2.2, with minor changes. Licensing should therefore be under the standard Python terms. For details on the PSF (Python Software Foundation) standard license, see:

https://docs.python.org/2/license.html

All the changes since then are under the same license as IPython.

3 Classes

class IPython.core.debugger.OldPdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True): Bases: PdbClosureBackport, Pdb

class IPython.core.debugger.Pdb(completekey=None, stdin=None, stdout=None, context: int | None | str = 5, **kwargs)

Bases: OldPdb

Modified Pdb class, does not load readline.

for a standalone version that uses prompt_toolkit, see IPython.terminal.debugger.TerminalPdb and IPython.terminal.debugger.set_trace()

This debugger can hide and skip frames that are tagged according to some predicates. See the skip_predicates commands.

__init__(completekey=None, stdin=None, stdout=None, context: int | None | str = 5, **kwargs)

Create a new IPython debugger.

Parameters:

completekey (default None) – Passed to pdb.Pdb.
stdin (default None) – Passed to pdb.Pdb.
stdout (default None) – Passed to pdb.Pdb.
context (int) – Number of lines of source code context to show when displaying stacktrace information.
**kwargs – Passed to pdb.Pdb.

Notes

The possibilities are python version dependent, see the python docs for more info.

break_anywhere(frame): _stop_in_decorator_internals is overly restrictive, as we may still want to trace function calls, so we need to also update break_anywhere so that is we don’t stop_here, because of debugger skip, we may still stop at any point inside the function

do_context(context: str): context number_of_lines Set the number of lines of source code to show when displaying stacktrace information.

do_d(arg)

d(own) [count] Move the current frame count (default one) levels down in the stack trace (to a newer frame).

Will skip hidden frames and ignored modules.

do_debug(arg): debug code Enter a recursive debugger that steps through the code argument (which is an arbitrary expression or statement to be executed in the current environment).

do_down(arg)

d(own) [count] Move the current frame count (default one) levels down in the stack trace (to a newer frame).

Will skip hidden frames and ignored modules.

do_exceptions(arg): exceptions [number] List or change current exception in an exception chain. Without arguments, list all the current exception in the exception chain. Exceptions will be numbered, with the current exception indicated with an arrow. If given an integer as argument, switch to the exception at that index.

do_ignore_module(arg)

ignore_module <module_name>

Add a module to the list of modules to skip when navigating frames. When a module is ignored, the debugger will automatically skip over frames from that module.

Supports wildcard patterns using fnmatch syntax:

Usage:: ignore_module threading # Skip threading module frames ignore_module asyncio.* # Skip all asyncio submodules ignore_module *.tests # Skip all test modules ignore_module # List currently ignored modules

do_l(arg): Print lines of code from the current stack frame

do_list(arg): Print lines of code from the current stack frame

do_ll(arg)

Print lines of code from the current stack frame.

Shows more lines than ‘list’ does.

do_longlist(arg)

Print lines of code from the current stack frame.

Shows more lines than ‘list’ does.

do_pdef(arg)

Print the call signature for any callable object.

The debugger interface to %pdef

do_pdoc(arg)

Print the docstring for an object.

The debugger interface to %pdoc.

do_pfile(arg)

Print (or run through pager) the file where an object is defined.

The debugger interface to %pfile.

do_pinfo(arg)

Provide detailed information about an object.

The debugger interface to %pinfo, i.e., obj?.

do_pinfo2(arg)

Provide extra detailed information about an object.

The debugger interface to %pinfo2, i.e., obj??.

do_psource(arg): Print (or run through pager) the source code for an object.

do_q(**kw): q(uit) exit Quit from the debugger. The program being executed is aborted.

do_quit(**kw): q(uit) exit Quit from the debugger. The program being executed is aborted.

do_skip_hidden(arg): Change whether or not we should skip frames with the __tracebackhide__ attribute.

do_skip_predicates(args)

Turn on/off individual predicates as to whether a frame should be hidden/skip.

The global option to skip (or not) hidden frames is set with skip_hidden

To change the value of a predicate

skip_predicates key [true|false]

Call without arguments to see the current values.

To permanently change the value of an option add the corresponding command to your ~/.pdbrc file. If you are programmatically using the Pdb instance you can also change the default_predicates class attribute.

do_u(arg)

u(p) [count] Move the current frame count (default one) levels up in the stack trace (to an older frame).

Will skip hidden frames and ignored modules.

do_unignore_module(arg)

unignore_module <module_name>

Remove a module from the list of modules to skip when navigating frames. This will allow the debugger to step into frames from the specified module.

Usage:: unignore_module threading # Stop ignoring threading module frames unignore_module asyncio.* # Remove asyncio.* pattern unignore_module # List currently ignored modules

do_up(arg)

u(p) [count] Move the current frame count (default one) levels up in the stack trace (to an older frame).

Will skip hidden frames and ignored modules.

do_w(arg: str)

w(here) Print a stack trace, with the most recent frame at the bottom. An arrow indicates the “current frame”, which determines the context of most commands. ‘bt’ is an alias for this command.

Take a number as argument as an (optional) number of context line to print

do_where(arg: str)

w(here) Print a stack trace, with the most recent frame at the bottom. An arrow indicates the “current frame”, which determines the context of most commands. ‘bt’ is an alias for this command.

Take a number as argument as an (optional) number of context line to print

format_stack_entry(frame_lineno: tuple[FrameType, int], lprefix: str = ': ') → str: overwrite from super class so must -> str

get_stack(*args, **kwargs)

Return a list of (frame, lineno) in a stack trace and a size.

List starts with original calling frame, if there is one. Size may be number of frames above or below f.

hidden_frames(stack)

Given an index in the stack return whether it should be skipped.

This is used in up/down and where to skip frames.

precmd(line): Perform useful escapes on the command before it is executed.

print_list_lines(filename: str, first: int, last: int) → None: The printing (as opposed to the parsing part of a ‘list’ command.

print_stack_entry(frame_lineno: tuple[FrameType, int], prompt_prefix: str = '\n-> ') → None: Overwrite print_stack_entry from superclass (PDB)

set_colors(scheme): Shorthand access to the color table scheme selector method.

set_trace(frame=None)

Start debugging from frame.

If frame is not specified, debugging starts from caller’s frame.

stop_here(frame): Return True if frame is below the starting frame in the stack.

class IPython.core.debugger.InterruptiblePdb(completekey=None, stdin=None, stdout=None, context: int | None | str = 5, **kwargs)

Bases: Pdb

Version of debugger where KeyboardInterrupt exits the debugger altogether.

cmdloop(intro=None): Wrap cmdloop() such that KeyboardInterrupt stops the debugger.

4 Functions

IPython.core.debugger.BdbQuit_excepthook(et, ev, tb, excepthook=None)

Exception hook which handles BdbQuit exceptions.

All other exceptions are processed using the excepthook parameter.

IPython.core.debugger.strip_indentation(multiline_string)

IPython.core.debugger.decorate_fn_with_doc(new_fn, old_fn, additional_text=''): Make new_fn have old_fn’s doc string. This is particularly useful for the do_... commands that hook into the help system. Adapted from from a comp.lang.python posting by Duncan Booth.

IPython.core.debugger.set_trace(frame=None, header=None)

Start debugging from frame.

If frame is not specified, debugging starts from caller’s frame.

Module: core.debugger

Global Configuration

Features

License

3 Classes

4 Functions

Module: `core.debugger`