eric7.DebugClients.Python.DebugClientBase

Module implementing a debug client base class.

Global Attributes

DebugClientInstance

Classes

DebugClientBase Class implementing the client side of the debugger.

Functions

DebugClientClose Replacement for the standard os.close(fd).
DebugClientInput Replacement for the standard input() builtin.
DebugClientSetRecursionLimit Replacement for the standard sys.setrecursionlimit(limit).


DebugClientBase

Class implementing the client side of the debugger.

It provides access to the Python interpeter from a debugger running in another process.

The protocol between the debugger and the client is based on JSONRPC 2.0 PDUs. Each one is sent on a single line, i.e. commands or responses are separated by a linefeed character.

If the debugger closes the session there is no response from the client. The client may close the session at any time as a result of the script being debugged closing or crashing.

Note: This class is meant to be subclassed by individual DebugClient classes. Do not instantiate it directly.

Derived from

None

Class Attributes

Type2Indicators
clientCapabilities

Class Methods

None

Methods

DebugClientBase Constructor
__clientCapabilities Private method to determine the clients capabilities.
__compileCommand Private method to compile source code.
__compileFileSource Private method to compile source code read from a file.
__completionList Private slot to handle the request for a commandline completion list.
__dumpVariable Private method to return the variables of a frame to the debug server.
__dumpVariables Private method to return the variables of a frame to the debug server.
__formatVariablesList Private method to produce a formated variables list.
__generateFilterObjects Private slot to convert a filter string to a list of filter objects.
__getCompletionList Private method to create a completions list.
__getSysPath Private slot to calculate a path list including the PYTHONPATH environment variable.
__interact Private method to interact with the debugger.
__interceptSignals Private method to intercept common signals.
__resolveHost Private method to resolve a hostname to an IP address.
__setCoding Private method to set the coding used by a python file.
__signalHandler Private method to handle signals.
__unhandled_exception Private method called to report an uncaught exception.
absPath Public method to convert a filename to an absolute name.
checkExceptionHook Public method to check, that 'sys.excepthook' is still our hook.
close Public method implementing a close method as a replacement for os.close().
connectDebugger Public method to establish a session with the debugger.
eventLoop Public method implementing our event loop.
eventPoll Public method to poll for events like 'set break point'.
getCoding Public method to return the current coding.
getRunning Public method to return the main script we are currently running.
handleJsonCommand Public method to handle a command serialized as a JSON string.
input Public method to implement input() using the event loop.
main Public method implementing the main method.
progTerminated Public method to tell the debugger that the program has terminated.
readReady Public method called when there is data ready to be read.
run_call Public method used to start the remote debugger and call a function.
sendCallTrace Public method to send a call trace entry.
sendClearTemporaryBreakpoint Public method to signal the deletion of a temporary breakpoint.
sendClearTemporaryWatch Public method to signal the deletion of a temporary watch expression.
sendDebuggerId Public method to send the debug client id.
sendException Public method to send information for an exception.
sendJsonCommand Public method to send a single command or response to the IDE.
sendPassiveStartup Public method to send the passive start information.
sendResponseLine Public method to send the current call stack.
sendSyntaxError Public method to send information for a syntax error.
sessionClose Public method to close the session with the debugger and optionally terminate.
setDisassembly Public method to store a disassembly of the code object raising an exception.
skipMultiProcessDebugging Public method to check, if the given script is eligible for debugging.
startDebugger Public method used to start the remote debugger.
startProgInDebugger Public method used to start the remote debugger.
writeReady Public method called when we are ready to write data.

Static Methods

None

DebugClientBase (Constructor)

DebugClientBase()

Constructor

DebugClientBase.__clientCapabilities

__clientCapabilities()

Private method to determine the clients capabilities.

Return:
client capabilities
Return Type:
int

DebugClientBase.__compileCommand

__compileCommand(statement, filename="", mode="exec")

Private method to compile source code.

