ipdbx 1.0.4

IPython-enabled pdb with extra functionality and customisation

ipdbx is an improved version of ipdb that provides extra functionality and customisation.

Python 2 support has been dropped to make way for new features.

Use

ipdbx exports functions to access the IPython debugger, which features tab completion, syntax highlighting, better tracebacks, better introspection with the same interface as the pdb module.

Example usage:

import ipdbx
ipdbx.set_trace()
ipdbx.set_trace(context=5)  # will show five lines of code
                           # instead of the default three lines
                           # or you can set it via IPDB_CONTEXT_SIZE env variable
                           # or setup.cfg file
ipdbx.set_trace(pretrace='/useful/debug/tools.py')  # can be set via IPDB_PRETRACE
                                                   # env variable. pretrace also
                                                   # accepts the same type of args
                                                   # as ipdbx.run(), ipdbx.runcall()
                                                   # and ipdbx.runeval()
ipdbx.pm()
ipdbx.run('x[0] = 3')
result = ipdbx.runcall(function, arg0, arg1, kwarg='foo')
result = ipdbx.runeval('f(1,2) - 3')

Patching sys.breakpointhook to call ipdbx when calling breakpoint():

import ipdbx
import sys
sys.breakpointhook = ipdbx.set_trace

# You can also call set_trace with default arguments, likewise:

from functools import partial
sys.breakpointhook = partial(ipdbx.set_trace, context=30, pretrace='/my/favourite/things.py')

Arguments for ipdbx.set_trace

The ipdbx.set_trace function accepts the following optional parameters:

• frame, a frame object (defaults to last);

• context: int, which will show as many lines of code as defined;

• cond: bool, which accepts boolean values (such as abc == 17) and will start ipdb’s interface whenever cond equals to True;

• pretrace, which accepts a file path, a python statement string, or a code object, which it will execute immediately before starting the debugger.

Using configuration file

It’s possible to set up context using a .ipdb file on your home folder or setup.cfg on your project folder. You can also set your file location via env var $IPDB_CONFIG. Your environment variable has priority over the home configuration file, which in turn has priority over the setup config file. Currently, only context setting is available.

A valid setup.cfg is as follows

[ipdb]
context=5
pretrace=./file.py

A valid .ipdb is as follows

context=5
pretrace="import inspect"

The post-mortem function, ipdbx.pm(), is equivalent to the magic function %debug.

If you install ipdbx with a tool which supports setuptools entry points, an ipdbx script is made for you. You can use it to debug your python scripts like

$ bin/ipdbx mymodule.py

You can also enclose code with the with statement to launch ipdb if an exception is raised:

from ipdbx import launch_ipdb_on_exception

with launch_ipdb_on_exception():
    ...

Issues with stdout

Some tools, like nose fiddle with stdout.

If you use a tool that fiddles with stdout, you should explicitly ask for stdout fiddling by using ipdbx like this

import ipdbx
ipdbx.sset_trace()
ipdbx.spm()

from ipdbx import slaunch_ipdb_on_exception
with slaunch_ipdb_on_exception():
    ...

Development

ipdbx source code and tracker are at https://github.com/giladbarnea/ipdbx.

Pull requests should take care of updating the changelog HISTORY.txt.

Manual testing

To test your changes, make use of manual_test.py. Create a virtual environment, install IPython and run python manual_test.py and check if your changes are in effect. If possible, create automated tests for better behaviour control.