API

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

Classes

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")
Where:
  • _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.

Parameters:
  • 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()[source]

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.

receive()[source]

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.

Parameters:
  • 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)[source]

Main debugger class.

Parameters:
  • 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.

canonic(file_name)[source]

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)
clear_breakpoint(breakpoint_number)[source]

Delete a breakpoint identified by it’s number.

Parameters:breakpoint_number (int) – index of breakpoint to delete
Returns:an error message or None
command_loop(run_script_event)[source]

return 1 to exit command_loop and resume execution

disable_tracing()[source]

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.
dump_frames(frame)[source]

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

dump_tracing_state(context)[source]

A debug tool to dump all threads tracing state

enable_tracing()[source]

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]

evaluate ‘expression’ in the context of the frame identified by ‘frame_id’ or globally. Breakpoints are disabled depending on ‘disable_break’ value. Returnsprint a tuple of value and type both as str.

extract_object_properties(o)[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.

lookup_module(file_name)[source]

translate a (possibly incomplete) file or module name into an absolute file name.

object_properties_count(o)[source]

returns the number of user browsable properties of an object.

reset()[source]

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_resume()[source]

Setup debugger to “resume” execution

setup_step_into(frame, pure=False)[source]

Setup debugger for a “stepInto”

setup_step_out(frame)[source]

Setup debugger for a “stepOut”

setup_step_over(frame)[source]

Setup debugger for a “stepOver”

setup_suspend()[source]

Setup debugger to “suspend” execution

should_break_here(frame)[source]

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

should_stop_here(frame)[source]

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.

Exceptions

exception ikpdb.IKPdbQuit[source]

A dummy Exception used by debugger to quit debugged program.

Helpers

ikpdb.IKPdbRepr(t)[source]

A function that returns a type representation suitable for debugger GUI.

Parameters:t – anyThing

Main

ikpdb.main()[source]