statement (str)
source code string to be compiled
filename (str)
name of the source file
mode (str)
kind of code to be generated (exec or eval)
Return:
compiled code object (None in case of errors)
Return Type:
Code

DebugClientBase.__compileFileSource

__compileFileSource(filename, mode="exec")

Private method to compile source code read from a file.

filename (str)
name of the source file
mode (str)
kind of code to be generated (exec or eval)
Return:
compiled code object (None in case of errors)
Return Type:
Code

DebugClientBase.__completionList

__completionList(text)

Private slot to handle the request for a commandline completion list.

text (str)
the text to be completed

DebugClientBase.__dumpVariable

__dumpVariable(var, frmnr, scope, filterList)

Private method to return the variables of a frame to the debug server.

var (list of str and int)
list encoded name of the requested variable
frmnr (int)
distance of frame reported on. 0 is the current frame
scope (int)
1 to report global variables, 0 for local variables
filterList (list of int)
list of variable types to be filtered

DebugClientBase.__dumpVariables

__dumpVariables(frmnr, scope, filterList)

Private method to return the variables of a frame to the debug server.

frmnr (int)
distance of frame reported on. 0 is the current frame
scope (int)
1 to report global variables, 0 for local variables
filterList (list of str)
list of variable types to be filtered

DebugClientBase.__formatVariablesList

__formatVariablesList(variables, scope, filterList=None, var=None)

Private method to produce a formated variables list.

The dictionary passed in to it is scanned. Variables are only added to the list, if their type is not contained in the filter list and their name doesn't match any of the filter expressions. The formated variables list (a list of tuples of 3 values) is returned.

variables (list of tuple of (str, Any) or (str, str, Any))
variables list to be processed
scope (int)
1 to filter using the globals filter, 0 using the locals filter. Variables are only added to the list, if their access path does not match any of the filter expressions and the 'show/no show' indication.
filterList (list of str (optional))
list of variable types to be filtered. Variables are only added to the list, if their type is not contained in the filter list. (defaults to None)
var (list of str and int (optional))
list encoded name of the requested variable (access path) (defaults to None)
Return:
A tuple consisting of a list of formatted variables. Each variable entry is a tuple of three elements, the variable name, its type and value.
Return Type:
list of tuple of (str, str, str)

DebugClientBase.__generateFilterObjects

__generateFilterObjects(scope, filterString)

Private slot to convert a filter string to a list of filter objects.

scope (int)
1 to generate filter for global variables, 0 for local variables
filterString (str)
string of filter patterns separated by ';'

DebugClientBase.__getCompletionList

__getCompletionList(text, completer, completions)

Private method to create a completions list.

text (str)
text to complete
completer (function)
completer method
completions (set)
set where to add new completions strings

DebugClientBase.__getSysPath

__getSysPath(firstEntry)

Private slot to calculate a path list including the PYTHONPATH environment variable.

firstEntry (str)
entry to be put first in sys.path
Return:
path list for use as sys.path
Return Type:
list of str

DebugClientBase.__interact

__interact()

Private method to interact with the debugger.

DebugClientBase.__interceptSignals

__interceptSignals()

Private method to intercept common signals.

DebugClientBase.__resolveHost

__resolveHost(host)

Private method to resolve a hostname to an IP address.

host (str)
hostname of the debug server
Return:
IP address
Return Type:
str

DebugClientBase.__setCoding

__setCoding(filename)

Private method to set the coding used by a python file.

filename (str)
name of the file to inspect

DebugClientBase.__signalHandler

__signalHandler(signalNumber, stackFrame)

Private method to handle signals.

signalNumber (int)
number of the signal to be handled
stackFrame (frame object)
current stack frame

DebugClientBase.__unhandled_exception

__unhandled_exception(exctype, excval, exctb)

Private method called to report an uncaught exception.

exctype (type)
class of the exception
excval (Exception)
exception instance
exctb (traceback)
traceback for the exception

DebugClientBase.absPath

absPath(fn)

Public method to convert a filename to an absolute name.

sys.path is used as a set of possible prefixes. The name stays relative if a file could not be found.

