Cleaned up KernelManager interface and clarified documentation.

IPython/frontend/qt/console/ipython_widget.py

@@ -1,83 +1,82 b''
 # System library imports
 from PyQt4 import QtCore, QtGui
 
 # Local imports
 from frontend_widget import FrontendWidget
 
 
 class IPythonWidget(FrontendWidget):
     """ A FrontendWidget for an IPython kernel.
     """
 
     #---------------------------------------------------------------------------
     # 'FrontendWidget' interface
     #---------------------------------------------------------------------------
     
     def __init__(self, kernel_manager, parent=None):
         super(IPythonWidget, self).__init__(kernel_manager, parent)
 
         self._magic_overrides = {}
 
     def execute_source(self, source, hidden=False, interactive=False):
         """ Reimplemented to override magic commands.
         """
         magic_source = source.strip()
         if magic_source.startswith('%'):
             magic_source = magic_source[1:]
         magic, sep, arguments = magic_source.partition(' ')
         if not magic:
             magic = magic_source
 
         callback = self._magic_overrides.get(magic)
         if callback:
             output = callback(arguments)
             if output:
                 self.appendPlainText(output)
             self._show_prompt('>>> ')
             return True
         else:
             return super(IPythonWidget, self).execute_source(source, hidden,
                                                              interactive)
 
     #---------------------------------------------------------------------------
     # 'IPythonWidget' interface
     #---------------------------------------------------------------------------
 
     def set_magic_override(self, magic, callback):
         """ Overrides an IPython magic command. This magic will be intercepted
             by the frontend rather than passed on to the kernel and 'callback'
             will be called with a single argument: a string of argument(s) for
             the magic. The callback can (optionally) return text to print to the
             console.
         """
         self._magic_overrides[magic] = callback
 
     def remove_magic_override(self, magic):
         """ Removes the override for the specified magic, if there is one.
         """
         try:
             del self._magic_overrides[magic]
         except KeyError:
             pass
 
 
 if __name__ == '__main__':
     import sys
     from IPython.frontend.qt.kernelmanager import QtKernelManager
 
     # Create KernelManager
-    xreq_addr = ('127.0.0.1', 5575)
-    sub_addr = ('127.0.0.1', 5576)
-    rep_addr = ('127.0.0.1', 5577)
-    kernel_manager = QtKernelManager(xreq_addr, sub_addr, rep_addr)
+    kernel_manager = QtKernelManager(xreq_address = ('127.0.0.1', 5575),
+                                     sub_address = ('127.0.0.1', 5576),
+                                     rep_address = ('127.0.0.1', 5577))
     kernel_manager.sub_channel.start()
     kernel_manager.xreq_channel.start()
 
     # Launch application
     app = QtGui.QApplication(sys.argv)
     widget = IPythonWidget(kernel_manager)
     widget.setWindowTitle('Python')
     widget.resize(640, 480)
     widget.show()
     sys.exit(app.exec_())
     

IPython/zmq/kernelmanager.py

@@ -1,335 +1,359 b''
 """Kernel frontend classes.
 
 TODO: Create logger to handle debugging and console messages.
 
 """
 
 # Standard library imports.
 from Queue import Queue, Empty
 from threading import Thread
 import time
 import traceback
 
 # System library imports.
 import zmq
 from zmq import POLLIN, POLLOUT, POLLERR
 from zmq.eventloop import ioloop
 
 # Local imports.
 from IPython.utils.traitlets import HasTraits, Any, Int, Instance, Str, Type
 from session import Session
 
 
 class MissingHandlerError(Exception):
     pass
 
 
 class ZmqSocketChannel(Thread):
+    """ The base class for the channels that use ZMQ sockets.
+    """
 
-    socket = None
-
-    def __init__(self, context, session, addr):
+    def __init__(self, context, session, addr=None):
         self.context = context
         self.session = session
         self.addr = addr
+        self.socket = None
+
         super(ZmqSocketChannel, self).__init__()
         self.daemon = True
 
 
 class SubSocketChannel(ZmqSocketChannel):
 
     handlers = None
     _overriden_call_handler = None
 
