# 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
__assembleTestCasesList | Private method to assemble a list of test cases included in a test suite.
__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.
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.__assembleTestCasesList

__assembleTestCasesList(suite, start)

Private method to assemble a list of test cases included in a test suite.

suite (unittest.TestSuite)
  test suite to be inspected
start (str)
  name of directory discovery was started at

Return:
  list of tuples containing the test case ID, a short description and the path of the test file name

Return Type:
  list of tuples of (str, str, str)

#### DebugClientBase.__clientCapabilities

__clientCapabilities()

Private method to determine the clients capabilities.

Return:
  client capabilities (integer)

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

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

#### DebugClientBase.__completionList

__completionList(text)

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

text
  the text to be completed (string)

#### DebugClientBase.__dumpVariable

__dumpVariable(var, frmnr, scope, filterList)

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

var (list of str)
  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)

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 name do not match any of the filter expressions.
filterList (list of str)
  list of variable types to be filtered. Variables are only added to the list, if their type is not contained in the filter list.

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
  1 to generate filter for global variables, 0 for local variables (int)
filterString
  string of filter patterns separated by ';'

#### DebugClientBase.__getCompletionList

__getCompletionList(text, completer, completions)

Private method to create a completions list.

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

#### DebugClientBase.__getSysPath

__getSysPath(firstEntry)

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

firstEntry
  entry to be put first in sys.path (string)

Return:
  path list for use as sys.path (list of strings)

#### 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
  hostname of the debug server (string)

Return:
  IP address (string)

#### DebugClientBase.__setCoding

__setCoding(filename)

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

filename
  name of the file to inspect (string)

#### 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
  the type of the exception
excval
  data about the exception
exctb
  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
  filename (string)

Return:
  the converted filename (string)

#### 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
  file descriptor to be closed (integer)

#### 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
  flag indicating to enter an event loop with polling disabled (boolean)

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

#### DebugClientBase.getRunning

getRunning()

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

Return:
  flag indicating a running debug session (boolean)

#### 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
  the prompt to be shown (string)
echo
  Flag indicating echoing of the input (boolean)

Return:
  the entered string

#### 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 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
  name of the script to be debugged (string)
func
  function to be called
*args
  arguments being passed to func

Return:
  result of the function call

#### 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)
  linenumber 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(debuggerId)

Public method to send the debug client id.

debuggerId (str)
  id of this debug client instance (made up of hostname and process 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, exceptions)

Public method to send the passive start information.

filename (str)
  name of the script
exceptions (bool)
  flag to enable exception reporting of the IDE

#### 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
  flag indicating to terminate (boolean)

#### 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, exceptions=True, 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
exceptions (bool)
  flag to enable exception reporting of the IDE
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

#### DebugClientBase.startProgInDebugger

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

Public method used to start the remote debugger.

progargs
  commandline for the program to be debugged (list of strings)
wd
  working directory for the program execution (string)
host
  hostname of the debug server (string)
port
  portnumber of the debug server (int)
exceptions
  flag to enable exception reporting of the IDE (boolean)
tracePython
  flag to enable tracing into the Python library (boolean)
redirect
  flag indicating redirection of stdin, stdout and stderr (boolean)
passive (bool)
  flag indicating a passive debugging session
multiprocessSupport (bool)
  flag indicating to enable multiprocess debugging support
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 object that has data to be written

Up

## DebugClientClose

DebugClientClose(fd)

Replacement for the standard os.close(fd).

fd
  open file descriptor to be closed (integer)

Up

## DebugClientInput

DebugClientInput(prompt="")

Replacement for the standard input() builtin.

This function works with the split debugger.

prompt (str)
  prompt to be shown

Return:
  result of the input() call

Return Type:
  str

Up

## DebugClientSetRecursionLimit

DebugClientSetRecursionLimit(limit)

Replacement for the standard sys.setrecursionlimit(limit).

limit
  recursion limit (integer)

Up