fn (str)
filename
Return:
the converted filename
Return Type:
str

DebugClientBase.checkExceptionHook

checkExceptionHook()

Public method to check, that 'sys.excepthook' is still our hook.

If the exception hook has been changed by the program being debugger, save that hook and set it to ours again. The program's hook is called in our '__unhandled_exception()' method.

DebugClientBase.close

close(fd)

Public method implementing a close method as a replacement for os.close().

It prevents the debugger connections from being closed.

fd (int)
file descriptor to be closed

DebugClientBase.connectDebugger

connectDebugger(port, remoteAddress=None, redirect=True, name="")

Public method to establish a session with the debugger.

It opens a network connection to the debugger, connects it to stdin, stdout and stderr and saves these file objects in case the application being debugged redirects them itself.

port (int)
the port number to connect to
remoteAddress (str)
the network address of the debug server host
redirect (bool)
flag indicating redirection of stdin, stdout and stderr
name (str)
name to be attached to the debugger ID

DebugClientBase.eventLoop

eventLoop(disablePolling=False)

Public method implementing our event loop.

disablePolling (bool)
flag indicating to enter an event loop with polling disabled

DebugClientBase.eventPoll

eventPoll()

Public method to poll for events like 'set break point'.

DebugClientBase.getCoding

getCoding()

Public method to return the current coding.

Return:
codec name
Return Type:
str

DebugClientBase.getRunning

getRunning()

Public method to return the main script we are currently running.

Return:
flag indicating a running debug session
Return Type:
bool

DebugClientBase.handleJsonCommand

handleJsonCommand(jsonStr)

Public method to handle a command serialized as a JSON string.

jsonStr (str)
string containing the command received from the IDE

DebugClientBase.input

input(prompt, echo=True)

Public method to implement input() using the event loop.

prompt (str)
prompt to be shown
echo (bool)
flag indicating echoing of the input
Return:
the entered string
Return Type:
str

DebugClientBase.main

main()

Public method implementing the main method.

DebugClientBase.progTerminated

progTerminated(status, message="", closeSession=True)

Public method to tell the debugger that the program has terminated.

status (int)
return status
message (str)
status message
closeSession (bool)
flag indicating to close the debugger session

DebugClientBase.readReady

readReady(stream)

Public method called when there is data ready to be read.

stream (file like)
file like object that has data to be read
Return:
flag indicating an error condition
Return Type:
bool

DebugClientBase.run_call

run_call(scriptname, func, *args)

Public method used to start the remote debugger and call a function.

scriptname (str)
name of the script to be debugged
func (function)
function to be called
*args (list)
arguments being passed to func
Return:
result of the function call
Return Type:
Any

DebugClientBase.sendCallTrace

sendCallTrace(event, fromInfo, toInfo)

Public method to send a call trace entry.

event (str)
trace event (call or return)
fromInfo (dict with 'filename', 'linenumber' and 'codename')
dictionary containing the origin info as keys
toInfo (dict with 'filename', 'linenumber' and 'codename')
dictionary containing the target info as keys

DebugClientBase.sendClearTemporaryBreakpoint

sendClearTemporaryBreakpoint(filename, lineno)

Public method to signal the deletion of a temporary breakpoint.

filename (str)
name of the file the bp belongs to
lineno (int)
line number of the bp

DebugClientBase.sendClearTemporaryWatch

sendClearTemporaryWatch(condition)

Public method to signal the deletion of a temporary watch expression.

condition (str)
condition of the watch expression to be cleared

DebugClientBase.sendDebuggerId

sendDebuggerId()

Public method to send the debug client id.

DebugClientBase.sendException

sendException(exceptionType, exceptionMessage, stack, threadName)

Public method to send information for an exception.

exceptionType (str)
type of exception raised
exceptionMessage (str)
message of the exception
stack (list)
stack trace information
threadName (str)
name of the thread sending the event

DebugClientBase.sendJsonCommand

sendJsonCommand(method, params)

