Here is the complete documentation for the ikpdb module.

IKPdb “public” API consists of 2 functions described in the Integration API paragraph of the IKPdb Integration Guide

IKPdb “private” API consists of:

and of course a ikpdb.main()


class ikpdb.IKPdbLogger[source]

IKPdb implements it’s own logging system to: - avoid problem while debugging programs that reconfigure logging system wide. - allow IKPdb debugging...

classmethod setup(ikpdb_log_arg)[source]

activates DEBUG logging level based on the ikpdb_log_arg parameter string.

ikpdb_log_arg corresponds to the –ikpdb-log command line argument.

ikpdb_log_arg is composed of a serie of letters that set the DEBUG logging level on the components of the debugger.

Here are the letters and the component they activate DEBUG logging level on:

  • n,N: Network
  • b,B: Breakpoints
  • e,E: Expression evaluation
  • x,X: Execution
  • f,F: Frame
  • p,P: Path and python path manipulation
  • g,G: Global debugger

By default logging is disabled for all components. Any ikpdb_log_arg value different from the letters above (eg: ‘9’) activates INFO level logging on all domains.

To log, use:

_logger.x_debug("useful information")
  • _logger is a reference to the IKPdbLogger class
  • x is the Execution domain
  • debug is the logging level
class ikpdb.IKBreakpoint(file_name, line_number, condition=None, enabled=True)[source]

IKBreakpoint implements and manages IKPdb Breakpoints.

Basically a breakpoint is described by:

  • number: a uniq breakpoint number
  • file_name: using a canonical file path
  • line_number: 1 based
  • condition: an optional python expression used to trigger conditional breakpoints.Basically
  • enabled: a flag to enable / disable the breakpoint

The debugger manages Breakpoints using 3 lists maintained by IKBreakpoint:

  • breakpoints_files contains all breakpoints line numbers indexed by file_name
  • breakpoints_by_file_and_line contains all breakpoints indexed by (file, line)
  • breakpoints_by_number is an indexed list of all breakpoints.

This class also maintains a any_active_breakpoint boolean class attribute that is False when there is no active breakpoint. This flag is used to trigger TURBO Mode.

  • file_name (str) – a CANONICAL file name.
  • line_number (int) – breakpoint’s line number (1 based).
  • condition (str) – an optional python expression used to trigger conditional breakpoints.
  • enabled (bool) – a flag to enable / disable the breakpoint.
any_active_breakpoint = False

False when there is no active breakpoint.

classmethod backup_breakpoints_state()[source]

Returns the state of all breakpoints in a list that can be used later to restore all breakpoints state

breakpoints_by_file_and_line = {}

list of breakpoints indexed by (file_name, line)

breakpoints_by_number = []

list of breakpoints indexed by number.

breakpoints_files = {}

list of lines indexed by canonical file names


Clear a breakpoint by removing it from all lists.

classmethod disable_all_breakpoints()[source]

Disable all breakpoints and udate active_breakpoint_flag.

classmethod get_breakpoints_list()[source]
Returns:a list of all breakpoints.
Return type:a list of dict with this keys: breakpoint_number, bp.number, file_name, line_number, condition, enabled.

Warning: IKPDb line numbers are 1 based so line number conversion must be done by clients (eg. inouk.ikpdb for Cloud9)

classmethod lookup_effective_breakpoint(file_name, line_number, frame)[source]

Checks if there is an enabled breakpoint at given file_name and line_number. Check breakpoint condition if any.

Returns:found, enabled and condition verified breakpoint or None
Return type:IKPdbBreakpoint or None
next_breakpoint_number = 0

Used to allocate next breakpoint number.

classmethod restore_breakpoints_state(breakpoints_state_list)[source]

Restore the state of breakpoints given a list provided by backup_breakpoints_state(). If list of breakpoint has changed since backup missing or added breakpoints are ignored.

breakpoints_state_list is a list of tuple. Each tuple is of form: (breakpoint_number, enabled, condition)

classmethod update_active_breakpoint_flag()[source]

Checks all breakpoints to find wether at least one is active and update any_active_breakpoint accordingly.

class ikpdb.IKPdbConnectionHandler(connection)[source]

IKPdbConnectionHandler manages a connection with a remote client once it is established.

IKpdb and remote client exchanges messages having this structure:

length={{integer length of json_message_body below}}{{MAGIC_CODE}}{{json_dump_of_message_body}}

This class contains methods to receive, send and reply to such messages.


Waits for a message from the debugger and returns it as a dict.

