Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

673 lines (546 sloc) 20.854 kb
import xml.etree.ElementTree as ET
import socket
import vdebug.log
import base64
import time
""" Response objects for the DBGP module."""
class Response:
"""Contains response data from a command made to the debugger."""
ns = '{urn:debugger_protocol_v1}'
def __init__(self,response,cmd,cmd_args,api):
self.response = response
self.cmd = cmd
self.cmd_args = cmd_args
self.xml = None
self.api = api
if "<error" in self.response:
def __parse_error(self):
"""Parse an error message which has been returned
in the response, then raise it as a DBGPError."""
xml = self.as_xml()
err_el = xml.find('%serror' % self.ns)
code = err_el.get("code")
if code is None:
raise ResponseError(
"Missing error code in response",
msg_el = err_el.find('%smessage' % self.ns)
if msg_el is None:
raise ResponseError(
"Missing error message in response",
raise DBGPError(msg_el.text,code)
def get_cmd(self):
"""Get the command that created this response."""
return self.cmd
def get_cmd_args(self):
"""Get the arguments to the command."""
return self.cmd_args
def as_string(self):
"""Return the full response as a string.
There is a __str__ method, which will render the
whole object as a string and should be used for
return self.response
def as_xml(self):
"""Get the response as element tree XML.
Returns an xml.etree.ElementTree.Element object.
if self.xml == None:
self.xml = ET.fromstring(self.response)
return self.xml
def __str__(self):
return self.as_string()
class ContextNamesResponse(Response):
def names(self):
names = {}
for c in self.as_xml().getchildren():
names[int(c.get('id'))] = c.get('name')
return names
class StatusResponse(Response):
"""Response object returned by the status command."""
def __str__(self):
return self.as_xml().get('status')
class StackGetResponse(Response):
"""Response object used by the stack_get command."""
def get_stack(self):
return self.as_xml().getchildren()
class ContextGetResponse(Response):
"""Response object used by the context_get command.
The property nodes are converted into ContextProperty
objects, which are much easier to use."""
def __init__(self,response,cmd,cmd_args,api):
Response.__init__(self,response,cmd,cmd_args,api) = []
def get_context(self):
for c in self.as_xml().getchildren():
def create_properties(self,property):
for p in property.children:
class EvalResponse(ContextGetResponse):
"""Response object returned by the eval command."""
def __init__(self,response,cmd,cmd_args,api):
except DBGPError, e:
if int(e.args[1]) == 206:
raise EvalError
raise e
def get_context(self):
code = self.get_code()
for c in self.as_xml().getchildren():
def get_code(self):
cmd = self.get_cmd_args()
parts = cmd.split('-- ')
return base64.decodestring(parts[1])
class BreakpointSetResponse(Response):
"""Response object returned by the breakpoint_set command."""
def get_id(self):
return int(self.as_xml().get('id'))
def __str__(self):
return self.as_xml().get('id')
class FeatureGetResponse(Response):
"""Response object specifically for the feature_get command."""
def is_supported(self):
"""Whether the feature is supported or not."""
xml = self.as_xml()
return int(xml.get('supported'))
def __str__(self):
if self.is_supported():
xml = self.as_xml()
return xml.text
return "* Feature not supported *"
class Api:
"""Api for eBGP commands.
Uses a Connection object to read and write with the debugger,
and builds commands and returns the results.
conn = None
transID = 0
def __init__(self,connection):
"""Create a new Api using a Connection object.
The Connection object specifies the debugger connection,
and the Protocol provides a OO api to interacting
with it.
connection -- The Connection object to use
self.language = None
self.protocol = None
self.idekey = None
self.startfile = None
self.conn = connection
if self.conn.isconnected() == 0:
def __parse_init_msg(self,msg):
"""Parse the init message from the debugger"""
xml = ET.fromstring(msg)
self.language = xml.get("language")
if self.language is None:
raise ResponseError(
"Invalid XML response from debugger",
self.language = self.language.lower()
self.idekey = xml.get("idekey")
self.version = xml.get("api_version")
self.startfile = xml.get("fileuri")
def send_cmd(self,cmd,args = '',
res_cls = Response):
"""Send a command to the debugger.
This method automatically adds a unique transaction
ID to the command which is required by the debugger.
Returns a Response object, which contains the
response message and command.
cmd -- the command name, e.g. 'status'
args -- arguments for the command, which is optional
for certain commands (default '')
args = args.strip()
send = cmd.strip()
self.transID += 1
send += ' -i '+ str(self.transID)
if len(args) > 0:
send += ' ' + args
vdebug.log.Log("Command: "+send,\
msg = self.conn.recv_msg()
vdebug.log.Log("Response: "+msg,\
return res_cls(msg,cmd,args,self)
def status(self):
"""Get the debugger status.
Returns a Response object.
return self.send_cmd('status','',StatusResponse)
def feature_get(self,name):
"""Get the value of a feature from the debugger.
See the DBGP documentation for a list of features.
Returns a FeatureGetResponse object.
name -- name of the feature, e.g. encoding
return self.send_cmd(
'-n '+str(name),
def feature_set(self,name,value):
"""Set the value of a debugger feature.
See the DBGP documentation for a list of features.
Returns a Response object.
name -- name of the feature, e.g. encoding
value -- new value for the feature
return self.send_cmd(
'-n ' + str(name) + ' -v ' + str(value))
def run(self):
"""Tell the debugger to start or resume
return self.send_cmd('run','',StatusResponse)
def eval(self,code):
"""Tell the debugger to start or resume
code_enc = base64.encodestring(code)
args = '-- %s' % code_enc
""" The python engine incorrectly requires length.
if self.language == 'python':
args = ("-l %i " % len(code_enc) ) + args"""
return self.send_cmd('eval',args,EvalResponse)
def step_into(self):
"""Tell the debugger to step to the next
If there's a function call, the debugger engine
will break on the first statement in the function.
return self.send_cmd('step_into','',StatusResponse)
def step_over(self):
"""Tell the debugger to step to the next
If there's a function call, the debugger engine
will stop at the next statement after the function call.
return self.send_cmd('step_over','',StatusResponse)
def step_out(self):
"""Tell the debugger to step out of the statement.
The debugger will step out of the current scope.
return self.send_cmd('step_out','',StatusResponse)
def stop(self):
"""Tell the debugger to stop execution.
The script is terminated immediately."""
return self.send_cmd('stop','',StatusResponse)
def stack_get(self):
"""Get the stack information.
return self.send_cmd('stack_get','',StackGetResponse)
def context_get(self,context = 0):
"""Get the context variables.
return self.send_cmd('context_get',\
'-c %i' % int(context),\
def context_names(self):
"""Get the context types.
return self.send_cmd('context_names','',ContextNamesResponse)
def property_get(self,name):
"""Get a property.
return self.send_cmd('property_get','-n %s -d 0' % name,ContextGetResponse)
def detach(self):
"""Tell the debugger to detach itself from this
The script is not terminated, but runs as normal
from this point."""
return self.send_cmd('detach','',StatusResponse)
def breakpoint_set(self,cmd_args):
"""Set a breakpoint.
The breakpoint type is defined by the arguments, see the
Breakpoint class for more detail."""
return self.send_cmd('breakpoint_set',cmd_args,\
def breakpoint_remove(self,id):
"""Remove a breakpoint by ID.
The ID is that returned in the response from breakpoint_set."""
return self.send_cmd('breakpoint_remove','-d %i' % id,Response)
"""Connection module for managing a socket connection
between this client and the debugger."""
class Connection:
"""DBGP connection class, for managing the connection to the debugger.
The host, port and socket timeout are configurable on object construction.
sock = None
address = None
isconned = 0
def __init__(self, host = '', port = 9000, timeout = 30, input_stream = None):
"""Create a new Connection.
The connection is not established until open() is called.
host -- host name where debugger is running (default '')
port -- port number which debugger is listening on (default 9000)
timeout -- time in seconds to wait for a debugger connection before giving up (default 30)
input_stream -- object for checking input stream and user interrupts (default None)
self.port = port = host
self.timeout = timeout
self.input_stream = input_stream
def __del__(self):
"""Make sure the connection is closed."""
def isconnected(self):
"""Whether the connection has been established."""
return self.isconned
def open(self):
"""Listen for a connection from the debugger. Listening for the actual
connection is handled by self.listen()."""
print 'Waiting for a connection (Ctrl-C to cancel, this message will self-destruct in ',self.timeout,' seconds...)'
serv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
serv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
serv.bind((, self.port))
(self.sock, self.address) = self.listen(serv, self.timeout)
except socket.timeout:
raise TimeoutError,"Timeout waiting for connection"
self.isconned = 1
def listen(self, serv, timeout):
"""Non-blocking listener. Provides support for keyboard interrupts from
the user. Although it's non-blocking, the user interface will still
block until the timeout is reached.
serv -- Socket server to listen to.
timeout -- Seconds before timeout.
start = time.time()
while True:
if (time.time() - start) > timeout:
raise socket.timeout
"""Check for user interrupts"""
if self.input_stream is not None:
return serv.accept()
except socket.error:
def close(self):
"""Close the connection."""
if self.sock != None:
self.sock = None
self.isconned = 0
def __recv_length(self):
"""Get the length of the proceeding message."""
length = ''
while 1:
c = self.sock.recv(1)
if c == '':
raise EOFError, 'Socket Closed'
if c == '\0':
return int(length)
if c.isdigit():
length = length + c
def __recv_null(self):
"""Receive a null byte."""
while 1:
c = self.sock.recv(1)
if c == '':
raise EOFError, 'Socket Closed'
if c == '\0':
def __recv_body(self, to_recv):
"""Receive a message of a given length.
to_recv -- length of the message to receive
body = ''
while to_recv > 0:
buf = self.sock.recv(to_recv)
if buf == '':
raise EOFError, 'Socket Closed'
to_recv -= len(buf)
body = body + buf
return body
def recv_msg(self):
"""Receive a message from the debugger.
Returns a string, which is expected to be XML.
length = self.__recv_length()
body = self.__recv_body(length)
return body
def send_msg(self, cmd):
"""Send a message to the debugger.
cmd -- command to send
self.sock.send(cmd + '\0')
class ContextProperty:
ns = '{urn:debugger_protocol_v1}'
def __init__(self,node,parent = None,depth = 0):
self.parent = parent
self.encoding = node.get('encoding')
self.depth = depth
self.size = node.get('size')
self.value = ""
self.is_last_child = False
if self.type == 'scalar':
self.size = len(self.value) - 2
def __determine_value(self,node):
if self.has_children:
self.value = ""
self.value = self._get_enc_node_text(node,'value')
if self.value is None:
if self.encoding == 'base64':
if node.text is None:
self.value = ""
self.value = base64.decodestring(node.text)
elif not self.is_uninitialized() \
and not self.has_children:
self.value = node.text
if self.value is None:
self.value = ""
self.num_crs = self.value.count('\n')
if self.type.lower() in ("string","str","scalar"):
self.value = '`%s`' % self.value.replace('`','\\`')
def __determine_type(self,node):
type = node.get('classname')
if type is None:
type = node.get('type')
if type is None:
type = 'unknown'
self.type = type
def _determine_displayname(self,node):
display_name = node.get('fullname')
if display_name == None:
display_name = self._get_enc_node_text(node,'fullname',"")
if display_name == '::':
display_name = self.type
self.display_name = display_name
def _get_enc_node_text(self,node,name,default =
n = node.find('%s%s' %(self.ns, name))
if n is not None and n.text is not None:
if n.get('encoding') == 'base64':
val = base64.decodestring(n.text)
val = n.text
val = None
if val is None:
return default
return val
def _determine_children(self,node):
children = node.get('numchildren')
if children is None:
children = node.get('children')
if children is None:
children = 0
children = int(children)
self.num_declared_children = children
self.has_children = True if children > 0 else False
self.children = []
def __init_children(self,node):
if self.has_children:
idx = 0
tagname = '%sproperty' % self.ns
children = node.getchildren()
if children is not None:
for c in children:
if c.tag == tagname:
idx += 1
p = self._create_child(c,self,self.depth+1)
if idx == self.num_declared_children:
def _create_child(self,node,parent,depth):
return ContextProperty(node,parent,depth)
def mark_as_last_child(self):
self.is_last_child = True
def is_uninitialized(self):
if self.type == 'uninitialized':
return True
return False
def child_count(self):
return len(self.children)
def type_and_size(self):
size = None
if self.has_children:
size = self.num_declared_children
elif self.size is not None:
size = self.size
if size is None:
return self.type
return "%s [%s]" %(self.type,size)
class EvalProperty(ContextProperty):
def __init__(self,node,code,language,parent=None,depth=0):
self.code = code
self.language = language.lower()
if parent is None:
self.is_parent = True
self.is_parent = False
def _create_child(self,node,parent,depth):
return EvalProperty(node,self.code,self.language,parent,depth)
def _determine_displayname(self,node):
if self.is_parent:
self.display_name = self.code
if self.language == 'php' or \
self.language == 'perl':
if self.parent.type == 'array':
self.display_name = self.parent.display_name + \
"['%s']" % node.get('name')
self.display_name = self.parent.display_name + \
name = node.get('name')
if name is None:
name = "?"
name = self._get_enc_node_text(node,'name','?')
if self.parent.type == 'list':
self.display_name = self.parent.display_name + name
self.display_name = self.parent.display_name + \
"." + name
""" Errors/Exceptions """
class TimeoutError(Exception):
class DBGPError(Exception):
"""Raised when the debugger returns an error message."""
class EvalError(Exception):
"""Raised when some evaluated code is invalid."""
class ResponseError(Exception):
"""An error caused by an unexpected response from the
debugger (e.g. invalid format XML)."""
Jump to Line
Something went wrong with that request. Please try again.