-    def __init__(self, context, session, addr):
+    def __init__(self, context, session, addr=None):
         self.handlers = {}
         super(SubSocketChannel, self).__init__(context, session, addr)
 
     def run(self):
         self.socket = self.context.socket(zmq.SUB)
         self.socket.setsockopt(zmq.SUBSCRIBE,'')
         self.socket.setsockopt(zmq.IDENTITY, self.session.session)
         self.socket.connect('tcp://%s:%i' % self.addr)
         self.ioloop = ioloop.IOLoop()
         self.ioloop.add_handler(self.socket, self._handle_events, 
                                 POLLIN|POLLERR)
         self.ioloop.start()
 
     def _handle_events(self, socket, events):
         # Turn on and off POLLOUT depending on if we have made a request
         if events & POLLERR:
             self._handle_err()
         if events & POLLIN:
             self._handle_recv()
 
     def _handle_err(self):
         raise zmq.ZmqError()
 
     def _handle_recv(self):
         msg = self.socket.recv_json()
         self.call_handlers(msg)
 
     def override_call_handler(self, func):
         """Permanently override the call_handler.
     
         The function func will be called as::
 
             func(handler, msg)
 
         And must call::
         
             handler(msg)
 
         in the main thread.
         """
         assert callable(func), "not a callable: %r" % func
         self._overriden_call_handler = func
 
     def call_handlers(self, msg):
         handler = self.handlers.get(msg['msg_type'], None)
         if handler is not None:
             try:
                 self.call_handler(handler, msg)
             except:
                 # XXX: This should be logged at least
                 traceback.print_last()
 
     def call_handler(self, handler, msg):
         if self._overriden_call_handler is not None:
             self._overriden_call_handler(handler, msg)
         elif hasattr(self, '_call_handler'):
            call_handler = getattr(self, '_call_handler')
            call_handler(handler, msg)
         else:
             raise RuntimeError('no handler!')
 
     def add_handler(self, callback, msg_type):
         """Register a callback for msg type."""
         self.handlers[msg_type] = callback
 
     def remove_handler(self, msg_type):
         """Remove the callback for msg type."""
         self.handlers.pop(msg_type, None)
 
     def flush(self):
         """Immediately processes all pending messages on the SUB channel. This
            method is thread safe.
         """
         self._flushed = False
         self.ioloop.add_callback(self._flush)
         while not self._flushed:
             time.sleep(0.01)
         
     def _flush(self):
         """Called in this thread by the IOLoop to indicate that all events have
            been processed.
         """
         self._flushed = True
 
 
 class XReqSocketChannel(ZmqSocketChannel):
 
     handler_queue = None
     command_queue = None
     handlers = None
     _overriden_call_handler = None
 
-    def __init__(self, context, session, addr):
+    def __init__(self, context, session, addr=None):
         self.handlers = {}
         self.handler_queue = Queue()
         self.command_queue = Queue()
         super(XReqSocketChannel, self).__init__(context, session, addr)
 
     def run(self):
         self.socket = self.context.socket(zmq.XREQ)
         self.socket.setsockopt(zmq.IDENTITY, self.session.session)
         self.socket.connect('tcp://%s:%i' % self.addr)
         self.ioloop = ioloop.IOLoop()
         self.ioloop.add_handler(self.socket, self._handle_events, 
                                 POLLIN|POLLOUT|POLLERR)
         self.ioloop.start()
 
     def _handle_events(self, socket, events):
         # Turn on and off POLLOUT depending on if we have made a request
         if events & POLLERR:
             self._handle_err()
         if events & POLLOUT:
             self._handle_send()
         if events & POLLIN:
             self._handle_recv()
 
     def _handle_recv(self):
         msg = self.socket.recv_json()
         self.call_handlers(msg)
 
     def _handle_send(self):
         try:
             msg = self.command_queue.get(False)
         except Empty:
             pass
         else:
             self.socket.send_json(msg)
 
     def _handle_err(self):
         raise zmq.ZmqError()
 
     def _queue_request(self, msg, callback):
         handler = self._find_handler(msg['msg_type'], callback)
         self.handler_queue.put(handler)
         self.command_queue.put(msg)
 
     def execute(self, code, callback=None):
         # Create class for content/msg creation. Related to, but possibly
         # not in Session.
         content = dict(code=code)
         msg = self.session.msg('execute_request', content)
         self._queue_request(msg, callback)
         return msg['header']['msg_id']
 
     def complete(self, text, line, block=None, callback=None):
         content = dict(text=text, line=line)
         msg = self.session.msg('complete_request', content)
         self._queue_request(msg, callback)
         return msg['header']['msg_id']
 
     def object_info(self, oname, callback=None):
         content = dict(oname=oname)
         msg = self.session.msg('object_info_request', content)
         self._queue_request(msg, callback)
         return msg['header']['msg_id']
 
     def _find_handler(self, name, callback):
         if callback is not None:
             return callback
         handler = self.handlers.get(name)
         if handler is None:
             raise MissingHandlerError(
                 'No handler defined for method: %s' % name)
         return handler
 
     def override_call_handler(self, func):
         """Permanently override the call_handler.
     
         The function func will be called as::
 
             func(handler, msg)
 
         And must call::
         
             handler(msg)
 
         in the main thread.
         """
         assert callable(func), "not a callable: %r" % func
         self._overriden_call_handler = func
 
     def call_handlers(self, msg):
         try:
             handler = self.handler_queue.get(False)
         except Empty:
             print "Message received with no handler!!!"
             print msg
         else:
             self.call_handler(handler, msg)
 
     def call_handler(self, handler, msg):
         if self._overriden_call_handler is not None:
             self._overriden_call_handler(handler, msg)
         elif hasattr(self, '_call_handler'):
            call_handler = getattr(self, '_call_handler')
            call_handler(handler, msg)
         else:
             raise RuntimeError('no handler!')
 
 
 class RepSocketChannel(ZmqSocketChannel):
 
     def on_raw_input():
         pass
 
 
 class KernelManager(HasTraits):