reply(obj, result, command_exec_status='ok', info_messages=[], warning_messages=[], error_messages=[])[source]
Build a response from a previouslsy received command message, send it
and return number of sent bytes.
Parameters:result (dict) – Used to send back the result of the command execution to the debugger client.

See send() above for others parameters definition.

send(command, _id=None, result={}, frames=[], error_messages=[], warning_messages=[], info_messages=[], exception=None)[source]

Build a message from parameters and send it to debugger.

  • command (str) – The command sent to the debugger client.
  • _id (int) – Unique id of the sent message. Right now, it’s always None for messages by debugger to client.
  • result (dict) – Used to send exit_code and updated executionStatus to debugger client.
  • frames (list) – contains the complete stack frames when debugger sends the programBreak message.
  • error_messages (list of str) – A list of error messages the debugger client must display to the user.
  • warning_messages (list of str) – A list of warning messages the debugger client must display to the user.
  • info_messages (list of str) – A list of info messages the debugger client must display to the user.
  • exception (dict) – If debugger encounter an exception, this dict contains 2 keys: type and info (the later is the message).
class ikpdb.IKPdb(skip=None, stop_at_first_statement=False, working_directory=None, client_working_directory=None)[source]

Main debugger class.

  • skip – reserved for future use
  • working_directory (str) – allows to force debugger’s Current Working Directory (CWD). working_directory is used for file mapping between IKPdb and clients. working_directory is concatenated with file path exchanged with debugger’s client to get absolute file’s paths.
  • stop_at_first_statement (str) – defines wether debugger must break at first statement. None don’t break, else break.

Take note that, right now, IKPdb is used as singleton.


returns canonical version of a file name. A canonical file name is an absolute, lowercase normalized path to a given file.

change_breakpoint_state(bp_number, enabled, condition=None)[source]

Change breakpoint status or condition expression.

Parameters:bp_number – number of breakpoint to change
Returns:None or an error message (string)

Delete a breakpoint identified by it’s number.

Parameters:breakpoint_number (int) – index of breakpoint to delete
Returns:an error message or None

return 1 to exit command_loop and resume execution


Disable tracing if it is disabled and debugged program is running, else do nothing. Do this on all threads but the debugger thread.

Returns:False if tracing has disabled, False else.

dumps frames chain in a representation suitable for serialization and remote (debugger) client usage.


A debug tool to dump all threads tracing state


Enable tracing if it is disabled and debugged program is running, else do nothing. Do this on all threads but the debugger thread. :return: True if tracing has been enabled, False else.

evaluate(frame_id, expression, global_context=False, disable_break=False)[source]

Evaluates ‘expression’ in the context of the frame identified by ‘frame_id’ or globally. Breakpoints are disabled depending on ‘disable_break’ value. Returns a tuple of value and type both as str. Note that - depending on the CGI_ESCAPE_EVALUATE_OUTPUT attribute - value is escaped.

extract_name_value_type(name, value, limit_size=False)[source]

Extracts value of any object, eventually reduces it’s size and returns name, truncated value and type (for str with size appended)

extract_object_properties(o, limit_size=False)[source]

Extracts all properties from an object (eg. f_locals, f_globals, user dict, instance ...) and returns them as an array of variables.

let_variable(frame_id, var_name, expression_value)[source]

Let a frame’s var with a value by building then eval a let expression with breakoints disabled.


Translate a (possibly incomplete) file or module name received from debugging client into an absolute file name.


Normalizes path sent to client :param path: path to normalize :return: normalized path


returns the number of user browsable properties of an object.


Resets debugger status and set it to run.

set_breakpoint(file_name, line_number, condition=None, enabled=True)[source]

Create a breakpoint, register it in the class’s lists and returns a tuple of (error_message, break_number)


Setup debugger to “resume” execution

setup_step_into(frame, pure=False)[source]

Setup debugger for a “stepInto”


Setup debugger for a “stepOut”


Setup debugger for a “stepOver”


Setup debugger to “suspend” execution


Check if there is a breakpoint at this frame or not.


Called by dispatch function to check wether debugger must stop at this frame. Note that we test ‘step into’ first to give a chance to ‘stepOver’ in case user click on ‘stepInto’ on a ‘no call’ line.


exception ikpdb.IKPdbQuit[source]

A dummy Exception used by debugger to quit debugged program.



A function that returns a type representation suitable for debugger GUI. :param t: anyThing :return: a string representation of t’s type Note: Type representation str format is not finalized...