# 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