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:

• 4 classes:

  • ikpdb.IKPdbLogger (logging system)
  • ikpdb.IKBreakpoint (breakpoints manager)
  • ikpdb.IKPdbConnectionHandler (protocol implementation)
  • ikpdb.IKPdb: The debugger by itself

• 1 exception:

  • ikpdb.IKPdbQuit

• 1 helper:

  • ikpdb.IKPdbRepr() returns a repr suitable for clients

and of course a ikpdb.main()

Classes

class ikpdb.IKPdbLogger

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)

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)

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

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

Clear a breakpoint by removing it from all lists.

classmethod disable_all_breakpoints()

Disable all breakpoints and udate active_breakpoint_flag.

classmethod get_breakpoints_list()

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)

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)

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

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

class ikpdb.IKPdbConnectionHandler(connection)

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

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=[])

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)

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, client_working_directory=None)

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)

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)

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)

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)

return 1 to exit command_loop and resume execution

disable_tracing()

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)

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

dump_tracing_state(context)

A debug tool to dump all threads tracing state

enable_tracing()

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)

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)

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)

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)

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

normalize_path_in(client_file_name)

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

normalize_path_out(path)

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

object_properties_count(o)

returns the number of user browsable properties of an object.

reset()

Resets debugger status and set it to run.

set_breakpoint(file_name, line_number, condition=None, enabled=True)

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

setup_resume()

Setup debugger to “resume” execution

setup_step_into(frame, pure=False)

Setup debugger for a “stepInto”

setup_step_out(frame)

Setup debugger for a “stepOut”

setup_step_over(frame)

Setup debugger for a “stepOver”

setup_suspend()

Setup debugger to “suspend” execution

should_break_here(frame)

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

should_stop_here(frame)

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

A dummy Exception used by debugger to quit debugged program.

Helpers

ikpdb.IKPdbRepr(t)

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...

Main

ikpdb.main()