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:
- 1 helper:
ikpdb.IKPdbRepr()
returns a repr suitable for clients
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
-
classmethod
-
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
-
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)
-
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.
-
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, client_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
-
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.
-
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]¶ 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.
-
normalize_path_in
(client_file_name)[source]¶ Translate a (possibly incomplete) file or module name received from debugging client into an absolute file name.
-
normalize_path_out
(path)[source]¶ Normalizes path sent to client :param path: path to normalize :return: normalized path