+    """ Manages a kernel for a frontend.
 
-    # The addresses to use for the various channels. Should be tuples of form
-    # (ip_address, port).
-    sub_address = Any
-    xreq_address = Any
-    rep_address = Any
-    # FIXME: Add Tuple to Traitlets.
-    #sub_address = Tuple(Str, Int)
-    #xreq_address = Tuple(Str, Int)
-    #rep_address = Tuple(Str, Int)
+    The SUB channel is for the frontend to receive messages published by the
+    kernel.
+        
+    The REQ channel is for the frontend to make requests of the kernel.
+    
+    The REP channel is for the kernel to request stdin (raw_input) from the
+    frontend.
+    """
 
     # The PyZMQ Context to use for communication with the kernel.
     context = Instance(zmq.Context, ())
 
     # The Session to use for communication with the kernel.
     session = Instance(Session, ())
 
+    # The channels objects used for communication with the kernel.
+    # FIXME: Add '_traitname_default' instantiation method to Traitlets.
+    #sub_channel = Instance(SubSocketChannel)
+    #xreq_channel = Instance(XReqSocketChannel)
+    #rep_channel = Instance(RepSocketChannel)
+
     # The classes to use for the various channels.
     sub_channel_class = Type(SubSocketChannel)
     xreq_channel_class = Type(XReqSocketChannel)
     rep_channel_class = Type(RepSocketChannel)
 
+    # The addresses to use for the various channels. Should be tuples of form
+    # (ip_address, port).
+    #sub_address = DelegatesTo('sub_channel')
+    #xreq_address = DelegatesTo('xreq_channel')
+    #rep_address = DelegatesTo('rep_channel')
+    
     # Protected traits.
     _sub_channel = Any
     _xreq_channel = Any
     _rep_channel = Any
 
-    def __init__(self, xreq_address, sub_address, rep_address, **traits):
+    def __init__(self, **traits):
         super(KernelManager, self).__init__()
 
-        self.xreq_address = xreq_address
-        self.sub_address = sub_address
-        self.rep_address = rep_address
-
         # FIXME: This should be the business of HasTraits. The convention is:
         #        HasTraits.__init__(self, **traits_to_be_initialized.)
         for trait in traits:
             setattr(self, trait, traits[trait])
 
     def start_kernel(self):
-        """Start a localhost kernel on ip and port.
-        
-        The SUB channel is for the frontend to receive messages published by
-        the kernel.
-        
-        The REQ channel is for the frontend to make requests of the kernel.
-        
-        The REP channel is for the kernel to request stdin (raw_input) from 
-        the frontend.
+        """Start a localhost kernel. If ports have been specified, use
+        them. Otherwise, choose an open port at random.
         """
 
     def kill_kernel(self):
         """Kill the running kernel"""
 
     def is_alive(self):
         """Is the kernel alive?"""
         return True
 
     def signal_kernel(self, signum):
         """Send signum to the kernel."""
 
     @property
     def sub_channel(self):
         """Get the SUB socket channel object."""
         if self._sub_channel is None:
-            self._sub_channel = self.sub_channel_class(
-                self.context, self.session, self.sub_address)
+            self._sub_channel = self.sub_channel_class(self.context,
+                                                       self.session)
         return self._sub_channel
 
     @property
     def xreq_channel(self):
         """Get the REQ socket channel object to make requests of the kernel."""
         if self._xreq_channel is None:
-            self._xreq_channel = self.xreq_channel_class(
-                self.context, self.session, self.xreq_address)
+            self._xreq_channel = self.xreq_channel_class(self.context, 
+                                                         self.session)
         return self._xreq_channel
 
     @property
     def rep_channel(self):
         """Get the REP socket channel object to handle stdin (raw_input)."""
         if self._rep_channel is None:
-            self._rep_channel = self.rep_channel_class(
-                self.context, self.session, self.rep_address)
+            self._rep_channel = self.rep_channel_class(self.context, 
+                                                       self.session)
         return self._rep_channel
+
+    def get_sub_address(self):
+        return self.sub_channel.addr
+    def set_sub_address(self, addr):
+        self.sub_channel.addr = addr
+    sub_address = property(get_sub_address, set_sub_address,
+                           doc="The address used by SUB socket channel.")
+
+    def get_xreq_address(self):
+        return self.xreq_channel.addr
+    def set_xreq_address(self, addr):
+        self.xreq_channel.addr = addr
+    xreq_address = property(get_xreq_address, set_xreq_address,
+                            doc="The address used by XREQ socket channel.")
+    
+    def get_rep_address(self):
+        return self.rep_channel.addr
+    def set_rep_address(self, addr):
+        self.rep_channel.addr = addr
+    rep_address = property(get_rep_address, set_rep_address,
+                           doc="The address used by REP socket channel.")