# eric6.DebugClients.Python3.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.
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 whether or not the Qt event loop is running.

The protocol between the debugger and the client assumes that there will be a single source of debugger commands and a single source of Python statements. Commands and statement are always exactly one line and may be interspersed.

The protocol is as follows. First the client opens a connection to the debugger and then sends a series of one line commands. A command is either >Load<, >Step<, >StepInto<, ... or a Python statement. See DebugProtocol.py for a listing of valid protocol tokens.

A Python statement consists of the statement to execute, followed (in a separate line) by >OK?<. If the statement was incomplete then the response is >Continue<. If there was an exception then the response is >Exception<. Otherwise the response is >OK<. The reason for the >OK?< part is to provide a sentinal (ie. the responding >OK<) after any possible output as a result of executing the command.

The client may send any other lines at any other time which should be interpreted as program output.

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

clientCapabilities

### Class Methods

None

### Methods

DebugClientBase | Constructor
__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.
__dumpThreadList | Private method to send the list of threads.
__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.
__exceptionRaised | Private method called in the case of an exception.
__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.
attachThread | Public method to setup a thread for DebugClient to debug.
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.
handleLine | Public method to handle the receipt of a complete line.
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.
run_call | Public method used to start the remote debugger and call a function.
sessionClose | Public method to close the session with the debugger and optionally terminate.
shouldSkip | Public method to check if a file should be skipped.
startDebugger | Public method used to start the remote debugger.
startProgInDebugger | Public method used to start the remote debugger.
write | Public method to write data to the output stream.

### Static Methods

None

#### DebugClientBase (Constructor)

DebugClientBase()

Constructor

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

__dumpThreadList()

Private method to send the list of threads.

#### DebugClientBase.__dumpVariable

__dumpVariable(var, frmnr, scope, filter)

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

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

#### DebugClientBase.__dumpVariables

__dumpVariables(frmnr, scope, filter)

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

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

#### DebugClientBase.__exceptionRaised

__exceptionRaised()

Private method called in the case of an exception.

It ensures that the debug server is informed of the raised exception.

#### DebugClientBase.__formatQtVariable

__formatQtVariable(value, vtype)

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

value
  variable to be formatted
vtype
  type of the 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(keylist, dict, scope, filter=[], formatSequences=False)

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.

keylist
  keys of the dictionary
dict
  the dictionary to be scanned
scope
  1 to filter using the globals filter, 0 using the locals filter (int). Variables are only added to the list, if their name do not match any of the filter expressions.
filter
  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.
formatSequences
  flag indicating, that sequence or dictionary variables should be formatted. If it is 0 (or false), just the number of items contained in these variables is returned. (boolean)

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.__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.attachThread

attachThread(target=None, args=None, kwargs=None, mainThread=False)

Public method to setup a thread for DebugClient to debug.

If mainThread is non-zero, then we are attaching to the already started mainthread of the app and the rest of the args are ignored.

target
  the start function of the target thread (i.e. the user code)
args
  arguments to pass to target
kwargs
  keyword arguments to pass to target
mainThread
  True, if we are attaching to the already started mainthread of the app

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

handleLine(line)

Public method to handle the receipt of a complete line.

It first looks for a valid protocol token at the start of the line. Thereafter it trys to execute the lines accumulated so far.

line
  the received line

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

Returns:
  the entered string

#### DebugClientBase.main

main()

Public method implementing the main method.

#### DebugClientBase.progTerminated

progTerminated(status)

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

status (int)
  return status

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

sessionClose(exit=True)

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

exit
  flag indicating to terminate (boolean)

#### DebugClientBase.shouldSkip

shouldSkip(fn)

Public method to check if a file should be skipped.

fn
  filename to be checked

Returns:
  non-zero if fn represents a file we are 'skipping', zero otherwise.

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

write(s)

Public method to write data to the output stream.

s
  data to be written (string)

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

## DebugClientSetRecursionLimit

DebugClientSetRecursionLimit(limit)

Replacement for the standard sys.setrecursionlimit(limit).

limit
  recursion limit (integer)

Up