# Use the version of Pdb that's in svn trunk because the constructor
# from Pdb needs to take a stdin and stdout argument.
class MPdb(pdb.Pdb):
    def __init__(self, sys.stdin, sys.stdout):
        """ Use sys.stdin and sys.stdout for our input
        and output streams respectively.
        """

    def do_list(self, args):
        """ Override pdb's implementation of the list command """"

    def do_info(self, args):
        """ Provide information about [args] like the gdb info
        command.
        """

    def do_thread(self, thread_no):
        """ Use this command to switch between threads or to apply
        a command to all threads.
        """

    def do_attach(self, location):
        """ fork a new MXXXConsole object and close this one. """

class MSocketConsole(MPdb):
    """ A debugging console that connects to a debugging
    server on a socket. We leave stdin and stdout in tact
    """
    def __init__(self, stdin, stdout)
    
    def do_attach(self, args):
        """ Attach to a debugging server. """

    def write(self, cmd):
        """ Send a command to the debugging server. """

    def read(self):
        """ Receive output from a debugging server. """

    def cmdloop(self):
        """ Loop until we exit sending and receiving commands
        and output from the debugging server.
        """

# SERVER CLASSES

# What I'm think would be cool here is allowing a design where a
# programmer can combine MPdb and a server class to produce a working
# debugging server. Below are some samples

# It is possible for someone to write a wrapper for this class to allow
# XMLRPC communication over SSL. See, 
# http://www.shipyard.com.au/articles/webdevelopment/sslxmlrpc.py
class MXMLRPCServer(MPdb, SimpleXMLRPCServer):
    def __init__(self, stdin, stdout, host, port):
        """ A XMLRPC server. """

    def _register_functions(Self):
        """ Register all MPdb functions with the XMLRPC
        server.
        """

    def do_list(self, args):
        """ This is an example of a method that one may wish to override
        in order to provide the debugging console (which may end up being
        a GUI front-end) with more structured information than that which
        is available in the inherited methods.

        For example, one may wish to return the contents of an entire file
        for the GUIs parsing plus a tag indicating where we currently
        are in the file.
        """

# It is possible to provide a wrapper class for this to enable SSL
# See above for more info (url link above MXMLRPCServer class)
class MTCPSocketServer(MPdb, SocketServer.TCPServer):
    def __init__(self, stdin, stdout, host, port):
        """ A socket server implementation of a debugging
        server.
        """

    def handle_request(self):
        """ Override the method from TCPServer.
        Handle requests coming in on the socket.

        Most of the work of this entire class will be done in
        this method. For instance,

        - redirecting self.stdin and self.stdout to the connected
        sockets
        - providing any authentication methods
        """

class MSerialServer(MPdb):
    """ A class that sets up a debugging server for use with serial
    communication, such as that through a serial port.
    """
    def __init__(self, stdin, stdout, device):
        """ Specify the serial device on the computer as a file from
        /dev to read and write serial information from and to.
        """

    def listen(self):
        """ Listen on the serial device for connecting debugging
        consoles.
        """

    def accept(self):
        """ Accept a debugging console connection through the serial
        device.
        """