Public method to send a single command or response to the IDE.

method (str)
command or response command name to be sent
params (dict)
dictionary of named parameters for the command or response

DebugClientBase.sendPassiveStartup

sendPassiveStartup(filename, reportAllExceptions)

Public method to send the passive start information.

filename (str)
name of the script
reportAllExceptions (bool)
flag to enable reporting of all exceptions

DebugClientBase.sendResponseLine

sendResponseLine(stack, threadName)

Public method to send the current call stack.

stack (list)
call stack
threadName (str)
name of the thread sending the event

DebugClientBase.sendSyntaxError

sendSyntaxError(message, filename, lineno, charno, threadName)

Public method to send information for a syntax error.

message (str)
syntax error message
filename (str)
name of the faulty file
lineno (int)
line number info
charno (int)
character number info
threadName (str)
name of the thread sending the event

DebugClientBase.sessionClose

sessionClose(terminate=True)

Public method to close the session with the debugger and optionally terminate.

terminate (bool)
flag indicating to terminate

DebugClientBase.setDisassembly

setDisassembly(disassembly)

Public method to store a disassembly of the code object raising an exception.

disassembly (dict)
dictionary containing the disassembly information

DebugClientBase.skipMultiProcessDebugging

skipMultiProcessDebugging(scriptName)

Public method to check, if the given script is eligible for debugging.

scriptName (str)
name of the script to check
Return:
flag indicating eligibility
Return Type:
bool

DebugClientBase.startDebugger

startDebugger(filename=None, host=None, port=None, enableTrace=True, reportAllExceptions=False, tracePython=False, redirect=True, passive=True, multiprocessSupport=False, )

Public method used to start the remote debugger.

filename (str)
the program to be debugged
host (str)
hostname of the debug server
port (int)
portnumber of the debug server
enableTrace (bool)
flag to enable the tracing function
reportAllExceptions (bool)
flag indicating to report all exceptions instead of unhandled exceptions only
tracePython (bool)
flag to enable tracing into the Python library
redirect (bool)
flag indicating redirection of stdin, stdout and stderr
passive (bool)
flag indicating a passive debugging session
multiprocessSupport (bool)
flag indicating to enable multiprocess debugging support (unused)

DebugClientBase.startProgInDebugger

startProgInDebugger(progargs, wd="", host=None, port=None, tracePython=False, redirect=True, passive=True, multiprocessSupport=False, reportAllExceptions=False, callTraceOptimization=False, codeStr="", scriptModule="", )

Public method used to start the remote debugger.

progargs (list of str)
commandline for the program to be debugged
wd (str)
working directory for the program execution
host (str)
hostname of the debug server
port (int)
portnumber of the debug server
tracePython (bool)
flag to enable tracing into the Python library
redirect (bool)
flag indicating redirection of stdin, stdout and stderr
passive (bool)
flag indicating a passive debugging session
multiprocessSupport (bool)
flag indicating to enable multiprocess debugging support
reportAllExceptions (bool)
flag indicating to report all exceptions instead of unhandled exceptions only
callTraceOptimization (bool)
flag indicating to speed up function/method call tracing
codeStr (str)
string containing Python code to execute
scriptModule (str)
name of a module to be executed as a script
Return:
exit code of the debugged program
Return Type:
int

DebugClientBase.writeReady

writeReady(stream)

Public method called when we are ready to write data.

stream (file like)
file like object that has data to be written
Up


DebugClientClose

DebugClientClose(fd)

Replacement for the standard os.close(fd).

fd (int)
open file descriptor to be closed
Up


DebugClientInput

DebugClientInput(prompt="", echo=True)

Replacement for the standard input() builtin.

This function works with the split debugger.

prompt (str)
prompt to be shown
echo (bool)
flag indicating echoing of the input
Return:
result of the input() call
Return Type:
str
Up


DebugClientSetRecursionLimit

DebugClientSetRecursionLimit(limit)

Replacement for the standard sys.setrecursionlimit(limit).

limit (int)
recursion limit
Up