# eric6.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).
DebugClientFork | Replacement for the standard os.fork().
DebugClientInput | Replacement for the standard input builtin.
DebugClientRawInput | Replacement for the standard raw_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

object

### Class Attributes

Indicators
arrayTypes
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.
__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.
__extractIndicators | Private method to extract the indicator string from a variable text.
__formatQtVariable | Private method to produce a formatted output of a simple Qt4/Qt5 type.
__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'.
fork | Public method implementing a fork routine deciding which branch to follow.
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() (Python 2) using the event loop.
main | Public method implementing the main method.
progTerminated | Public method to tell the debugger that the program has terminated.
raw_input | Public method to implement raw_input() / input() using the event loop.
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.
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.
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

Returns:
  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.

Returns:
  client capabilities (integer)

#### DebugClientBase.__compileFileSource

__compileFileSource(filename, mode='exec')

Private method to compile source code read from a file.

filename
  name of the source file (string)
mode
  kind of code to be generated (string, exec or eval)

Returns:
  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 strings)
  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)
  the indices 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 int)
  the indices of variable types to be filtered

#### DebugClientBase.__extractIndicators

__extractIndicators(var)

Private method to extract the indicator string from a variable text.

var (str)
  variable text

Returns:
  tuple containing the variable text without indicators and the indicator string

Return Type:
  tuple of two str

#### DebugClientBase.__formatQtVariable

__formatQtVariable(value, qttype)

Private method to produce a formatted output of a simple Qt4/Qt5 type.

value
  variable to be formatted
qttype
  type of the Qt variable to be formatted (string)

Returns:
  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.

#### DebugClientBase.__formatVariablesList

__formatVariablesList(dict_, 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.

dict_ (dict)
  the dictionary to be scanned
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 int)
  the indices of variable types to be filtered. Variables are only added to the list, if their type is not contained in the filter list.

Returns:
  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 methode
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)

Returns:
  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)

Returns:
  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)

Returns:
  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)

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
  the port number to connect to (int)
remoteAddress
  the network address of the debug server host (string)
redirect
  flag indicating redirection of stdin, stdout and stderr (boolean)

#### 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.fork

fork()

Public method implementing a fork routine deciding which branch to follow.

Returns:
  process ID (integer)

#### DebugClientBase.getCoding

getCoding()

Public method to return the current coding.

Returns:
  codec name (string)

#### DebugClientBase.getRunning

getRunning()

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

Returns:
  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)

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

prompt
  the prompt to be shown (string)

Returns:
  the entered string evaluated as a Python expresion

#### DebugClientBase.main

main()

Public method implementing the main method.

#### DebugClientBase.progTerminated

progTerminated(status, message="")

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

status (int)
  return status
message (str)
  status message

#### DebugClientBase.raw_input

raw_input(prompt, echo)

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

prompt
  the prompt to be shown (string)
echo
  Flag indicating echoing of the input (boolean)

Returns:
  the entered string

#### DebugClientBase.readReady

readReady(stream)

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

stream
  file like object that has data to be written

Returns:
  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

Returns:
  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.sendException

sendException(exceptionType, exceptionMessage, stack)

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

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

Public method to send the current call stack.

stack (list)
  call stack

#### DebugClientBase.sendSyntaxError

sendSyntaxError(message, filename, lineno, charno)

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

#### DebugClientBase.sessionClose

sessionClose(terminate=True)

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

terminate
  flag indicating to terminate (boolean)

#### DebugClientBase.startDebugger

startDebugger(filename=None, host=None, port=None, enableTrace=True, exceptions=True, tracePython=False, redirect=True)

Public method used to start the remote debugger.

filename
  the program to be debugged (string)
host
  hostname of the debug server (string)
port
  portnumber of the debug server (int)
enableTrace
  flag to enable the tracing function (boolean)
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)

#### DebugClientBase.startProgInDebugger

startProgInDebugger(progargs, wd='', host=None, port=None, exceptions=True, tracePython=False, redirect=True)

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)

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

## DebugClientFork

DebugClientFork()

Replacement for the standard os.fork().

Returns:
  result of the fork() call

Up

## DebugClientInput

DebugClientInput(prompt="", echo=True)

Replacement for the standard input builtin.

This function works with the split debugger.

prompt
  prompt to be shown (string)
echo
  flag indicating to echo the output (boolean)

Returns:
  result of the input() call

Up

## DebugClientRawInput

DebugClientRawInput(prompt="", echo=True)

Replacement for the standard raw_input builtin.

This function works with the split debugger.

prompt
  prompt to be shown. (string)
echo
  flag indicating echoing of the input (boolean)

Returns:
  result of the raw_input() call

Up

## DebugClientSetRecursionLimit

DebugClientSetRecursionLimit(limit)

Replacement for the standard sys.setrecursionlimit(limit).

limit
  recursion limit (integer)

Up