Welcome to IKPdb’s documentation!

A hackable CPython remote debugger designed for the Web.

Features

IKPdb supports:

  • Debugging of multithreaded programs
  • Conditional breakpoints
  • Variables hot modifications
  • “Turbo” mode

IKPdb has no integrated GUI ; its only interface is a TCP protocol.

IKPdb client GUI reference implementation is Cloud9 Online IDE

IKPdb TCP protocol - based on JSON - is designed for easy integration with latest generation of Javascript editor / IDE (eg. Visual Studio Code, Cloud9, Atom).

Please note that IKPdb supports only CPython 2.7, CPython 3 support is the next step.

Getting started

Getting started with Cloud9

  1. Create a Workspace using the Python template
  2. Install the debugger
$ pip install ikpdb
  1. Create a new file with a few statements and save it as “debug_me.py”.

You can copy / paste this snippet.

#coding: utf-8
print "I want to try Python debugging with IKPdb in Cloud9."
print "I step over onto this line."

4. Set a breakpoint on the first line by clicking in the left margin until a red circle appears.

Ignore the red check button on line 1 ; as it is relevant only for Django development.

_images/index_pic1__py_snippet.png
  1. Click on the Run button at the Top menu right-hand side.
_images/index_pic2__run_button.png

The debugger is now open on the breakpoint you defined at step 3.

_images/index_pic3__debugger_opened.png

Now you can:

Getting started without Cloud9

IKPdb is a debug server. You need a client to use it. You can use Cloud9 client (see above) or develop your own.

For that, follow the instructions in Install IKPdb’s source code to install IKPdb from source code.

Now you can launch IKPdb.

IKPdb has a –help command that shows all available options.

$ python -m ikpdb --help

Start a debugging session with:

$ python -m ikpdb to_debug.py
[IKPdb-g] 05:04:40,690467 - INFO - IKPdb 1.0.0 - Inouk Python Debugger for CPython 2.7
[IKPdb-g] 05:04:40,690937 - INFO - IKPdb listening on 127.0.0.1:15470

This command starts debugging of the to_debug.py python file. IKPdb is then listening for commands on localhost port 15470 (15470 is default port).

Now you can start hacking on your own client. For that you can use this starting material:

Source files mapping

IKPdb exchanges file names with his debugger clients. When it sends a file name, IKPdb always uses full path. But some debuggers client sends relative paths (when setting breakpoints for example). In that case, IKPdb tries to resolve the file’s full path using its “working directory” as a base folder. If it fails, IKPdb sends a “FileMappingError:”.

IKPdb’s working directory can be defined:

  • Implicitly ; working directory is set to the debugged program’s current directory.
  • Explictly ; using the –ikpdb-working-directory command line parameter

To ask IKPdb to display its working directory add a –ikpdb-log=G command line parameter in the runner.

User’s Guide

You’ll find more information about IKPdb usage in the IKPdb User Guide for Cloud9. This guide covers the debugger and the Cloud9 client plugin.

Integration’s Guide

You can get a huge productivity boost by integrating IKPdb with the software of the framework you use. Once integrated, the debugger will automaticaly opens an gives you all information required to debug each time an exception occurs.

_images/index_pic4__demo_exception.png

Read the IKPdb Integration Guide here.

Developer’s Guide

The IKPdb Developer’s Guide describes how to modify the debugger or the IKPdb’s client Cloud9 plugin.

Documentation Writer’s Guide

The documentation is written using the Sphinx Documentation Generator

The Documentation Writer’s Guide describes how to enhance the documentation you are reading.

Source code

IKPdb is composed of these projects hosted on github:

Protocol description

You’ll find a high level overview of IKPdb’s protocol in the IKPdb Protocol

API

Find the complete documentation of IKPDb’s debugger source code in the API document.

Dependencies

IKPdb has no external dependencies (and we wish this to remain like that).

Issues / Suggestions

Please feel free to file an issue on the project’s Github bug tracker if you:

  • have found a bug
  • have some idea about improvements or optimizations
  • have some needs to build a new debugging client !

License

IKPdb is MIT licensed. All detail in the License page.

Indices and tables