Welcome to IKPdb’s documentation!¶
Contents:
-
class
ikpdb.
IKBreakpoint
(file_name, line_number, condition=None, enabled=True)[source]¶ IKBreakpoint implements IKPdb Breakpoints.
Basically a breakpoint is described by:
- number: a uniq breakpoint number
- file_name: using a canonical file path
- line_number: 0 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 a zero based 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) – 0 based line number of the breakpoint.
- 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.
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
-
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]¶ 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
-
lookup_module
(file_name)[source]¶ Translate a (possibly incomplete) file or module name into an absolute file name.
-
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.
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
-
ikpdb.
IKPdbRepr
(t)[source]¶ A function that returns a type representation suitable for debugger GUI.
Parameters: t – anyThing
-
ikpdb.
post_mortem
(exc_info)[source]¶ Breaks on an exception and send all execution information to the debugger client. If no exc_info is given try get it from sys.exc_info(). If no exception is currently handled, break at caller.
This is useful for integrating with systems that manages Exceptions. Using this function systems can set a developer mode where unhandled exceptions are sente to the developer.
Parameters: exc_info (tuple) – information about the exception to break on.