Merge branch 'keepkernel' of https://github.com/minrk/ipython into minrk-keepkernel

Closes pull request gh-164.

IPython/frontend/qt/console/frontend_widget.py

@@ -1,554 +1,568 b''
 from __future__ import print_function
 
 # Standard library imports
 from collections import namedtuple
 import sys
+import time
 
 # System library imports
 from pygments.lexers import PythonLexer
 from PyQt4 import QtCore, QtGui
 
 # Local imports
 from IPython.core.inputsplitter import InputSplitter, transform_classic_prompt
 from IPython.core.oinspect import call_tip
 from IPython.frontend.qt.base_frontend_mixin import BaseFrontendMixin
 from IPython.utils.traitlets import Bool
 from bracket_matcher import BracketMatcher
 from call_tip_widget import CallTipWidget
 from completion_lexer import CompletionLexer
 from history_console_widget import HistoryConsoleWidget
 from pygments_highlighter import PygmentsHighlighter
 
 
 class FrontendHighlighter(PygmentsHighlighter):
     """ A PygmentsHighlighter that can be turned on and off and that ignores
         prompts.
     """
 
     def __init__(self, frontend):
         super(FrontendHighlighter, self).__init__(frontend._control.document())
         self._current_offset = 0
         self._frontend = frontend
         self.highlighting_on = False
 
     def highlightBlock(self, qstring):
         """ Highlight a block of text. Reimplemented to highlight selectively.
         """
         if not self.highlighting_on:
             return
 
         # The input to this function is unicode string that may contain
         # paragraph break characters, non-breaking spaces, etc. Here we acquire
         # the string as plain text so we can compare it.
         current_block = self.currentBlock()
         string = self._frontend._get_block_plain_text(current_block)
 
         # Decide whether to check for the regular or continuation prompt.
         if current_block.contains(self._frontend._prompt_pos):
             prompt = self._frontend._prompt
         else:
             prompt = self._frontend._continuation_prompt
 
         # Don't highlight the part of the string that contains the prompt.
         if string.startswith(prompt):
             self._current_offset = len(prompt)
             qstring.remove(0, len(prompt))
         else:
             self._current_offset = 0
 
         PygmentsHighlighter.highlightBlock(self, qstring)
 
     def rehighlightBlock(self, block):
         """ Reimplemented to temporarily enable highlighting if disabled.
         """
         old = self.highlighting_on
         self.highlighting_on = True
         super(FrontendHighlighter, self).rehighlightBlock(block)
         self.highlighting_on = old
 
     def setFormat(self, start, count, format):
         """ Reimplemented to highlight selectively.
         """
         start += self._current_offset
         PygmentsHighlighter.setFormat(self, start, count, format)
 
 
 class FrontendWidget(HistoryConsoleWidget, BaseFrontendMixin):
     """ A Qt frontend for a generic Python kernel.
     """
 
     # An option and corresponding signal for overriding the default kernel
     # interrupt behavior.
     custom_interrupt = Bool(False)
     custom_interrupt_requested = QtCore.pyqtSignal()
 
     # An option and corresponding signals for overriding the default kernel
     # restart behavior.
     custom_restart = Bool(False)
     custom_restart_kernel_died = QtCore.pyqtSignal(float)
     custom_restart_requested = QtCore.pyqtSignal()
    
     # Emitted when an 'execute_reply' has been received from the kernel and
     # processed by the FrontendWidget.
     executed = QtCore.pyqtSignal(object)
 
     # Emitted when an exit request has been received from the kernel.
     exit_requested = QtCore.pyqtSignal()
     
     # Protected class variables.
     _CallTipRequest = namedtuple('_CallTipRequest', ['id', 'pos'])
     _CompletionRequest = namedtuple('_CompletionRequest', ['id', 'pos'])
     _ExecutionRequest = namedtuple('_ExecutionRequest', ['id', 'kind'])
     _input_splitter_class = InputSplitter
 
     #---------------------------------------------------------------------------
     # 'object' interface
     #---------------------------------------------------------------------------
     
     def __init__(self, *args, **kw):
         super(FrontendWidget, self).__init__(*args, **kw)
 
         # FrontendWidget protected variables.
         self._bracket_matcher = BracketMatcher(self._control)
         self._call_tip_widget = CallTipWidget(self._control)
         self._completion_lexer = CompletionLexer(PythonLexer())
         self._copy_raw_action = QtGui.QAction('Copy (Raw Text)', None)
         self._hidden = False
         self._highlighter = FrontendHighlighter(self)
         self._input_splitter = self._input_splitter_class(input_mode='cell')
         self._kernel_manager = None
         self._request_info = {}
 
         # Configure the ConsoleWidget.
         self.tab_width = 4
         self._set_continuation_prompt('... ')
 
         # Configure the CallTipWidget.
         self._call_tip_widget.setFont(self.font)
         self.font_changed.connect(self._call_tip_widget.setFont)
 
         # Configure actions.
         action = self._copy_raw_action
         key = QtCore.Qt.CTRL | QtCore.Qt.SHIFT | QtCore.Qt.Key_C
         action.setEnabled(False)
         action.setShortcut(QtGui.QKeySequence(key))
         action.setShortcutContext(QtCore.Qt.WidgetWithChildrenShortcut)
         action.triggered.connect(self.copy_raw)
         self.copy_available.connect(action.setEnabled)
         self.addAction(action)
 
         # Connect signal handlers.
         document = self._control.document()
         document.contentsChange.connect(self._document_contents_change)
 
     #---------------------------------------------------------------------------
     # 'ConsoleWidget' public interface
     #---------------------------------------------------------------------------
 
     def copy(self):
         """ Copy the currently selected text to the clipboard, removing prompts.
         """
         text = unicode(self._control.textCursor().selection().toPlainText())
         if text:
             lines = map(transform_classic_prompt, text.splitlines())
             text = '\n'.join(lines)
             QtGui.QApplication.clipboard().setText(text)
 
     #---------------------------------------------------------------------------
     # 'ConsoleWidget' abstract interface
     #---------------------------------------------------------------------------
 
     def _is_complete(self, source, interactive):
         """ Returns whether 'source' can be completely processed and a new
             prompt created. When triggered by an Enter/Return key press,
             'interactive' is True; otherwise, it is False.
         """
         complete = self._input_splitter.push(source)
         if interactive:
             complete = not self._input_splitter.push_accepts_more()
         return complete
 
     def _execute(self, source, hidden):
         """ Execute 'source'. If 'hidden', do not show any output.
 
         See parent class :meth:`execute` docstring for full details.
         """
         msg_id = self.kernel_manager.xreq_channel.execute(source, hidden)
         self._request_info['execute'] = self._ExecutionRequest(msg_id, 'user')
         self._hidden = hidden
         
     def _prompt_started_hook(self):
         """ Called immediately after a new prompt is displayed.
         """
         if not self._reading:
             self._highlighter.highlighting_on = True
 
     def _prompt_finished_hook(self):
         """ Called immediately after a prompt is finished, i.e. when some input
             will be processed and a new prompt displayed.
         """
         if not self._reading:
             self._highlighter.highlighting_on = False
 
     def _tab_pressed(self):
         """ Called when the tab key is pressed. Returns whether to continue
             processing the event.
         """
         # Perform tab completion if:
         # 1) The cursor is in the input buffer.
         # 2) There is a non-whitespace character before the cursor.
         text = self._get_input_buffer_cursor_line()
         if text is None:
             return False
         complete = bool(text[:self._get_input_buffer_cursor_column()].strip())
         if complete:
             self._complete()
         return not complete
 
     #---------------------------------------------------------------------------
     # 'ConsoleWidget' protected interface
     #---------------------------------------------------------------------------
 
     def _context_menu_make(self, pos):
         """ Reimplemented to add an action for raw copy.
         """
         menu = super(FrontendWidget, self)._context_menu_make(pos)
         for before_action in menu.actions():
             if before_action.shortcut().matches(QtGui.QKeySequence.Paste) == \
                     QtGui.QKeySequence.ExactMatch:
                 menu.insertAction(before_action, self._copy_raw_action)
                 break
         return menu
 
     def _event_filter_console_keypress(self, event):
         """ Reimplemented for execution interruption and smart backspace.
         """
         key = event.key()
         if self._control_key_down(event.modifiers(), include_command=False):
 
             if key == QtCore.Qt.Key_C and self._executing:
                 self.interrupt_kernel()
                 return True
 
             elif key == QtCore.Qt.Key_Period:
                 message = 'Are you sure you want to restart the kernel?'
                 self.restart_kernel(message, now=False)
                 return True
 
         elif not event.modifiers() & QtCore.Qt.AltModifier:
 
             # Smart backspace: remove four characters in one backspace if:
             # 1) everything left of the cursor is whitespace
             # 2) the four characters immediately left of the cursor are spaces
             if key == QtCore.Qt.Key_Backspace:
                 col = self._get_input_buffer_cursor_column()
                 cursor = self._control.textCursor()
                 if col > 3 and not cursor.hasSelection():
                     text = self._get_input_buffer_cursor_line()[:col]
                     if text.endswith('    ') and not text.strip():
                         cursor.movePosition(QtGui.QTextCursor.Left,
                                             QtGui.QTextCursor.KeepAnchor, 4)
                         cursor.removeSelectedText()
                         return True
 
         return super(FrontendWidget, self)._event_filter_console_keypress(event)
 
     def _insert_continuation_prompt(self, cursor):
         """ Reimplemented for auto-indentation.
         """
         super(FrontendWidget, self)._insert_continuation_prompt(cursor)
         cursor.insertText(' ' * self._input_splitter.indent_spaces)
 
     #---------------------------------------------------------------------------
     # 'BaseFrontendMixin' abstract interface
     #---------------------------------------------------------------------------
 
     def _handle_complete_reply(self, rep):
         """ Handle replies for tab completion.
         """
         cursor = self._get_cursor()
         info = self._request_info.get('complete')
         if info and info.id == rep['parent_header']['msg_id'] and \
                 info.pos == cursor.position():
             text = '.'.join(self._get_context())
             cursor.movePosition(QtGui.QTextCursor.Left, n=len(text))
             self._complete_with_items(cursor, rep['content']['matches'])
 
     def _handle_execute_reply(self, msg):
         """ Handles replies for code execution.
         """
         info = self._request_info.get('execute')
         if info and info.id == msg['parent_header']['msg_id'] and \
                 info.kind == 'user' and not self._hidden:
             # Make sure that all output from the SUB channel has been processed
             # before writing a new prompt.
             self.kernel_manager.sub_channel.flush()
 
             # Reset the ANSI style information to prevent bad text in stdout
             # from messing up our colors. We're not a true terminal so we're
             # allowed to do this.
             if self.ansi_codes:
                 self._ansi_processor.reset_sgr()
 
             content = msg['content']
             status = content['status']
             if status == 'ok':
                 self._process_execute_ok(msg)
             elif status == 'error':
                 self._process_execute_error(msg)
             elif status == 'abort':
                 self._process_execute_abort(msg)
 
             self._show_interpreter_prompt_for_reply(msg)
             self.executed.emit(msg)
 
     def _handle_input_request(self, msg):
         """ Handle requests for raw_input.
         """
         if self._hidden:
             raise RuntimeError('Request for raw input during hidden execution.')
 
         # Make sure that all output from the SUB channel has been processed
         # before entering readline mode.
         self.kernel_manager.sub_channel.flush()
 
         def callback(line):
             self.kernel_manager.rep_channel.input(line)
         self._readline(msg['content']['prompt'], callback=callback)
 
     def _handle_kernel_died(self, since_last_heartbeat):
         """ Handle the kernel's death by asking if the user wants to restart.
         """
         if self.custom_restart:
             self.custom_restart_kernel_died.emit(since_last_heartbeat)
         else:
             message = 'The kernel heartbeat has been inactive for %.2f ' \
                 'seconds. Do you want to restart the kernel? You may ' \
                 'first want to check the network connection.' % \
                 since_last_heartbeat
             self.restart_kernel(message, now=True)
 
     def _handle_object_info_reply(self, rep):
         """ Handle replies for call tips.
         """
         cursor = self._get_cursor()
         info = self._request_info.get('call_tip')
         if info and info.id == rep['parent_header']['msg_id'] and \
                 info.pos == cursor.position():
             # Get the information for a call tip.  For now we format the call
             # line as string, later we can pass False to format_call and
             # syntax-highlight it ourselves for nicer formatting in the
             # calltip.
             call_info, doc = call_tip(rep['content'], format_call=True)
             if call_info or doc:
                 self._call_tip_widget.show_call_info(call_info, doc)
 
     def _handle_pyout(self, msg):
         """ Handle display hook output.
         """
         if not self._hidden and self._is_from_this_session(msg):
             self._append_plain_text(msg['content']['data'] + '\n')
 
     def _handle_stream(self, msg):
         """ Handle stdout, stderr, and stdin.
         """
         if not self._hidden and self._is_from_this_session(msg):
             # Most consoles treat tabs as being 8 space characters. Convert tabs
             # to spaces so that output looks as expected regardless of this
             # widget's tab width.
             text = msg['content']['data'].expandtabs(8)
             
             self._append_plain_text(text)
             self._control.moveCursor(QtGui.QTextCursor.End)
 
+    def _handle_shutdown_reply(self, msg):
+        """ Handle shutdown signal, only if from other console.
+        """
+        if not self._hidden and not self._is_from_this_session(msg):
+            if not msg['content']['restart']:
+                sys.exit(0)
+            else:
+                # we just got notified of a restart!
+                time.sleep(0.25) # wait 1/4 sec to reset
+                                 # lest the request for a new prompt
+                                 # goes to the old kernel
+                self.reset()
+
     def _started_channels(self):
         """ Called when the KernelManager channels have started listening or 
             when the frontend is assigned an already listening KernelManager.
         """
         self.reset()
 
     #---------------------------------------------------------------------------
     # 'FrontendWidget' public interface
     #---------------------------------------------------------------------------
 
     def copy_raw(self):
         """ Copy the currently selected text to the clipboard without attempting
             to remove prompts or otherwise alter the text.
         """
         self._control.copy()
 
     def execute_file(self, path, hidden=False):
         """ Attempts to execute file with 'path'. If 'hidden', no output is
             shown.
         """
         self.execute('execfile("%s")' % path, hidden=hidden)
 
     def interrupt_kernel(self):
         """ Attempts to interrupt the running kernel.
         """
         if self.custom_interrupt:
             self.custom_interrupt_requested.emit()
         elif self.kernel_manager.has_kernel:
             self.kernel_manager.interrupt_kernel()
         else:
             self._append_plain_text('Kernel process is either remote or '
                                     'unspecified. Cannot interrupt.\n')
 
     def reset(self):
         """ Resets the widget to its initial state. Similar to ``clear``, but
             also re-writes the banner and aborts execution if necessary.
         """ 
         if self._executing:
             self._executing = False
             self._request_info['execute'] = None
         self._reading = False
         self._highlighter.highlighting_on = False
 
         self._control.clear()
         self._append_plain_text(self._get_banner())
         self._show_interpreter_prompt()
 
     def restart_kernel(self, message, now=False):
         """ Attempts to restart the running kernel.
         """
         # FIXME: now should be configurable via a checkbox in the dialog.  Right
         # now at least the heartbeat path sets it to True and the manual restart
         # to False.  But those should just be the pre-selected states of a
         # checkbox that the user could override if so desired.  But I don't know
         # enough Qt to go implementing the checkbox now.
 
         if self.custom_restart:
             self.custom_restart_requested.emit()
 
         elif self.kernel_manager.has_kernel:
             # Pause the heart beat channel to prevent further warnings.
             self.kernel_manager.hb_channel.pause()
 
             # Prompt the user to restart the kernel. Un-pause the heartbeat if
             # they decline. (If they accept, the heartbeat will be un-paused
             # automatically when the kernel is restarted.)
             buttons = QtGui.QMessageBox.Yes | QtGui.QMessageBox.No
             result = QtGui.QMessageBox.question(self, 'Restart kernel?',
                                                 message, buttons)
             if result == QtGui.QMessageBox.Yes:
                 try:
                     self.kernel_manager.restart_kernel(now=now)
                 except RuntimeError:
                     self._append_plain_text('Kernel started externally. '
                                             'Cannot restart.\n')
                 else:
                     self.reset()
             else:
                 self.kernel_manager.hb_channel.unpause()
 
         else:
             self._append_plain_text('Kernel process is either remote or '
                                     'unspecified. Cannot restart.\n')
 
     #---------------------------------------------------------------------------
     # 'FrontendWidget' protected interface
     #---------------------------------------------------------------------------
 
     def _call_tip(self):
         """ Shows a call tip, if appropriate, at the current cursor location.
         """
         # Decide if it makes sense to show a call tip
         cursor = self._get_cursor()
         cursor.movePosition(QtGui.QTextCursor.Left)
         if cursor.document().characterAt(cursor.position()).toAscii() != '(':
             return False
         context = self._get_context(cursor)
         if not context:
             return False
 
         # Send the metadata request to the kernel
         name = '.'.join(context)
         msg_id = self.kernel_manager.xreq_channel.object_info(name)
         pos = self._get_cursor().position()
         self._request_info['call_tip'] = self._CallTipRequest(msg_id, pos)
         return True
 
     def _complete(self):
         """ Performs completion at the current cursor location.
         """
         context = self._get_context()
         if context:
             # Send the completion request to the kernel
             msg_id = self.kernel_manager.xreq_channel.complete(
                 '.'.join(context),                       # text
                 self._get_input_buffer_cursor_line(),    # line
                 self._get_input_buffer_cursor_column(),  # cursor_pos
                 self.input_buffer)                       # block 
             pos = self._get_cursor().position()
             info = self._CompletionRequest(msg_id, pos)
             self._request_info['complete'] = info
 
     def _get_banner(self):
         """ Gets a banner to display at the beginning of a session.
         """
         banner = 'Python %s on %s\nType "help", "copyright", "credits" or ' \
             '"license" for more information.'
         return banner % (sys.version, sys.platform)
 
     def _get_context(self, cursor=None):
         """ Gets the context for the specified cursor (or the current cursor
             if none is specified).
         """
         if cursor is None:
             cursor = self._get_cursor()
         cursor.movePosition(QtGui.QTextCursor.StartOfBlock, 
                             QtGui.QTextCursor.KeepAnchor)
         text = unicode(cursor.selection().toPlainText())
         return self._completion_lexer.get_context(text)
 
     def _process_execute_abort(self, msg):
         """ Process a reply for an aborted execution request.
         """
         self._append_plain_text("ERROR: execution aborted\n")
 
     def _process_execute_error(self, msg):
         """ Process a reply for an execution request that resulted in an error.
         """
         content = msg['content']
         traceback = ''.join(content['traceback'])
         self._append_plain_text(traceback)
 
     def _process_execute_ok(self, msg):
         """ Process a reply for a successful execution equest.
         """
         payload = msg['content']['payload']
         for item in payload:
             if not self._process_execute_payload(item):
                 warning = 'Warning: received unknown payload of type %s'
                 print(warning % repr(item['source']))
 
     def _process_execute_payload(self, item):
         """ Process a single payload item from the list of payload items in an
             execution reply. Returns whether the payload was handled.
         """
         # The basic FrontendWidget doesn't handle payloads, as they are a
         # mechanism for going beyond the standard Python interpreter model.
         return False
 
     def _show_interpreter_prompt(self):
         """ Shows a prompt for the interpreter.
         """
         self._show_prompt('>>> ')
 
     def _show_interpreter_prompt_for_reply(self, msg):
         """ Shows a prompt for the interpreter given an 'execute_reply' message.
         """
         self._show_interpreter_prompt()
 
     #------ Signal handlers ----------------------------------------------------
 
     def _document_contents_change(self, position, removed, added):
         """ Called whenever the document's content changes. Display a call tip
             if appropriate.
         """
         # Calculate where the cursor should be *after* the change:
         position += added
 
         document = self._control.document()
         if position == self._get_cursor().position():
             self._call_tip()

IPython/frontend/qt/console/ipythonqt.py

@@ -1,144 +1,158 b''
 """ A minimal application using the Qt console-style IPython frontend.
 """
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Systemm library imports
 from PyQt4 import QtGui
 
 # Local imports
 from IPython.external.argparse import ArgumentParser
 from IPython.frontend.qt.console.frontend_widget import FrontendWidget
 from IPython.frontend.qt.console.ipython_widget import IPythonWidget
 from IPython.frontend.qt.console.rich_ipython_widget import RichIPythonWidget
 from IPython.frontend.qt.kernelmanager import QtKernelManager
 
 #-----------------------------------------------------------------------------
 # Constants
 #-----------------------------------------------------------------------------
 
 LOCALHOST = '127.0.0.1'
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class MainWindow(QtGui.QMainWindow):
 
     #---------------------------------------------------------------------------
     # 'object' interface
     #---------------------------------------------------------------------------
     
-    def __init__(self, frontend):
+    def __init__(self, app, frontend, existing=False):
         """ Create a MainWindow for the specified FrontendWidget.
+        
+        The app is passed as an argument to allow for different
+        closing behavior depending on whether we are the Kernel's parent.
+        
+        If existing is True, then this Window does not own the Kernel.
         """
         super(MainWindow, self).__init__()
+        self._app = app
         self._frontend = frontend
+        self._existing = existing
         self._frontend.exit_requested.connect(self.close)
         self.setCentralWidget(frontend)
     
     #---------------------------------------------------------------------------
     # QWidget interface
     #---------------------------------------------------------------------------
     
     def closeEvent(self, event):
         """ Reimplemented to prompt the user and close the kernel cleanly.
         """
         kernel_manager = self._frontend.kernel_manager
         if kernel_manager and kernel_manager.channels_running:
             title = self.window().windowTitle()
             reply = QtGui.QMessageBox.question(self, title,
-                'Close console?', QtGui.QMessageBox.Yes, QtGui.QMessageBox.No)
-            if reply == QtGui.QMessageBox.Yes:
+                "Close just this console, or shutdown the kernel and close "+
+                "all windows attached to it?", 
+                'Cancel', 'Close Console', 'Close All')
+            if reply == 2: # close All
                 kernel_manager.shutdown_kernel()
                 #kernel_manager.stop_channels()
                 event.accept()
+            elif reply == 1: # close Console
+                if not self._existing:
+                    # I have the kernel: don't quit, just close the window
+                    self._app.setQuitOnLastWindowClosed(False)
+                event.accept()
             else:
                 event.ignore()
 
 #-----------------------------------------------------------------------------
 # Main entry point
 #-----------------------------------------------------------------------------
 
 def main():
     """ Entry point for application.
     """
     # Parse command line arguments.
     parser = ArgumentParser()
     kgroup = parser.add_argument_group('kernel options')
     kgroup.add_argument('-e', '--existing', action='store_true',
                         help='connect to an existing kernel')
     kgroup.add_argument('--ip', type=str, default=LOCALHOST,
                         help='set the kernel\'s IP address [default localhost]')
     kgroup.add_argument('--xreq', type=int, metavar='PORT', default=0,
                         help='set the XREQ channel port [default random]')
     kgroup.add_argument('--sub', type=int, metavar='PORT', default=0,
                         help='set the SUB channel port [default random]')
     kgroup.add_argument('--rep', type=int, metavar='PORT', default=0,
                         help='set the REP channel port [default random]')
     kgroup.add_argument('--hb', type=int, metavar='PORT', default=0,
                         help='set the heartbeat port [default: random]')
 
     egroup = kgroup.add_mutually_exclusive_group()
     egroup.add_argument('--pure', action='store_true', help = \
                         'use a pure Python kernel instead of an IPython kernel')
     egroup.add_argument('--pylab', type=str, metavar='GUI', nargs='?', 
                        const='auto', help = \
         "Pre-load matplotlib and numpy for interactive use. If GUI is not \
          given, the GUI backend is matplotlib's, otherwise use one of: \
          ['tk', 'gtk', 'qt', 'wx', 'inline'].")
 
     wgroup = parser.add_argument_group('widget options')
     wgroup.add_argument('--paging', type=str, default='inside',
                         choices = ['inside', 'hsplit', 'vsplit', 'none'],
                         help='set the paging style [default inside]')
     wgroup.add_argument('--rich', action='store_true',
                         help='enable rich text support')
     wgroup.add_argument('--gui-completion', action='store_true',
                         help='use a GUI widget for tab completion')
 
     args = parser.parse_args()
 
     # Don't let Qt or ZMQ swallow KeyboardInterupts.
     import signal
     signal.signal(signal.SIGINT, signal.SIG_DFL)
 
     # Create a KernelManager and start a kernel.
     kernel_manager = QtKernelManager(xreq_address=(args.ip, args.xreq),
                                      sub_address=(args.ip, args.sub),
                                      rep_address=(args.ip, args.rep),
                                      hb_address=(args.ip, args.hb))
     if args.ip == LOCALHOST and not args.existing:
         if args.pure:
             kernel_manager.start_kernel(ipython=False)
         elif args.pylab:
             kernel_manager.start_kernel(pylab=args.pylab)
         else:
             kernel_manager.start_kernel()
     kernel_manager.start_channels()
 
     # Create the widget.
     app = QtGui.QApplication([])
     if args.pure:
         kind = 'rich' if args.rich else 'plain'
         widget = FrontendWidget(kind=kind, paging=args.paging)
     elif args.rich or args.pylab:
         widget = RichIPythonWidget(paging=args.paging)
     else:
         widget = IPythonWidget(paging=args.paging)
     widget.gui_completion = args.gui_completion
     widget.kernel_manager = kernel_manager
 
     # Create the main window.
-    window = MainWindow(widget)
+    window = MainWindow(app, widget, args.existing)
     window.setWindowTitle('Python' if args.pure else 'IPython')
     window.show()
 
     # Start the application main loop.
     app.exec_()
 
 
 if __name__ == '__main__':
     main()

IPython/frontend/qt/kernelmanager.py

@@ -1,237 +1,240 b''
 """ Defines a KernelManager that provides signals and slots.
 """
 
 # System library imports.
 from PyQt4 import QtCore
 
 # IPython imports.
 from IPython.utils.traitlets import Type
 from IPython.zmq.kernelmanager import KernelManager, SubSocketChannel, \
     XReqSocketChannel, RepSocketChannel, HBSocketChannel
 from util import MetaQObjectHasTraits, SuperQObject
 
 
 class SocketChannelQObject(SuperQObject):
 
     # Emitted when the channel is started.
     started = QtCore.pyqtSignal()
 
     # Emitted when the channel is stopped.
     stopped = QtCore.pyqtSignal()
 
     #---------------------------------------------------------------------------
     # 'ZmqSocketChannel' interface
     #---------------------------------------------------------------------------
 
     def start(self):
         """ Reimplemented to emit signal.
         """
         super(SocketChannelQObject, self).start()
         self.started.emit()
 
     def stop(self):
         """ Reimplemented to emit signal.
         """
         super(SocketChannelQObject, self).stop()
         self.stopped.emit()
 
 
 class QtXReqSocketChannel(SocketChannelQObject, XReqSocketChannel):
 
     # Emitted when any message is received.
     message_received = QtCore.pyqtSignal(object)
 
     # Emitted when a reply has been received for the corresponding request
     # type.
     execute_reply = QtCore.pyqtSignal(object)
     complete_reply = QtCore.pyqtSignal(object)
     object_info_reply = QtCore.pyqtSignal(object)
 
     # Emitted when the first reply comes back.
     first_reply = QtCore.pyqtSignal()
 
     # Used by the first_reply signal logic to determine if a reply is the 
     # first.
     _handlers_called = False
 
     #---------------------------------------------------------------------------
     # 'XReqSocketChannel' interface
     #---------------------------------------------------------------------------
     
     def call_handlers(self, msg):
         """ Reimplemented to emit signals instead of making callbacks.
         """
         # Emit the generic signal.
         self.message_received.emit(msg)
         
         # Emit signals for specialized message types.
         msg_type = msg['msg_type']
         signal = getattr(self, msg_type, None)
         if signal:
             signal.emit(msg)
 
         if not self._handlers_called:
             self.first_reply.emit()
             self._handlers_called = True
 
     #---------------------------------------------------------------------------
     # 'QtXReqSocketChannel' interface
     #---------------------------------------------------------------------------
 
     def reset_first_reply(self):
         """ Reset the first_reply signal to fire again on the next reply.
         """
         self._handlers_called = False
 
 
 class QtSubSocketChannel(SocketChannelQObject, SubSocketChannel):
 
     # Emitted when any message is received.
     message_received = QtCore.pyqtSignal(object)
 
     # Emitted when a message of type 'stream' is received.
     stream_received = QtCore.pyqtSignal(object)
 
     # Emitted when a message of type 'pyin' is received.
     pyin_received = QtCore.pyqtSignal(object)
 
     # Emitted when a message of type 'pyout' is received.
     pyout_received = QtCore.pyqtSignal(object)
 
     # Emitted when a message of type 'pyerr' is received.
     pyerr_received = QtCore.pyqtSignal(object)
 
     # Emitted when a crash report message is received from the kernel's
     # last-resort sys.excepthook.
     crash_received = QtCore.pyqtSignal(object)
 
+    # Emitted when a shutdown is noticed.
+    shutdown_reply_received = QtCore.pyqtSignal(object)
+
     #---------------------------------------------------------------------------
     # 'SubSocketChannel' interface
     #---------------------------------------------------------------------------
     
     def call_handlers(self, msg):
         """ Reimplemented to emit signals instead of making callbacks.
         """
         # Emit the generic signal.
         self.message_received.emit(msg)
         
         # Emit signals for specialized message types.
         msg_type = msg['msg_type']
         signal = getattr(self, msg_type + '_received', None)
         if signal:
             signal.emit(msg)
         elif msg_type in ('stdout', 'stderr'):
             self.stream_received.emit(msg)
 
     def flush(self):
         """ Reimplemented to ensure that signals are dispatched immediately.
         """
         super(QtSubSocketChannel, self).flush()
         QtCore.QCoreApplication.instance().processEvents()
 
 
 class QtRepSocketChannel(SocketChannelQObject, RepSocketChannel):
 
     # Emitted when any message is received.
     message_received = QtCore.pyqtSignal(object)
 
     # Emitted when an input request is received.
     input_requested = QtCore.pyqtSignal(object)
 
     #---------------------------------------------------------------------------
     # 'RepSocketChannel' interface
     #---------------------------------------------------------------------------
 
     def call_handlers(self, msg):
         """ Reimplemented to emit signals instead of making callbacks.
         """
         # Emit the generic signal.
         self.message_received.emit(msg)
         
         # Emit signals for specialized message types.
         msg_type = msg['msg_type']
         if msg_type == 'input_request':
             self.input_requested.emit(msg)
 
 
 class QtHBSocketChannel(SocketChannelQObject, HBSocketChannel):
 
     # Emitted when the kernel has died.
     kernel_died = QtCore.pyqtSignal(object)
 
     #---------------------------------------------------------------------------
     # 'HBSocketChannel' interface
     #---------------------------------------------------------------------------
 
     def call_handlers(self, since_last_heartbeat):
         """ Reimplemented to emit signals instead of making callbacks.
         """
         # Emit the generic signal.
         self.kernel_died.emit(since_last_heartbeat)
 
 
 class QtKernelManager(KernelManager, SuperQObject):
     """ A KernelManager that provides signals and slots.
     """
 
     __metaclass__ = MetaQObjectHasTraits
 
     # Emitted when the kernel manager has started listening.
     started_channels = QtCore.pyqtSignal()
 
     # Emitted when the kernel manager has stopped listening.
     stopped_channels = QtCore.pyqtSignal()
 
     # Use Qt-specific channel classes that emit signals.
     sub_channel_class = Type(QtSubSocketChannel)
     xreq_channel_class = Type(QtXReqSocketChannel)
     rep_channel_class = Type(QtRepSocketChannel)
     hb_channel_class = Type(QtHBSocketChannel)
 
     #---------------------------------------------------------------------------
     # 'KernelManager' interface
     #---------------------------------------------------------------------------
 
     #------ Kernel process management ------------------------------------------
 
     def start_kernel(self, *args, **kw):
         """ Reimplemented for proper heartbeat management.
         """
         if self._xreq_channel is not None:
             self._xreq_channel.reset_first_reply()
         super(QtKernelManager, self).start_kernel(*args, **kw)
 
     #------ Channel management -------------------------------------------------
     
     def start_channels(self, *args, **kw):
         """ Reimplemented to emit signal.
         """
         super(QtKernelManager, self).start_channels(*args, **kw)
         self.started_channels.emit()
 
     def stop_channels(self):
         """ Reimplemented to emit signal.
         """ 
         super(QtKernelManager, self).stop_channels()
         self.stopped_channels.emit()
 
     @property
     def xreq_channel(self):
         """ Reimplemented for proper heartbeat management.
         """
         if self._xreq_channel is None:
             self._xreq_channel = super(QtKernelManager, self).xreq_channel
             self._xreq_channel.first_reply.connect(self._first_reply)
         return self._xreq_channel
 
     #---------------------------------------------------------------------------
     # Protected interface
     #---------------------------------------------------------------------------
     
     def _first_reply(self):
         """ Unpauses the heartbeat channel when the first reply is received on
             the execute channel. Note that this will *not* start the heartbeat
             channel if it is not already running!
         """
         if self._hb_channel is not None:
             self._hb_channel.unpause()

IPython/zmq/ipkernel.py

@@ -1,626 +1,627 b''
 #!/usr/bin/env python
 """A simple interactive kernel that talks to a frontend over 0MQ.
 
 Things to do:
 
 * Implement `set_parent` logic. Right before doing exec, the Kernel should
   call set_parent on all the PUB objects with the message about to be executed.
 * Implement random port and security key logic.
 * Implement control messages.
 * Implement event loop and poll version.
 """
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 # Standard library imports.
 import __builtin__
 import atexit
 import sys
 import time
 import traceback
 
 # System library imports.
 import zmq
 
 # Local imports.
 from IPython.config.configurable import Configurable
 from IPython.utils import io
 from IPython.utils.jsonutil import json_clean
 from IPython.lib import pylabtools
 from IPython.utils.traitlets import Instance, Float
 from entry_point import (base_launch_kernel, make_argument_parser, make_kernel,
                          start_kernel)
 from iostream import OutStream
 from session import Session, Message
 from zmqshell import ZMQInteractiveShell
 
 #-----------------------------------------------------------------------------
 # Main kernel class
 #-----------------------------------------------------------------------------
 
 class Kernel(Configurable):
 
     #---------------------------------------------------------------------------
     # Kernel interface
     #---------------------------------------------------------------------------
 
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
     session = Instance(Session)
     reply_socket = Instance('zmq.Socket')
     pub_socket = Instance('zmq.Socket')
     req_socket = Instance('zmq.Socket')
 
     # Private interface
 
     # Time to sleep after flushing the stdout/err buffers in each execute
     # cycle.  While this introduces a hard limit on the minimal latency of the
     # execute cycle, it helps prevent output synchronization problems for
     # clients.
     # Units are in seconds.  The minimum zmq latency on local host is probably
     # ~150 microseconds, set this to 500us for now.  We may need to increase it
     # a little if it's not enough after more interactive testing.
     _execute_sleep = Float(0.0005, config=True)
 
     # Frequency of the kernel's event loop.
     # Units are in seconds, kernel subclasses for GUI toolkits may need to
     # adapt to milliseconds.
     _poll_interval = Float(0.05, config=True)
 
     # If the shutdown was requested over the network, we leave here the
     # necessary reply message so it can be sent by our registered atexit
     # handler.  This ensures that the reply is only sent to clients truly at
     # the end of our shutdown process (which happens after the underlying
     # IPython shell's own shutdown).
     _shutdown_message = None
 
     # This is a dict of port number that the kernel is listening on. It is set
     # by record_ports and used by connect_request.
     _recorded_ports = None
     
     def __init__(self, **kwargs):
         super(Kernel, self).__init__(**kwargs)
 
         # Before we even start up the shell, register *first* our exit handlers
         # so they come before the shell's
         atexit.register(self._at_shutdown)
 
         # Initialize the InteractiveShell subclass
         self.shell = ZMQInteractiveShell.instance()
         self.shell.displayhook.session = self.session
         self.shell.displayhook.pub_socket = self.pub_socket
 
         # TMP - hack while developing
         self.shell._reply_content = None
 
         # Build dict of handlers for message types
         msg_types = [ 'execute_request', 'complete_request', 
                       'object_info_request', 'history_request',
                       'connect_request', 'shutdown_request']
         self.handlers = {}
         for msg_type in msg_types:
             self.handlers[msg_type] = getattr(self, msg_type)
 
     def do_one_iteration(self):
         """Do one iteration of the kernel's evaluation loop.
         """
         try:
             ident = self.reply_socket.recv(zmq.NOBLOCK)
         except zmq.ZMQError, e:
             if e.errno == zmq.EAGAIN:
                 return
             else:
                 raise
         # FIXME: Bug in pyzmq/zmq?
         # assert self.reply_socket.rcvmore(), "Missing message part."
         msg = self.reply_socket.recv_json()
         
         # Print some info about this message and leave a '--->' marker, so it's
         # easier to trace visually the message chain when debugging.  Each
         # handler prints its message at the end.
         # Eventually we'll move these from stdout to a logger.
         io.raw_print('\n*** MESSAGE TYPE:', msg['msg_type'], '***')
         io.raw_print('   Content: ', msg['content'],
                      '\n   --->\n   ', sep='', end='')
 
         # Find and call actual handler for message
         handler = self.handlers.get(msg['msg_type'], None)
         if handler is None:
             io.raw_print_err("UNKNOWN MESSAGE TYPE:", msg)
         else:
             handler(ident, msg)
             
         # Check whether we should exit, in case the incoming message set the
         # exit flag on
         if self.shell.exit_now:
             io.raw_print('\nExiting IPython kernel...')
             # We do a normal, clean exit, which allows any actions registered
             # via atexit (such as history saving) to take place.
             sys.exit(0)
 
 
     def start(self):
         """ Start the kernel main loop.
         """
         while True:
             time.sleep(self._poll_interval)
             self.do_one_iteration()
 
     def record_ports(self, xrep_port, pub_port, req_port, hb_port):
         """Record the ports that this kernel is using.
 
         The creator of the Kernel instance must call this methods if they
         want the :meth:`connect_request` method to return the port numbers.
         """
         self._recorded_ports = {
             'xrep_port' : xrep_port,
             'pub_port' : pub_port,
             'req_port' : req_port,
             'hb_port' : hb_port
         }
 
     #---------------------------------------------------------------------------
     # Kernel request handlers
     #---------------------------------------------------------------------------
 
     def _publish_pyin(self, code, parent):
         """Publish the code request on the pyin stream."""
 
         pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
         self.pub_socket.send_json(pyin_msg)
 
     def execute_request(self, ident, parent):
         
         status_msg = self.session.msg(
             u'status',
             {u'execution_state':u'busy'},
             parent=parent
         )
         self.pub_socket.send_json(status_msg)
         
         try:
             content = parent[u'content']
             code = content[u'code']
             silent = content[u'silent'] 
         except:
             io.raw_print_err("Got bad msg: ")
             io.raw_print_err(Message(parent))
             return
 
         shell = self.shell # we'll need this a lot here
 
         # Replace raw_input. Note that is not sufficient to replace 
         # raw_input in the user namespace.
         raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
         __builtin__.raw_input = raw_input
 
         # Set the parent message of the display hook and out streams.
         shell.displayhook.set_parent(parent)
         sys.stdout.set_parent(parent)
         sys.stderr.set_parent(parent)
 
         # Re-broadcast our input for the benefit of listening clients, and
         # start computing output
         if not silent:
             self._publish_pyin(code, parent)
 
         reply_content = {}
         try:
             if silent:
                 # runcode uses 'exec' mode, so no displayhook will fire, and it
                 # doesn't call logging or history manipulations.  Print
                 # statements in that code will obviously still execute.
                 shell.runcode(code)
             else:
                 # FIXME: runlines calls the exception handler itself.
                 shell._reply_content = None
 
                 # For now leave this here until we're sure we can stop using it
                 #shell.runlines(code)
 
                 # Experimental: cell mode!  Test more before turning into
                 # default and removing the hacks around runlines.
                 shell.run_cell(code)
         except:
             status = u'error'
             # FIXME: this code right now isn't being used yet by default,
             # because the runlines() call above directly fires off exception
             # reporting.  This code, therefore, is only active in the scenario
             # where runlines itself has an unhandled exception.  We need to
             # uniformize this, for all exception construction to come from a
             # single location in the codbase.
             etype, evalue, tb = sys.exc_info()
             tb_list = traceback.format_exception(etype, evalue, tb)
             reply_content.update(shell._showtraceback(etype, evalue, tb_list))
         else:
             status = u'ok'
 
         reply_content[u'status'] = status
         # Compute the execution counter so clients can display prompts
         reply_content['execution_count'] = shell.displayhook.prompt_count
 
         # FIXME - fish exception info out of shell, possibly left there by
         # runlines.  We'll need to clean up this logic later.
         if shell._reply_content is not None:
             reply_content.update(shell._reply_content)
 
         # At this point, we can tell whether the main code execution succeeded
         # or not.  If it did, we proceed to evaluate user_variables/expressions
         if reply_content['status'] == 'ok':
             reply_content[u'user_variables'] = \
                          shell.user_variables(content[u'user_variables'])
             reply_content[u'user_expressions'] = \
                          shell.user_expressions(content[u'user_expressions'])
         else:
             # If there was an error, don't even try to compute variables or
             # expressions
             reply_content[u'user_variables'] = {}
             reply_content[u'user_expressions'] = {}
 
         # Payloads should be retrieved regardless of outcome, so we can both
         # recover partial output (that could have been generated early in a
         # block, before an error) and clear the payload system always.
         reply_content[u'payload'] = shell.payload_manager.read_payload()
         # Be agressive about clearing the payload because we don't want
         # it to sit in memory until the next execute_request comes in.
         shell.payload_manager.clear_payload()
 
         # Send the reply.
         reply_msg = self.session.msg(u'execute_reply', reply_content, parent)
         io.raw_print(reply_msg)
 
         # Flush output before sending the reply.
         sys.stdout.flush()
         sys.stderr.flush()
         # FIXME: on rare occasions, the flush doesn't seem to make it to the
         # clients... This seems to mitigate the problem, but we definitely need
         # to better understand what's going on.
         if self._execute_sleep:
             time.sleep(self._execute_sleep)
         
         self.reply_socket.send(ident, zmq.SNDMORE)
         self.reply_socket.send_json(reply_msg)
         if reply_msg['content']['status'] == u'error':
             self._abort_queue()
 
         status_msg = self.session.msg(
             u'status',
             {u'execution_state':u'idle'},
             parent=parent
         )
         self.pub_socket.send_json(status_msg)
 
     def complete_request(self, ident, parent):
         txt, matches = self._complete(parent)
         matches = {'matches' : matches,
                    'matched_text' : txt,
                    'status' : 'ok'}
         completion_msg = self.session.send(self.reply_socket, 'complete_reply',
                                            matches, parent, ident)
         io.raw_print(completion_msg)
 
     def object_info_request(self, ident, parent):
         object_info = self.shell.object_inspect(parent['content']['oname'])
         # Before we send this object over, we scrub it for JSON usage
         oinfo = json_clean(object_info)
         msg = self.session.send(self.reply_socket, 'object_info_reply',
                                 oinfo, parent, ident)
         io.raw_print(msg)
 
     def history_request(self, ident, parent):
         output = parent['content']['output']
         index = parent['content']['index']
         raw = parent['content']['raw']
         hist = self.shell.get_history(index=index, raw=raw, output=output)
         content = {'history' : hist}
         msg = self.session.send(self.reply_socket, 'history_reply',
                                 content, parent, ident)
         io.raw_print(msg)
 
     def connect_request(self, ident, parent):
         if self._recorded_ports is not None:
             content = self._recorded_ports.copy()
         else:
             content = {}
         msg = self.session.send(self.reply_socket, 'connect_reply',
                                 content, parent, ident)
         io.raw_print(msg)
 
     def shutdown_request(self, ident, parent):
         self.shell.exit_now = True
-        self._shutdown_message = self.session.msg(u'shutdown_reply', {}, parent)
+        self._shutdown_message = self.session.msg(u'shutdown_reply', parent['content'], parent)
         sys.exit(0)
 
     #---------------------------------------------------------------------------
     # Protected interface
     #---------------------------------------------------------------------------
 
     def _abort_queue(self):
         while True:
             try:
                 ident = self.reply_socket.recv(zmq.NOBLOCK)
             except zmq.ZMQError, e:
                 if e.errno == zmq.EAGAIN:
                     break
             else:
                 assert self.reply_socket.rcvmore(), \
                        "Unexpected missing message part."
                 msg = self.reply_socket.recv_json()
             io.raw_print("Aborting:\n", Message(msg))
             msg_type = msg['msg_type']
             reply_type = msg_type.split('_')[0] + '_reply'
             reply_msg = self.session.msg(reply_type, {'status' : 'aborted'}, msg)
             io.raw_print(reply_msg)
             self.reply_socket.send(ident,zmq.SNDMORE)
             self.reply_socket.send_json(reply_msg)
             # We need to wait a bit for requests to come in. This can probably
             # be set shorter for true asynchronous clients.
             time.sleep(0.1)
 
     def _raw_input(self, prompt, ident, parent):
         # Flush output before making the request.
         sys.stderr.flush()
         sys.stdout.flush()
 
         # Send the input request.
         content = dict(prompt=prompt)
         msg = self.session.msg(u'input_request', content, parent)
         self.req_socket.send_json(msg)
 
         # Await a response.
         reply = self.req_socket.recv_json()
         try:
             value = reply['content']['value']
         except:
             io.raw_print_err("Got bad raw_input reply: ")
             io.raw_print_err(Message(parent))
             value = ''
         return value
     
     def _complete(self, msg):
         c = msg['content']
         try:
             cpos = int(c['cursor_pos'])
         except:
             # If we don't get something that we can convert to an integer, at
             # least attempt the completion guessing the cursor is at the end of
             # the text, if there's any, and otherwise of the line
             cpos = len(c['text'])
             if cpos==0:
                 cpos = len(c['line'])
         return self.shell.complete(c['text'], c['line'], cpos)
 
     def _object_info(self, context):
         symbol, leftover = self._symbol_from_context(context)
         if symbol is not None and not leftover:
             doc = getattr(symbol, '__doc__', '')
         else:
             doc = ''
         object_info = dict(docstring = doc)
         return object_info
 
     def _symbol_from_context(self, context):
         if not context:
             return None, context
 
         base_symbol_string = context[0]
         symbol = self.shell.user_ns.get(base_symbol_string, None)
         if symbol is None:
             symbol = __builtin__.__dict__.get(base_symbol_string, None)
         if symbol is None:
             return None, context
 
         context = context[1:]
         for i, name in enumerate(context):
             new_symbol = getattr(symbol, name, None)
             if new_symbol is None:
                 return symbol, context[i:]
             else:
                 symbol = new_symbol
 
         return symbol, []
 
     def _at_shutdown(self):
         """Actions taken at shutdown by the kernel, called by python's atexit.
         """
         # io.rprint("Kernel at_shutdown") # dbg
         if self._shutdown_message is not None:
             self.reply_socket.send_json(self._shutdown_message)
+            self.pub_socket.send_json(self._shutdown_message)
             io.raw_print(self._shutdown_message)
             # A very short sleep to give zmq time to flush its message buffers
             # before Python truly shuts down.
             time.sleep(0.01)
 
 
 class QtKernel(Kernel):
     """A Kernel subclass with Qt support."""
 
     def start(self):
         """Start a kernel with QtPy4 event loop integration."""
 
         from PyQt4 import QtCore
         from IPython.lib.guisupport import get_app_qt4, start_event_loop_qt4
 
         self.app = get_app_qt4([" "])
         self.app.setQuitOnLastWindowClosed(False)
         self.timer = QtCore.QTimer()
         self.timer.timeout.connect(self.do_one_iteration)
         # Units for the timer are in milliseconds
         self.timer.start(1000*self._poll_interval)
         start_event_loop_qt4(self.app)
 
 
 class WxKernel(Kernel):
     """A Kernel subclass with Wx support."""
 
     def start(self):
         """Start a kernel with wx event loop support."""
 
         import wx
         from IPython.lib.guisupport import start_event_loop_wx
 
         doi = self.do_one_iteration
          # Wx uses milliseconds
         poll_interval = int(1000*self._poll_interval)
 
         # We have to put the wx.Timer in a wx.Frame for it to fire properly.
         # We make the Frame hidden when we create it in the main app below.
         class TimerFrame(wx.Frame):
             def __init__(self, func):
                 wx.Frame.__init__(self, None, -1)
                 self.timer = wx.Timer(self)
                 # Units for the timer are in milliseconds
                 self.timer.Start(poll_interval)
                 self.Bind(wx.EVT_TIMER, self.on_timer)
                 self.func = func
 
             def on_timer(self, event):
                 self.func()
 
         # We need a custom wx.App to create our Frame subclass that has the
         # wx.Timer to drive the ZMQ event loop.
         class IPWxApp(wx.App):
             def OnInit(self):
                 self.frame = TimerFrame(doi)
                 self.frame.Show(False)
                 return True
 
         # The redirect=False here makes sure that wx doesn't replace
         # sys.stdout/stderr with its own classes.
         self.app = IPWxApp(redirect=False)
         start_event_loop_wx(self.app)
 
 
 class TkKernel(Kernel):
     """A Kernel subclass with Tk support."""
 
     def start(self):
         """Start a Tk enabled event loop."""
 
         import Tkinter
         doi = self.do_one_iteration
         # Tk uses milliseconds
         poll_interval = int(1000*self._poll_interval)
         # For Tkinter, we create a Tk object and call its withdraw method.
         class Timer(object):
             def __init__(self, func):
                 self.app = Tkinter.Tk()
                 self.app.withdraw()
                 self.func = func
                 
             def on_timer(self):
                 self.func()
                 self.app.after(poll_interval, self.on_timer)
                 
             def start(self):
                 self.on_timer()  # Call it once to get things going.
                 self.app.mainloop()
 
         self.timer = Timer(doi)
         self.timer.start()
 
 
 class GTKKernel(Kernel):
     """A Kernel subclass with GTK support."""
     
     def start(self):
         """Start the kernel, coordinating with the GTK event loop"""
         from .gui.gtkembed import GTKEmbed
         
         gtk_kernel = GTKEmbed(self)
         gtk_kernel.start()
 
 
 #-----------------------------------------------------------------------------
 # Kernel main and launch functions
 #-----------------------------------------------------------------------------
 
 def launch_kernel(xrep_port=0, pub_port=0, req_port=0, hb_port=0,
                   independent=False, pylab=False):
     """Launches a localhost kernel, binding to the specified ports.
 
     Parameters
     ----------
     xrep_port : int, optional
         The port to use for XREP channel.
 
     pub_port : int, optional
         The port to use for the SUB channel.
 
     req_port : int, optional
         The port to use for the REQ (raw input) channel.
 
     hb_port : int, optional
         The port to use for the hearbeat REP channel.
 
     independent : bool, optional (default False) 
         If set, the kernel process is guaranteed to survive if this process
         dies. If not set, an effort is made to ensure that the kernel is killed
         when this process dies. Note that in this case it is still good practice
         to kill kernels manually before exiting.
 
     pylab : bool or string, optional (default False)
         If not False, the kernel will be launched with pylab enabled. If a
         string is passed, matplotlib will use the specified backend. Otherwise,
         matplotlib's default backend will be used.
 
     Returns
     -------
     A tuple of form:
         (kernel_process, xrep_port, pub_port, req_port)
     where kernel_process is a Popen object and the ports are integers.
     """
     extra_arguments = []
     if pylab:
         extra_arguments.append('--pylab')
         if isinstance(pylab, basestring):
             extra_arguments.append(pylab)
     return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
                               xrep_port, pub_port, req_port, hb_port, 
                               independent, extra_arguments)
 
 
 def main():
     """ The IPython kernel main entry point.
     """
     parser = make_argument_parser()
     parser.add_argument('--pylab', type=str, metavar='GUI', nargs='?', 
                         const='auto', help = \
 "Pre-load matplotlib and numpy for interactive use. If GUI is not \
 given, the GUI backend is matplotlib's, otherwise use one of: \
 ['tk', 'gtk', 'qt', 'wx', 'inline'].")
     namespace = parser.parse_args()
 
     kernel_class = Kernel
 
     kernel_classes = {
         'qt' : QtKernel,
         'qt4': QtKernel,
         'inline': Kernel,
         'wx' : WxKernel,
         'tk' : TkKernel,
         'gtk': GTKKernel,
     }
     if namespace.pylab:
         if namespace.pylab == 'auto':
             gui, backend = pylabtools.find_gui_and_backend()
         else:
             gui, backend = pylabtools.find_gui_and_backend(namespace.pylab)
         kernel_class = kernel_classes.get(gui)
         if kernel_class is None:
             raise ValueError('GUI is not supported: %r' % gui)
         pylabtools.activate_matplotlib(backend)
 
     kernel = make_kernel(namespace, kernel_class, OutStream)
 
     if namespace.pylab:
         pylabtools.import_pylab(kernel.shell.user_ns, backend,
                                 shell=kernel.shell)
 
     start_kernel(namespace, kernel)
 
 
 if __name__ == '__main__':
     main()

IPython/zmq/kernelmanager.py

@@ -1,905 +1,905 b''
 """Base classes to manage the interaction with a running kernel.
 
 TODO
 * Create logger to handle debugging and console messages.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Standard library imports.
 import atexit
 from Queue import Queue, Empty
 from subprocess import Popen
 import signal
 import sys
 from threading import Thread
 import time
 
 # System library imports.
 import zmq
 from zmq import POLLIN, POLLOUT, POLLERR
 from zmq.eventloop import ioloop
 
 # Local imports.
 from IPython.utils import io
 from IPython.utils.traitlets import HasTraits, Any, Instance, Type, TCPAddress
 from session import Session
 
 #-----------------------------------------------------------------------------
 # Constants and exceptions
 #-----------------------------------------------------------------------------
 
 LOCALHOST = '127.0.0.1'
 
 class InvalidPortNumber(Exception):
     pass
 
 #-----------------------------------------------------------------------------
 # Utility functions
 #-----------------------------------------------------------------------------
 
 # some utilities to validate message structure, these might get moved elsewhere
 # if they prove to have more generic utility
 
 def validate_string_list(lst):
     """Validate that the input is a list of strings.
 
     Raises ValueError if not."""
     if not isinstance(lst, list):
         raise ValueError('input %r must be a list' % lst)
     for x in lst:
         if not isinstance(x, basestring):
             raise ValueError('element %r in list must be a string' % x)
 
 
 def validate_string_dict(dct):
     """Validate that the input is a dict with string keys and values.
 
     Raises ValueError if not."""
     for k,v in dct.iteritems():
         if not isinstance(k, basestring):
             raise ValueError('key %r in dict must be a string' % k)
         if not isinstance(v, basestring):
             raise ValueError('value %r in dict must be a string' % v)
 
 
 #-----------------------------------------------------------------------------
 # ZMQ Socket Channel classes
 #-----------------------------------------------------------------------------
 
 class ZmqSocketChannel(Thread):
     """The base class for the channels that use ZMQ sockets.
     """
     context = None
     session = None
     socket = None
     ioloop = None
     iostate = None
     _address = None
 
     def __init__(self, context, session, address):
         """Create a channel
 
         Parameters
         ----------
         context : :class:`zmq.Context`
             The ZMQ context to use.
         session : :class:`session.Session`
             The session to use.
         address : tuple
             Standard (ip, port) tuple that the kernel is listening on.
         """
         super(ZmqSocketChannel, self).__init__()
         self.daemon = True
 
         self.context = context
         self.session = session
         if address[1] == 0:
             message = 'The port number for a channel cannot be 0.'
             raise InvalidPortNumber(message)
         self._address = address
 
     def stop(self):
         """Stop the channel's activity.
 
         This calls :method:`Thread.join` and returns when the thread
         terminates. :class:`RuntimeError` will be raised if 
         :method:`self.start` is called again.
         """
         self.join()
 
     @property
     def address(self):
         """Get the channel's address as an (ip, port) tuple.
         
         By the default, the address is (localhost, 0), where 0 means a random
         port.
         """
         return self._address
 
     def add_io_state(self, state):
         """Add IO state to the eventloop.
 
         Parameters
         ----------
         state : zmq.POLLIN|zmq.POLLOUT|zmq.POLLERR
             The IO state flag to set.
 
         This is thread safe as it uses the thread safe IOLoop.add_callback.
         """
         def add_io_state_callback():
             if not self.iostate & state:
                 self.iostate = self.iostate | state
                 self.ioloop.update_handler(self.socket, self.iostate)
         self.ioloop.add_callback(add_io_state_callback)
 
     def drop_io_state(self, state):
         """Drop IO state from the eventloop.
 
         Parameters
         ----------
         state : zmq.POLLIN|zmq.POLLOUT|zmq.POLLERR
             The IO state flag to set.
 
         This is thread safe as it uses the thread safe IOLoop.add_callback.
         """
         def drop_io_state_callback():
             if self.iostate & state:
                 self.iostate = self.iostate & (~state)
                 self.ioloop.update_handler(self.socket, self.iostate)
         self.ioloop.add_callback(drop_io_state_callback)
 
 
 class XReqSocketChannel(ZmqSocketChannel):
     """The XREQ channel for issues request/replies to the kernel.
     """
 
     command_queue = None
 
     def __init__(self, context, session, address):
         super(XReqSocketChannel, self).__init__(context, session, address)
         self.command_queue = Queue()
         self.ioloop = ioloop.IOLoop()
 
     def run(self):
         """The thread's main activity.  Call start() instead."""
         self.socket = self.context.socket(zmq.XREQ)
         self.socket.setsockopt(zmq.IDENTITY, self.session.session)
         self.socket.connect('tcp://%s:%i' % self.address)
         self.iostate = POLLERR|POLLIN
         self.ioloop.add_handler(self.socket, self._handle_events, 
                                 self.iostate)
         self.ioloop.start()
 
     def stop(self):
         self.ioloop.stop()
         super(XReqSocketChannel, self).stop()
 
     def call_handlers(self, msg):
         """This method is called in the ioloop thread when a message arrives.
 
         Subclasses should override this method to handle incoming messages.
         It is important to remember that this method is called in the thread
         so that some logic must be done to ensure that the application leve
         handlers are called in the application thread.
         """
         raise NotImplementedError('call_handlers must be defined in a subclass.')
 
     def execute(self, code, silent=False,
                 user_variables=None, user_expressions=None):
         """Execute code in the kernel.
 
         Parameters
         ----------
         code : str
             A string of Python code.
             
         silent : bool, optional (default False)
             If set, the kernel will execute the code as quietly possible.
 
         user_variables : list, optional
             A list of variable names to pull from the user's namespace.  They
             will come back as a dict with these names as keys and their
             :func:`repr` as values.
             
         user_expressions : dict, optional
             A dict with string keys and  to pull from the user's
             namespace.  They will come back as a dict with these names as keys
             and their :func:`repr` as values.
 
         Returns
         -------
         The msg_id of the message sent.
         """
         if user_variables is None:
             user_variables = []
         if user_expressions is None:
             user_expressions = {}
             
         # Don't waste network traffic if inputs are invalid
         if not isinstance(code, basestring):
             raise ValueError('code %r must be a string' % code)
         validate_string_list(user_variables)
         validate_string_dict(user_expressions)
 
         # Create class for content/msg creation. Related to, but possibly
         # not in Session.
         content = dict(code=code, silent=silent,
                        user_variables=user_variables,
                        user_expressions=user_expressions)
         msg = self.session.msg('execute_request', content)
         self._queue_request(msg)
         return msg['header']['msg_id']
 
     def complete(self, text, line, cursor_pos, block=None):
         """Tab complete text in the kernel's namespace.
 
         Parameters
         ----------
         text : str
             The text to complete.
         line : str
             The full line of text that is the surrounding context for the 
             text to complete.
         cursor_pos : int
             The position of the cursor in the line where the completion was
             requested.
         block : str, optional
             The full block of code in which the completion is being requested.
 
         Returns
         -------
         The msg_id of the message sent.
         """
         content = dict(text=text, line=line, block=block, cursor_pos=cursor_pos)
         msg = self.session.msg('complete_request', content)
         self._queue_request(msg)
         return msg['header']['msg_id']
 
     def object_info(self, oname):
         """Get metadata information about an object.
 
         Parameters
         ----------
         oname : str
             A string specifying the object name.
         
         Returns
         -------
         The msg_id of the message sent.
         """
         content = dict(oname=oname)
         msg = self.session.msg('object_info_request', content)
         self._queue_request(msg)
         return msg['header']['msg_id']
 
     def history(self, index=None, raw=False, output=True):
         """Get the history list.
 
         Parameters
         ----------
         index : n or (n1, n2) or None
             If n, then the last entries. If a tuple, then all in
             range(n1, n2). If None, then all entries. Raises IndexError if
             the format of index is incorrect.
         raw : bool
             If True, return the raw input.
         output : bool
             If True, then return the output as well.
 
         Returns
         -------
         The msg_id of the message sent.
         """
         content = dict(index=index, raw=raw, output=output)
         msg = self.session.msg('history_request', content)
         self._queue_request(msg)
         return msg['header']['msg_id']
 
-    def shutdown(self):
+    def shutdown(self, restart=False):
         """Request an immediate kernel shutdown.
 
         Upon receipt of the (empty) reply, client code can safely assume that
         the kernel has shut down and it's safe to forcefully terminate it if
         it's still alive.
 
         The kernel will send the reply via a function registered with Python's
         atexit module, ensuring it's truly done as the kernel is done with all
         normal operation.
         """
         # Send quit message to kernel. Once we implement kernel-side setattr,
         # this should probably be done that way, but for now this will do.
-        msg = self.session.msg('shutdown_request', {})
+        msg = self.session.msg('shutdown_request', {'restart':restart})
         self._queue_request(msg)
         return msg['header']['msg_id']
 
     def _handle_events(self, socket, events):
         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)
         if self.command_queue.empty():
             self.drop_io_state(POLLOUT)
 
     def _handle_err(self):
         # We don't want to let this go silently, so eventually we should log.
         raise zmq.ZMQError()
 
     def _queue_request(self, msg):
         self.command_queue.put(msg)
         self.add_io_state(POLLOUT)
 
 
 class SubSocketChannel(ZmqSocketChannel):
     """The SUB channel which listens for messages that the kernel publishes.
     """
 
     def __init__(self, context, session, address):
         super(SubSocketChannel, self).__init__(context, session, address)
         self.ioloop = ioloop.IOLoop()
 
     def run(self):
         """The thread's main activity.  Call start() instead."""
         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.address)
         self.iostate = POLLIN|POLLERR
         self.ioloop.add_handler(self.socket, self._handle_events, 
                                 self.iostate)
         self.ioloop.start()
 
     def stop(self):
         self.ioloop.stop()
         super(SubSocketChannel, self).stop()
 
     def call_handlers(self, msg):
         """This method is called in the ioloop thread when a message arrives.
 
         Subclasses should override this method to handle incoming messages.
         It is important to remember that this method is called in the thread
         so that some logic must be done to ensure that the application leve
         handlers are called in the application thread.
         """
         raise NotImplementedError('call_handlers must be defined in a subclass.')
 
     def flush(self, timeout=1.0):
         """Immediately processes all pending messages on the SUB channel.
 
         Callers should use this method to ensure that :method:`call_handlers`
         has been called for all messages that have been received on the
         0MQ SUB socket of this channel.
 
         This method is thread safe.
 
         Parameters
         ----------
         timeout : float, optional
             The maximum amount of time to spend flushing, in seconds. The
             default is one second.
         """
         # We do the IOLoop callback process twice to ensure that the IOLoop
         # gets to perform at least one full poll.
         stop_time = time.time() + timeout
         for i in xrange(2):
             self._flushed = False
             self.ioloop.add_callback(self._flush)
             while not self._flushed and time.time() < stop_time:
                 time.sleep(0.01)
 
     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):
         # We don't want to let this go silently, so eventually we should log.
         raise zmq.ZMQError()
 
     def _handle_recv(self):
         # Get all of the messages we can
         while True:
             try:
                 msg = self.socket.recv_json(zmq.NOBLOCK)
             except zmq.ZMQError:
                 # Check the errno?
                 # Will this trigger POLLERR?
                 break
             else:
                 self.call_handlers(msg)
 
     def _flush(self):
         """Callback for :method:`self.flush`."""
         self._flushed = True
 
 
 class RepSocketChannel(ZmqSocketChannel):
     """A reply channel to handle raw_input requests that the kernel makes."""
 
     msg_queue = None
 
     def __init__(self, context, session, address):
         super(RepSocketChannel, self).__init__(context, session, address)
         self.ioloop = ioloop.IOLoop()
         self.msg_queue = Queue()
 
     def run(self):
         """The thread's main activity.  Call start() instead."""
         self.socket = self.context.socket(zmq.XREQ)
         self.socket.setsockopt(zmq.IDENTITY, self.session.session)
         self.socket.connect('tcp://%s:%i' % self.address)
         self.iostate = POLLERR|POLLIN
         self.ioloop.add_handler(self.socket, self._handle_events, 
                                 self.iostate)
         self.ioloop.start()
 
     def stop(self):
         self.ioloop.stop()
         super(RepSocketChannel, self).stop()
 
     def call_handlers(self, msg):
         """This method is called in the ioloop thread when a message arrives.
 
         Subclasses should override this method to handle incoming messages.
         It is important to remember that this method is called in the thread
         so that some logic must be done to ensure that the application leve
         handlers are called in the application thread.
         """
         raise NotImplementedError('call_handlers must be defined in a subclass.')
 
     def input(self, string):
         """Send a string of raw input to the kernel."""
         content = dict(value=string)
         msg = self.session.msg('input_reply', content)
         self._queue_reply(msg)
 
     def _handle_events(self, socket, events):
         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.msg_queue.get(False)
         except Empty:
             pass
         else:
             self.socket.send_json(msg)
         if self.msg_queue.empty():
             self.drop_io_state(POLLOUT)
 
     def _handle_err(self):
         # We don't want to let this go silently, so eventually we should log.
         raise zmq.ZMQError()
 
     def _queue_reply(self, msg):
         self.msg_queue.put(msg)
         self.add_io_state(POLLOUT)
 
 
 class HBSocketChannel(ZmqSocketChannel):
     """The heartbeat channel which monitors the kernel heartbeat.
 
     Note that the heartbeat channel is paused by default. As long as you start
     this channel, the kernel manager will ensure that it is paused and un-paused
     as appropriate.
     """
 
     time_to_dead = 3.0
     socket = None
     poller = None
     _running = None
     _pause = None
 
     def __init__(self, context, session, address):
         super(HBSocketChannel, self).__init__(context, session, address)
         self._running = False
         self._pause = True
 
     def _create_socket(self):
         self.socket = self.context.socket(zmq.REQ)
         self.socket.setsockopt(zmq.IDENTITY, self.session.session)
         self.socket.connect('tcp://%s:%i' % self.address)
         self.poller = zmq.Poller()
         self.poller.register(self.socket, zmq.POLLIN)
 
     def run(self):
         """The thread's main activity.  Call start() instead."""
         self._create_socket()
         self._running = True
         while self._running:
             if self._pause:
                 time.sleep(self.time_to_dead)
             else:
                 since_last_heartbeat = 0.0
                 request_time = time.time()
                 try:
                     #io.rprint('Ping from HB channel') # dbg
                     self.socket.send_json('ping')
                 except zmq.ZMQError, e:
                     #io.rprint('*** HB Error:', e) # dbg
                     if e.errno == zmq.EFSM:
                         #io.rprint('sleep...', self.time_to_dead) # dbg
                         time.sleep(self.time_to_dead)
                         self._create_socket()
                     else:
                         raise
                 else:
                     while True:
                         try:
                             self.socket.recv_json(zmq.NOBLOCK)
                         except zmq.ZMQError, e:
                             #io.rprint('*** HB Error 2:', e) # dbg
                             if e.errno == zmq.EAGAIN:
                                 before_poll = time.time()
                                 until_dead = self.time_to_dead - (before_poll -
                                                                   request_time)
 
                                 # When the return value of poll() is an empty
                                 # list, that is when things have gone wrong
                                 # (zeromq bug). As long as it is not an empty
                                 # list, poll is working correctly even if it
                                 # returns quickly. Note: poll timeout is in
                                 # milliseconds.
                                 self.poller.poll(1000*until_dead)
                             
                                 since_last_heartbeat = time.time()-request_time
                                 if since_last_heartbeat > self.time_to_dead:
                                     self.call_handlers(since_last_heartbeat)
                                     break
                             else:
                                 # FIXME: We should probably log this instead.
                                 raise
                         else:
                             until_dead = self.time_to_dead - (time.time() -
                                                               request_time)
                             if until_dead > 0.0:
                                 #io.rprint('sleep...', self.time_to_dead) # dbg
                                 time.sleep(until_dead)
                             break
 
     def pause(self):
         """Pause the heartbeat."""
         self._pause = True
 
     def unpause(self):
         """Unpause the heartbeat."""
         self._pause = False
 
     def is_beating(self):
         """Is the heartbeat running and not paused."""
         if self.is_alive() and not self._pause:
             return True
         else:
             return False
 
     def stop(self):
         self._running = False
         super(HBSocketChannel, self).stop()
 
     def call_handlers(self, since_last_heartbeat):
         """This method is called in the ioloop thread when a message arrives.
 
         Subclasses should override this method to handle incoming messages.
         It is important to remember that this method is called in the thread
         so that some logic must be done to ensure that the application leve
         handlers are called in the application thread.
         """
         raise NotImplementedError('call_handlers must be defined in a subclass.')
 
 
 #-----------------------------------------------------------------------------
 # Main kernel manager class
 #-----------------------------------------------------------------------------
 
 class KernelManager(HasTraits):
     """ Manages a kernel for a frontend.
 
     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 kernel process with which the KernelManager is communicating.
     kernel = Instance(Popen)
 
     # The addresses for the communication channels. 
     xreq_address = TCPAddress((LOCALHOST, 0))
     sub_address = TCPAddress((LOCALHOST, 0))
     rep_address = TCPAddress((LOCALHOST, 0))
     hb_address = TCPAddress((LOCALHOST, 0))
 
     # The classes to use for the various channels.
     xreq_channel_class = Type(XReqSocketChannel)
     sub_channel_class = Type(SubSocketChannel)
     rep_channel_class = Type(RepSocketChannel)
     hb_channel_class = Type(HBSocketChannel)
 
     # Protected traits.
     _launch_args = Any
     _xreq_channel = Any
     _sub_channel = Any
     _rep_channel = Any
     _hb_channel = Any
 
     def __init__(self, **kwargs):
         super(KernelManager, self).__init__(**kwargs)
         # Uncomment this to try closing the context.
         # atexit.register(self.context.close)
 
     #--------------------------------------------------------------------------
     # Channel management methods:
     #--------------------------------------------------------------------------
 
     def start_channels(self, xreq=True, sub=True, rep=True, hb=True):
         """Starts the channels for this kernel.
 
         This will create the channels if they do not exist and then start
         them. If port numbers of 0 are being used (random ports) then you
         must first call :method:`start_kernel`. If the channels have been
         stopped and you call this, :class:`RuntimeError` will be raised.
         """
         if xreq:
             self.xreq_channel.start()
         if sub:
             self.sub_channel.start()
         if rep:
             self.rep_channel.start()
         if hb:
             self.hb_channel.start()
 
     def stop_channels(self):
         """Stops all the running channels for this kernel.
         """
         if self.xreq_channel.is_alive():
             self.xreq_channel.stop()
         if self.sub_channel.is_alive():
             self.sub_channel.stop()
         if self.rep_channel.is_alive():
             self.rep_channel.stop()
         if self.hb_channel.is_alive():
             self.hb_channel.stop()
 
     @property
     def channels_running(self):
         """Are any of the channels created and running?"""
         return (self.xreq_channel.is_alive() or self.sub_channel.is_alive() or
                 self.rep_channel.is_alive() or self.hb_channel.is_alive())
 
     #--------------------------------------------------------------------------
     # Kernel process management methods:
     #--------------------------------------------------------------------------
 
     def start_kernel(self, **kw):
         """Starts a kernel process and configures the manager to use it.
 
         If random ports (port=0) are being used, this method must be called
         before the channels are created.
 
         Parameters:
         -----------
         ipython : bool, optional (default True)
              Whether to use an IPython kernel instead of a plain Python kernel.
         """
         xreq, sub, rep, hb = self.xreq_address, self.sub_address, \
             self.rep_address, self.hb_address
         if xreq[0] != LOCALHOST or sub[0] != LOCALHOST or \
                 rep[0] != LOCALHOST or hb[0] != LOCALHOST:
             raise RuntimeError("Can only launch a kernel on localhost."
                                "Make sure that the '*_address' attributes are "
                                "configured properly.")
 
         self._launch_args = kw.copy()
         if kw.pop('ipython', True):
             from ipkernel import launch_kernel
         else:
             from pykernel import launch_kernel
         self.kernel, xrep, pub, req, hb = launch_kernel(
             xrep_port=xreq[1], pub_port=sub[1], 
             req_port=rep[1], hb_port=hb[1], **kw)
         self.xreq_address = (LOCALHOST, xrep)
         self.sub_address = (LOCALHOST, pub)
         self.rep_address = (LOCALHOST, req)
         self.hb_address = (LOCALHOST, hb)
 
-    def shutdown_kernel(self):
+    def shutdown_kernel(self, restart=False):
         """ Attempts to the stop the kernel process cleanly. If the kernel
         cannot be stopped, it is killed, if possible.
         """
         # FIXME: Shutdown does not work on Windows due to ZMQ errors!
         if sys.platform == 'win32':
             self.kill_kernel()
             return
 
         # Pause the heart beat channel if it exists.
         if self._hb_channel is not None:
             self._hb_channel.pause()
 
         # Don't send any additional kernel kill messages immediately, to give
         # the kernel a chance to properly execute shutdown actions. Wait for at
         # most 1s, checking every 0.1s.
-        self.xreq_channel.shutdown()
+        self.xreq_channel.shutdown(restart=restart)
         for i in range(10):
             if self.is_alive:
                 time.sleep(0.1)
             else:
                 break
         else:
             # OK, we've waited long enough.
             if self.has_kernel:
                 self.kill_kernel()
     
     def restart_kernel(self, now=False):
         """Restarts a kernel with the same arguments that were used to launch
         it. If the old kernel was launched with random ports, the same ports
         will be used for the new kernel.
 
         Parameters
         ----------
         now : bool, optional
           If True, the kernel is forcefully restarted *immediately*, without
           having a chance to do any cleanup action.  Otherwise the kernel is
           given 1s to clean up before a forceful restart is issued.
 
           In all cases the kernel is restarted, the only difference is whether
           it is given a chance to perform a clean shutdown or not.
         """
         if self._launch_args is None:
             raise RuntimeError("Cannot restart the kernel. "
                                "No previous call to 'start_kernel'.")
         else:
             if self.has_kernel:
                 if now:
                     self.kill_kernel()
                 else:
-                    self.shutdown_kernel()
+                    self.shutdown_kernel(restart=True)
             self.start_kernel(**self._launch_args)
 
             # FIXME: Messages get dropped in Windows due to probable ZMQ bug
             # unless there is some delay here.
             if sys.platform == 'win32':
                 time.sleep(0.2)
 
     @property
     def has_kernel(self):
         """Returns whether a kernel process has been specified for the kernel
         manager.
         """
         return self.kernel is not None
 
     def kill_kernel(self):
         """ Kill the running kernel. """
         if self.has_kernel:
             # Pause the heart beat channel if it exists.
             if self._hb_channel is not None:
                 self._hb_channel.pause()
 
             # Attempt to kill the kernel.
             try:
                 self.kernel.kill()
             except OSError, e:
                 # In Windows, we will get an Access Denied error if the process
                 # has already terminated. Ignore it.
                 if not (sys.platform == 'win32' and e.winerror == 5):
                     raise
             self.kernel = None
         else:
             raise RuntimeError("Cannot kill kernel. No kernel is running!")
 
     def interrupt_kernel(self):
         """ Interrupts the kernel. Unlike ``signal_kernel``, this operation is
         well supported on all platforms.
         """
         if self.has_kernel:
             if sys.platform == 'win32':
                 from parentpoller import ParentPollerWindows as Poller
                 Poller.send_interrupt(self.kernel.win32_interrupt_event)
             else:
                 self.kernel.send_signal(signal.SIGINT)
         else:
             raise RuntimeError("Cannot interrupt kernel. No kernel is running!")
 
     def signal_kernel(self, signum):
         """ Sends a signal to the kernel. Note that since only SIGTERM is
         supported on Windows, this function is only useful on Unix systems.
         """
         if self.has_kernel:
             self.kernel.send_signal(signum)
         else:
             raise RuntimeError("Cannot signal kernel. No kernel is running!")
 
     @property
     def is_alive(self):
         """Is the kernel process still running?"""
         # FIXME: not using a heartbeat means this method is broken for any
         # remote kernel, it's only capable of handling local kernels.
         if self.has_kernel:
             if self.kernel.poll() is None:
                 return True
             else:
                 return False
         else:
             # We didn't start the kernel with this KernelManager so we don't
             # know if it is running. We should use a heartbeat for this case.
             return True
 
     #--------------------------------------------------------------------------
     # Channels used for communication with the kernel:
     #--------------------------------------------------------------------------
 
     @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)
         return self._xreq_channel
 
     @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)
         return self._sub_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)
         return self._rep_channel
 
     @property
     def hb_channel(self):
         """Get the REP socket channel object to handle stdin (raw_input)."""
         if self._hb_channel is None:
             self._hb_channel = self.hb_channel_class(self.context, 
                                                        self.session,
                                                        self.hb_address)
         return self._hb_channel

IPython/zmq/pykernel.py

@@ -1,286 +1,296 b''
 #!/usr/bin/env python
 """A simple interactive kernel that talks to a frontend over 0MQ.
 
 Things to do:
 
 * Implement `set_parent` logic. Right before doing exec, the Kernel should
   call set_parent on all the PUB objects with the message about to be executed.
 * Implement random port and security key logic.
 * Implement control messages.
 * Implement event loop and poll version.
 """
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Standard library imports.
 import __builtin__
 from code import CommandCompiler
 import sys
 import time
 import traceback
 
 # System library imports.
 import zmq
 
 # Local imports.
 from IPython.utils.traitlets import HasTraits, Instance
 from completer import KernelCompleter
 from entry_point import base_launch_kernel, make_default_main
 from session import Session, Message
 
 #-----------------------------------------------------------------------------
 # Main kernel class
 #-----------------------------------------------------------------------------
 
 class Kernel(HasTraits):
 
     # Private interface
 
     # This is a dict of port number that the kernel is listening on. It is set
     # by record_ports and used by connect_request.
     _recorded_ports = None
 
     #---------------------------------------------------------------------------
     # Kernel interface
     #---------------------------------------------------------------------------
 
     session = Instance(Session)
     reply_socket = Instance('zmq.Socket')
     pub_socket = Instance('zmq.Socket')
     req_socket = Instance('zmq.Socket')
 
     def __init__(self, **kwargs):
         super(Kernel, self).__init__(**kwargs)
         self.user_ns = {}
         self.history = []
         self.compiler = CommandCompiler()
         self.completer = KernelCompleter(self.user_ns)
 
         # Build dict of handlers for message types
         msg_types = [ 'execute_request', 'complete_request', 
-                      'object_info_request' ]
+                      'object_info_request', 'shutdown_request' ]
         self.handlers = {}
         for msg_type in msg_types:
             self.handlers[msg_type] = getattr(self, msg_type)
 
     def start(self):
         """ Start the kernel main loop.
         """
         while True:
             ident = self.reply_socket.recv()
             assert self.reply_socket.rcvmore(), "Missing message part."
             msg = self.reply_socket.recv_json()
             omsg = Message(msg)
             print>>sys.__stdout__
             print>>sys.__stdout__, omsg
             handler = self.handlers.get(omsg.msg_type, None)
             if handler is None:
                 print >> sys.__stderr__, "UNKNOWN MESSAGE TYPE:", omsg
             else:
                 handler(ident, omsg)
 
     def record_ports(self, xrep_port, pub_port, req_port, hb_port):
         """Record the ports that this kernel is using.
 
         The creator of the Kernel instance must call this methods if they
         want the :meth:`connect_request` method to return the port numbers.
         """
         self._recorded_ports = {
             'xrep_port' : xrep_port,
             'pub_port' : pub_port,
             'req_port' : req_port,
             'hb_port' : hb_port
         }
 
     #---------------------------------------------------------------------------
     # Kernel request handlers
     #---------------------------------------------------------------------------
 
     def execute_request(self, ident, parent):
         try:
             code = parent[u'content'][u'code']
         except:
             print>>sys.__stderr__, "Got bad msg: "
             print>>sys.__stderr__, Message(parent)
             return
         pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
         self.pub_socket.send_json(pyin_msg)
 
         try:
             comp_code = self.compiler(code, '<zmq-kernel>')
 
             # Replace raw_input. Note that is not sufficient to replace 
             # raw_input in the user namespace.
             raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
             __builtin__.raw_input = raw_input
 
             # Set the parent message of the display hook and out streams.
             sys.displayhook.set_parent(parent)
             sys.stdout.set_parent(parent)
             sys.stderr.set_parent(parent)
 
             exec comp_code in self.user_ns, self.user_ns
         except:
             etype, evalue, tb = sys.exc_info()
             tb = traceback.format_exception(etype, evalue, tb)
             exc_content = {
                 u'status' : u'error',
                 u'traceback' : tb,
                 u'ename' : unicode(etype.__name__),
                 u'evalue' : unicode(evalue)
             }
             exc_msg = self.session.msg(u'pyerr', exc_content, parent)
             self.pub_socket.send_json(exc_msg)
             reply_content = exc_content
         else:
             reply_content = { 'status' : 'ok', 'payload' : {} }
             
         # Flush output before sending the reply.
         sys.stderr.flush()
         sys.stdout.flush()
 
         # Send the reply.
         reply_msg = self.session.msg(u'execute_reply', reply_content, parent)
         print>>sys.__stdout__, Message(reply_msg)
         self.reply_socket.send(ident, zmq.SNDMORE)
         self.reply_socket.send_json(reply_msg)
         if reply_msg['content']['status'] == u'error':
             self._abort_queue()
 
     def complete_request(self, ident, parent):
         matches = {'matches' : self._complete(parent),
                    'status' : 'ok'}
         completion_msg = self.session.send(self.reply_socket, 'complete_reply',
                                            matches, parent, ident)
         print >> sys.__stdout__, completion_msg
 
     def object_info_request(self, ident, parent):
         context = parent['content']['oname'].split('.')
         object_info = self._object_info(context)
         msg = self.session.send(self.reply_socket, 'object_info_reply',
                                 object_info, parent, ident)
         print >> sys.__stdout__, msg
 
+    def shutdown_request(self, ident, parent):
+        content = dict(parent['content'])
+        msg = self.session.send(self.reply_socket, 'shutdown_reply',
+                                content, parent, ident)
+        msg = self.session.send(self.pub_socket, 'shutdown_reply',
+                                content, parent, ident)
+        print >> sys.__stdout__, msg
+        time.sleep(0.1)
+        sys.exit(0)
+
     #---------------------------------------------------------------------------
     # Protected interface
     #---------------------------------------------------------------------------
 
     def _abort_queue(self):
         while True:
             try:
                 ident = self.reply_socket.recv(zmq.NOBLOCK)
             except zmq.ZMQError, e:
                 if e.errno == zmq.EAGAIN:
                     break
             else:
                 assert self.reply_socket.rcvmore(), "Missing message part."
                 msg = self.reply_socket.recv_json()
             print>>sys.__stdout__, "Aborting:"
             print>>sys.__stdout__, Message(msg)
             msg_type = msg['msg_type']
             reply_type = msg_type.split('_')[0] + '_reply'
             reply_msg = self.session.msg(reply_type, {'status':'aborted'}, msg)
             print>>sys.__stdout__, Message(reply_msg)
             self.reply_socket.send(ident,zmq.SNDMORE)
             self.reply_socket.send_json(reply_msg)
             # We need to wait a bit for requests to come in. This can probably
             # be set shorter for true asynchronous clients.
             time.sleep(0.1)
 
     def _raw_input(self, prompt, ident, parent):
         # Flush output before making the request.
         sys.stderr.flush()
         sys.stdout.flush()
 
         # Send the input request.
         content = dict(prompt=prompt)
         msg = self.session.msg(u'input_request', content, parent)
         self.req_socket.send_json(msg)
 
         # Await a response.
         reply = self.req_socket.recv_json()
         try:
             value = reply['content']['value']
         except:
             print>>sys.__stderr__, "Got bad raw_input reply: "
             print>>sys.__stderr__, Message(parent)
             value = ''
         return value
 
     def _complete(self, msg):
         return self.completer.complete(msg.content.line, msg.content.text)
 
     def _object_info(self, context):
         symbol, leftover = self._symbol_from_context(context)
         if symbol is not None and not leftover:
             doc = getattr(symbol, '__doc__', '')
         else:
             doc = ''
         object_info = dict(docstring = doc)
         return object_info
 
     def _symbol_from_context(self, context):
         if not context:
             return None, context
 
         base_symbol_string = context[0]
         symbol = self.user_ns.get(base_symbol_string, None)
         if symbol is None:
             symbol = __builtin__.__dict__.get(base_symbol_string, None)
         if symbol is None:
             return None, context
 
         context = context[1:]
         for i, name in enumerate(context):
             new_symbol = getattr(symbol, name, None)
             if new_symbol is None:
                 return symbol, context[i:]
             else:
                 symbol = new_symbol
 
         return symbol, []
 
 #-----------------------------------------------------------------------------
 # Kernel main and launch functions
 #-----------------------------------------------------------------------------
 
 def launch_kernel(xrep_port=0, pub_port=0, req_port=0, hb_port=0,
                   independent=False):
     """ Launches a localhost kernel, binding to the specified ports.
 
     Parameters
     ----------
     xrep_port : int, optional
         The port to use for XREP channel.
 
     pub_port : int, optional
         The port to use for the SUB channel.
 
     req_port : int, optional
         The port to use for the REQ (raw input) channel.
 
     hb_port : int, optional
         The port to use for the hearbeat REP channel.
 
     independent : bool, optional (default False) 
         If set, the kernel process is guaranteed to survive if this process
         dies. If not set, an effort is made to ensure that the kernel is killed
         when this process dies. Note that in this case it is still good practice
         to kill kernels manually before exiting.
 
     Returns
     -------
     A tuple of form:
         (kernel_process, xrep_port, pub_port, req_port)
     where kernel_process is a Popen object and the ports are integers.
     """
     return base_launch_kernel('from IPython.zmq.pykernel import main; main()',
                               xrep_port, pub_port, req_port, hb_port,
                               independent)
 
 main = make_default_main(Kernel)
 
 if __name__ == '__main__':
     main()

docs/source/development/messaging.txt

@@ -1,871 +1,873 b''
 .. _messaging:
 
 ======================
  Messaging in IPython
 ======================
 
 
 Introduction
 ============
 
 This document explains the basic communications design and messaging
 specification for how the various IPython objects interact over a network
 transport.  The current implementation uses the ZeroMQ_ library for messaging
 within and between hosts.
 
 .. Note::
 
    This document should be considered the authoritative description of the
    IPython messaging protocol, and all developers are strongly encouraged to
    keep it updated as the implementation evolves, so that we have a single
    common reference for all protocol details.
    
 The basic design is explained in the following diagram:
 
 .. image:: frontend-kernel.png
    :width: 450px
    :alt: IPython kernel/frontend messaging architecture.
    :align: center
    :target: ../_images/frontend-kernel.png
 
 A single kernel can be simultaneously connected to one or more frontends.  The
 kernel has three sockets that serve the following functions:
 
 1. REQ: this socket is connected to a *single* frontend at a time, and it allows
    the kernel to request input from a frontend when :func:`raw_input` is called.
    The frontend holding the matching REP socket acts as a 'virtual keyboard'
    for the kernel while this communication is happening (illustrated in the
    figure by the black outline around the central keyboard).  In practice,
    frontends may display such kernel requests using a special input widget or
    otherwise indicating that the user is to type input for the kernel instead
    of normal commands in the frontend.
 
 2. XREP: this single sockets allows multiple incoming connections from
    frontends, and this is the socket where requests for code execution, object
    information, prompts, etc. are made to the kernel by any frontend.  The
    communication on this socket is a sequence of request/reply actions from
    each frontend and the kernel.
 
 3. PUB: this socket is the 'broadcast channel' where the kernel publishes all
    side effects (stdout, stderr, etc.) as well as the requests coming from any
    client over the XREP socket and its own requests on the REP socket.  There
    are a number of actions in Python which generate side effects: :func:`print`
    writes to ``sys.stdout``, errors generate tracebacks, etc.  Additionally, in
    a multi-client scenario, we want all frontends to be able to know what each
    other has sent to the kernel (this can be useful in collaborative scenarios,
    for example).  This socket allows both side effects and the information
    about communications taking place with one client over the XREQ/XREP channel
    to be made available to all clients in a uniform manner.
 
    All messages are tagged with enough information (details below) for clients
    to know which messages come from their own interaction with the kernel and
    which ones are from other clients, so they can display each type
    appropriately.
 
 The actual format of the messages allowed on each of these channels is
 specified below.  Messages are dicts of dicts with string keys and values that
 are reasonably representable in JSON.  Our current implementation uses JSON
 explicitly as its message format, but this shouldn't be considered a permanent
 feature.  As we've discovered that JSON has non-trivial performance issues due
 to excessive copying, we may in the future move to a pure pickle-based raw
 message format.  However, it should be possible to easily convert from the raw
 objects to JSON, since we may have non-python clients (e.g. a web frontend).
 As long as it's easy to make a JSON version of the objects that is a faithful
 representation of all the data, we can communicate with such clients.
 
 .. Note::
 
    Not all of these have yet been fully fleshed out, but the key ones are, see
    kernel and frontend files for actual implementation details.
 
    
 Python functional API
 =====================
 
 As messages are dicts, they map naturally to a ``func(**kw)`` call form.  We
 should develop, at a few key points, functional forms of all the requests that
 take arguments in this manner and automatically construct the necessary dict
 for sending.
 
 
 General Message Format
 ======================
 
 All messages send or received by any IPython process should have the following
 generic structure::
     
     {
       # The message header contains a pair of unique identifiers for the
       # originating session and the actual message id, in addition to the
       # username for the process that generated the message.  This is useful in
       # collaborative settings where multiple users may be interacting with the
       # same kernel simultaneously, so that frontends can label the various
       # messages in a meaningful way.
       'header' : { 'msg_id' : uuid,
                    'username' : str,
            'session' : uuid
          },
 
       # In a chain of messages, the header from the parent is copied so that
       # clients can track where messages come from.
       'parent_header' : dict,
 
       # All recognized message type strings are listed below.
       'msg_type' : str,
 
       # The actual content of the message must be a dict, whose structure
       # depends on the message type.x
       'content' : dict,
     }
 
 For each message type, the actual content will differ and all existing message
 types are specified in what follows of this document.
 
 
 Messages on the XREP/XREQ socket
 ================================
 
 .. _execute:
 
 Execute
 -------
 
 This message type is used by frontends to ask the kernel to execute code on
 behalf of the user, in a namespace reserved to the user's variables (and thus
 separate from the kernel's own internal code and variables).
 
 Message type: ``execute_request``::
 
     content = {
         # Source code to be executed by the kernel, one or more lines.
     'code' : str,
 
     # A boolean flag which, if True, signals the kernel to execute this
     # code as quietly as possible.  This means that the kernel will compile
     # the code witIPython/core/tests/h 'exec' instead of 'single' (so
     # sys.displayhook will not fire), and will *not*:
     #   - broadcast exceptions on the PUB socket
     #   - do any logging
     #   - populate any history
     #
     # The default is False.
     'silent' : bool,
 
     # A list of variable names from the user's namespace to be retrieved.  What
     # returns is a JSON string of the variable's repr(), not a python object.
     'user_variables' : list,
 
     # Similarly, a dict mapping names to expressions to be evaluated in the
     # user's dict.
     'user_expressions' : dict,
     }
 
 The ``code`` field contains a single string (possibly multiline).  The kernel
 is responsible for splitting this into one or more independent execution blocks
 and deciding whether to compile these in 'single' or 'exec' mode (see below for
 detailed execution semantics).
 
 The ``user_`` fields deserve a detailed explanation.  In the past, IPython had
 the notion of a prompt string that allowed arbitrary code to be evaluated, and
 this was put to good use by many in creating prompts that displayed system
 status, path information, and even more esoteric uses like remote instrument
 status aqcuired over the network.  But now that IPython has a clean separation
 between the kernel and the clients, the kernel has no prompt knowledge; prompts
 are a frontend-side feature, and it should be even possible for different
 frontends to display different prompts while interacting with the same kernel.
 
 The kernel now provides the ability to retrieve data from the user's namespace
 after the execution of the main ``code``, thanks to two fields in the
 ``execute_request`` message:
 
 - ``user_variables``: If only variables from the user's namespace are needed, a
   list of variable names can be passed and a dict with these names as keys and
   their :func:`repr()` as values will be returned.
 
 - ``user_expressions``: For more complex expressions that require function
   evaluations, a dict can be provided with string keys and arbitrary python
   expressions as values.  The return message will contain also a dict with the
   same keys and the :func:`repr()` of the evaluated expressions as value.
 
 With this information, frontends can display any status information they wish
 in the form that best suits each frontend (a status line, a popup, inline for a
 terminal, etc).
 
 .. Note::
 
    In order to obtain the current execution counter for the purposes of
    displaying input prompts, frontends simply make an execution request with an
    empty code string and ``silent=True``.
 
 Execution semantics
 ~~~~~~~~~~~~~~~~~~~
 
 When the silent flag is false, the execution of use code consists of the
 following phases (in silent mode, only the ``code`` field is executed):
 
 1. Run the ``pre_runcode_hook``.
 
 2. Execute the ``code`` field, see below for details.
 
 3. If #2 succeeds, compute ``user_variables`` and ``user_expressions`` are
    computed.  This ensures that any error in the latter don't harm the main
    code execution.
 
 4. Call any method registered with :meth:`register_post_execute`.
 
 .. warning::
 
    The API for running code before/after the main code block is likely to
    change soon.  Both the ``pre_runcode_hook`` and the
    :meth:`register_post_execute` are susceptible to modification, as we find a
    consistent model for both.
 
 To understand how the ``code`` field is executed, one must know that Python
 code can be compiled in one of three modes (controlled by the ``mode`` argument
 to the :func:`compile` builtin):
 
 *single*
   Valid for a single interactive statement (though the source can contain
   multiple lines, such as a for loop).  When compiled in this mode, the
   generated bytecode contains special instructions that trigger the calling of
   :func:`sys.displayhook` for any expression in the block that returns a value.
   This means that a single statement can actually produce multiple calls to
   :func:`sys.displayhook`, if for example it contains a loop where each
   iteration computes an unassigned expression would generate 10 calls::
 
       for i in range(10):
           i**2
 
 *exec*
   An arbitrary amount of source code, this is how modules are compiled.
   :func:`sys.displayhook` is *never* implicitly called.
 
 *eval*
   A single expression that returns a value.  :func:`sys.displayhook` is *never*
   implicitly called.
 
 
 The ``code`` field is split into individual blocks each of which is valid for
 execution in 'single' mode, and then:
 
 - If there is only a single block: it is executed in 'single' mode.
 
 - If there is more than one block:
 
   * if the last one is a single line long, run all but the last in 'exec' mode
     and the very last one in 'single' mode.  This makes it easy to type simple
     expressions at the end to see computed values.
 
   * if the last one is no more than two lines long, run all but the last in
     'exec' mode and the very last one in 'single' mode.  This makes it easy to
     type simple expressions at the end to see computed values.  - otherwise
     (last one is also multiline), run all in 'exec' mode
 
   * otherwise (last one is also multiline), run all in 'exec' mode as a single
     unit.
 
 Any error in retrieving the ``user_variables`` or evaluating the
 ``user_expressions`` will result in a simple error message in the return fields
 of the form::
 
    [ERROR] ExceptionType: Exception message
 
 The user can simply send the same variable name or expression for evaluation to
 see a regular traceback.
 
 Errors in any registered post_execute functions are also reported similarly,
 and the failing function is removed from the post_execution set so that it does
 not continue triggering failures.
 
 Upon completion of the execution request, the kernel *always* sends a reply,
 with a status code indicating what happened and additional data depending on
 the outcome.  See :ref:`below <execution_results>` for the possible return
 codes and associated data.
 
 
 Execution counter (old prompt number)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The kernel has a single, monotonically increasing counter of all execution
 requests that are made with ``silent=False``.  This counter is used to populate
 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
 display it in some form to the user, which will typically (but not necessarily)
 be done in the prompts.  The value of this counter will be returned as the
 ``execution_count`` field of all ``execute_reply`` messages.
 
 .. _execution_results:
 
 Execution results
 ~~~~~~~~~~~~~~~~~
     
 Message type: ``execute_reply``::
 
     content = {
       # One of: 'ok' OR 'error' OR 'abort'
       'status' : str,
 
       # The global kernel counter that increases by one with each non-silent
       # executed request.  This will typically be used by clients to display
       # prompt numbers to the user.  If the request was a silent one, this will
       # be the current value of the counter in the kernel.
       'execution_count' : int,
     }
 
 When status is 'ok', the following extra fields are present::
 
     {
       # The execution payload is a dict with string keys that may have been
       # produced by the code being executed.  It is retrieved by the kernel at
       # the end of the execution and sent back to the front end, which can take
       # action on it as needed.  See main text for further details.
       'payload' : dict,
 
       # Results for the user_variables and user_expressions.
       'user_variables' : dict,
       'user_expressions' : dict,
 
       # The kernel will often transform the input provided to it.  If the
       # '---->' transform had been applied, this is filled, otherwise it's the
       # empty string.  So transformations like magics don't appear here, only
       # autocall ones.
       'transformed_code' : str,
       }
 
 .. admonition:: Execution payloads
     
    The notion of an 'execution payload' is different from a return value of a
    given set of code, which normally is just displayed on the pyout stream
    through the PUB socket.  The idea of a payload is to allow special types of
    code, typically magics, to populate a data container in the IPython kernel
    that will be shipped back to the caller via this channel.  The kernel will
    have an API for this, probably something along the lines of::
 
        ip.exec_payload_add(key, value)
 
    though this API is still in the design stages.  The data returned in this
    payload will allow frontends to present special views of what just happened.
 
    
 When status is 'error', the following extra fields are present::
 
     {
       'exc_name' : str,   # Exception name, as a string
       'exc_value' : str,  # Exception value, as a string
 
       # The traceback will contain a list of frames, represented each as a
       # string.  For now we'll stick to the existing design of ultraTB, which
       # controls exception level of detail statefully.  But eventually we'll
       # want to grow into a model where more information is collected and
       # packed into the traceback object, with clients deciding how little or
       # how much of it to unpack.  But for now, let's start with a simple list
       # of strings, since that requires only minimal changes to ultratb as
       # written.
       'traceback' : list,
     }
 
 
 When status is 'abort', there are for now no additional data fields.  This
 happens when the kernel was interrupted by a signal.
 
 Kernel attribute access
 -----------------------
 
 .. warning::
 
    This part of the messaging spec is not actually implemented in the kernel
    yet.
  
 While this protocol does not specify full RPC access to arbitrary methods of
 the kernel object, the kernel does allow read (and in some cases write) access
 to certain attributes.
 
 The policy for which attributes can be read is: any attribute of the kernel, or
 its sub-objects, that belongs to a :class:`Configurable` object and has been
 declared at the class-level with Traits validation, is in principle accessible
 as long as its name does not begin with a leading underscore.  The attribute
 itself will have metadata indicating whether it allows remote read and/or write
 access.  The message spec follows for attribute read and write requests.
 
 Message type: ``getattr_request``::
 
     content = {
         # The (possibly dotted) name of the attribute
 	'name' : str,
     }
 
 When a ``getattr_request`` fails, there are two possible error types:
 
 - AttributeError: this type of error was raised when trying to access the
   given name by the kernel itself.  This means that the attribute likely
   doesn't exist.
 
 - AccessError: the attribute exists but its value is not readable remotely.
 
 
 Message type: ``getattr_reply``::
 
     content = {
         # One of ['ok', 'AttributeError', 'AccessError'].
         'status' : str,
 	# If status is 'ok', a JSON object.
 	'value' : object,
     }
 
 Message type: ``setattr_request``::
 
     content = {
         # The (possibly dotted) name of the attribute
 	'name' : str,
 	
 	# A JSON-encoded object, that will be validated by the Traits
 	# information in the kernel
 	'value' : object,
     }
 
 When a ``setattr_request`` fails, there are also two possible error types with
 similar meanings  as those of the ``getattr_request`` case, but for writing.
     
 Message type: ``setattr_reply``::
 
     content = {
         # One of ['ok', 'AttributeError', 'AccessError'].
         'status' : str,
     }
 
 
     
 Object information
 ------------------
 
 One of IPython's most used capabilities is the introspection of Python objects
 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
 (which in reality are shorthands for the ``%pinfo`` magic).  This is used often
 enough that it warrants an explicit message type, especially because frontends
 may want to get object information in response to user keystrokes (like Tab or
 F1) besides from the user explicitly typing code like ``x??``.
 
 Message type: ``object_info_request``::
 
     content = {
         # The (possibly dotted) name of the object to be searched in all
 	# relevant namespaces
         'name' : str,
 
     	# The level of detail desired.  The default (0) is equivalent to typing
 	# 'x?' at the prompt, 1 is equivalent to 'x??'.
 	'detail_level' : int,
     }
 
 The returned information will be a dictionary with keys very similar to the
 field names that IPython prints at the terminal.
     
 Message type: ``object_info_reply``::
 
     content = {
     # The name the object was requested under
     'name' : str,
     
     # Boolean flag indicating whether the named object was found or not.  If
     # it's false, all other fields will be empty.
     'found' : bool,
     
     # Flags for magics and system aliases
     'ismagic' : bool,
     'isalias' : bool,
 
     # The name of the namespace where the object was found ('builtin',
     # 'magics', 'alias', 'interactive', etc.)
     'namespace' : str,
 
     # The type name will be type.__name__ for normal Python objects, but it
     # can also be a string like 'Magic function' or 'System alias'
     'type_name' : str,
 
     'string_form' : str,
 
     # For objects with a __class__ attribute this will be set
     'base_class' : str,
 
     # For objects with a __len__ attribute this will be set
     'length' : int,
 
     # If the object is a function, class or method whose file we can find,
     # we give its full path
     'file' : str,
 
     # For pure Python callable objects, we can reconstruct the object
     # definition line which provides its call signature.  For convenience this
     # is returned as a single 'definition' field, but below the raw parts that
     # compose it are also returned as the argspec field.
     'definition' : str,
 
     # The individual parts that together form the definition string.  Clients
     # with rich display capabilities may use this to provide a richer and more
     # precise representation of the definition line (e.g. by highlighting
     # arguments based on the user's cursor position).  For non-callable
     # objects, this field is empty.
     'argspec' : { # The names of all the arguments
                   args : list,
 		  # The name of the varargs (*args), if any
                   varargs : str,
 		  # The name of the varkw (**kw), if any
 		  varkw : str,
 		  # The values (as strings) of all default arguments.  Note
 		  # that these must be matched *in reverse* with the 'args'
 		  # list above, since the first positional args have no default
 		  # value at all.
 		  defaults : list,
 		  },
 
     # For instances, provide the constructor signature (the definition of
     # the __init__ method):
     'init_definition' : str,
     
     # Docstrings: for any object (function, method, module, package) with a
     # docstring, we show it.  But in addition, we may provide additional
     # docstrings.  For example, for instances we will show the constructor
     # and class docstrings as well, if available.
     'docstring' : str,
 
     # For instances, provide the constructor and class docstrings
     'init_docstring' : str,
     'class_docstring' : str,
     
     # If it's a callable object whose call method has a separate docstring and
     # definition line:
     'call_def' : str,
     'call_docstring' : str,
     
     # If detail_level was 1, we also try to find the source code that
     # defines the object, if possible.  The string 'None' will indicate
     # that no source was found.
     'source' : str,
     }
 '
     
 Complete
 --------
 
 Message type: ``complete_request``::
 
     content = {
         # The text to be completed, such as 'a.is'
     'text' : str,
 
     # The full line, such as 'print a.is'.  This allows completers to
     # make decisions that may require information about more than just the
     # current word.
     'line' : str,
 
     # The entire block of text where the line is.  This may be useful in the
     # case of multiline completions where more context may be needed.  Note: if
     # in practice this field proves unnecessary, remove it to lighten the
     # messages.
     
     'block' : str,
 
     # The position of the cursor where the user hit 'TAB' on the line.
     'cursor_pos' : int,
     }
 
 Message type: ``complete_reply``::
 
     content = {
         # The list of all matches to the completion request, such as
     # ['a.isalnum', 'a.isalpha'] for the above example.
     'matches' : list
     }
 
     
 History
 -------
 
 For clients to explicitly request history from a kernel.  The kernel has all
 the actual execution history stored in a single location, so clients can
 request it from the kernel when needed.
 
 Message type: ``history_request``::
 
     content = {
     
       # If True, also return output history in the resulting dict.
       'output' : bool,
 
       # If True, return the raw input history, else the transformed input.
       'raw' : bool,
 
       # This parameter can be one of: A number,  a pair of numbers, None
       # If not given, last 40 are returned.
       #  - number n: return the last n entries.
       #  - pair n1, n2: return entries in the range(n1, n2).
       #  - None: return all history
       'index' : n or (n1, n2) or None,
     }
 
 Message type: ``history_reply``::
 
     content = {
       # A dict with prompt numbers as keys and either (input, output) or input
       # as the value depending on whether output was True or False,
       # respectively.
       'history' : dict,
     }
 
 
 Connect
 -------
 
 When a client connects to the request/reply socket of the kernel, it can issue
 a connect request to get basic information about the kernel, such as the ports
 the other ZeroMQ sockets are listening on. This allows clients to only have
 to know about a single port (the XREQ/XREP channel) to connect to a kernel.
 
 Message type: ``connect_request``::
 
     content = {
     }
 
 Message type: ``connect_reply``::
 
     content = {
         'xrep_port' : int  # The port the XREP socket is listening on.
         'pub_port' : int   # The port the PUB socket is listening on.
         'req_port' : int   # The port the REQ socket is listening on.
         'hb_port' : int    # The port the heartbeat socket is listening on.
     }
 
 
 
 Kernel shutdown
 ---------------
 
 The clients can request the kernel to shut itself down; this is used in
 multiple cases:
 
 - when the user chooses to close the client application via a menu or window
   control.
 - when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
 - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
   IPythonQt client) to force a kernel restart to get a clean kernel without
   losing client-side state like history or inlined figures.
 
 The client sends a shutdown request to the kernel, and once it receives the
 reply message (which is otherwise empty), it can assume that the kernel has
 completed shutdown safely.
 
 Upon their own shutdown, client applications will typically execute a last
 minute sanity check and forcefully terminate any kernel that is still alive, to
 avoid leaving stray processes in the user's machine.
 
 For both shutdown request and reply, there is no actual content that needs to
 be sent, so the content dict is empty.
 
 Message type: ``shutdown_request``::
 
     content = {
+        'restart' : bool # whether the shutdown is final, or precedes a restart
     }
 
 Message type: ``shutdown_reply``::
 
     content = {
+        'restart' : bool # whether the shutdown is final, or precedes a restart
     }
 
 .. Note::
 
    When the clients detect a dead kernel thanks to inactivity on the heartbeat
    socket, they simply send a forceful process termination signal, since a dead
    process is unlikely to respond in any useful way to messages.
     
 
 Messages on the PUB/SUB socket
 ==============================
 
 Streams (stdout,  stderr, etc)
 ------------------------------
 
 Message type: ``stream``::
 
     content = {
         # The name of the stream is one of 'stdin', 'stdout', 'stderr'
     'name' : str,
     
     # The data is an arbitrary string to be written to that stream
     'data' : str,
     }
 
 When a kernel receives a raw_input call, it should also broadcast it on the pub
 socket with the names 'stdin' and 'stdin_reply'.  This will allow other clients
 to monitor/display kernel interactions and possibly replay them to their user
 or otherwise expose them.
 
 Python inputs
 -------------
 
 These messages are the re-broadcast of the ``execute_request``.
 
 Message type: ``pyin``::
 
     content = {
         # Source code to be executed, one or more lines
     'code' : str
     }
 
 Python outputs
 --------------
 
 When Python produces output from code that has been compiled in with the
 'single' flag to :func:`compile`, any expression that produces a value (such as
 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
 this value whatever it wants.  The default behavior of ``sys.displayhook`` in
 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
 the value as long as it is not ``None`` (which isn't printed at all).  In our
 case, the kernel instantiates as ``sys.displayhook`` an object which has
 similar behavior, but which instead of printing to stdout, broadcasts these
 values as ``pyout`` messages for clients to display appropriately.
 
 Message type: ``pyout``::
 
     content = {
         # The data is typically the repr() of the object.
     'data' : str,
     
     # The counter for this execution is also provided so that clients can
     # display it, since IPython automatically creates variables called _N (for
     # prompt N).
     'execution_count' : int,
     }
     
 Python errors
 -------------
 
 When an error occurs during code execution
 
 Message type: ``pyerr``::
 
     content = {
        # Similar content to the execute_reply messages for the 'error' case,
        # except the 'status' field is omitted.
     }
 
 Kernel status
 -------------
 
 This message type is used by frontends to monitor the status of the kernel.
 
 Message type: ``status``::
 
     content = {
         # When the kernel starts to execute code, it will enter the 'busy'
         # state and when it finishes, it will enter the 'idle' state.
         execution_state : ('busy', 'idle')
     }
 
 Kernel crashes
 --------------
 
 When the kernel has an unexpected exception, caught by the last-resort
 sys.excepthook, we should broadcast the crash handler's output before exiting.
 This will allow clients to notice that a kernel died, inform the user and
 propose further actions.
 
 Message type: ``crash``::
 
     content = {
        # Similarly to the 'error' case for execute_reply messages, this will
        # contain exc_name, exc_type and traceback fields.
 
        # An additional field with supplementary information such as where to
        # send the crash message
        'info' : str,
     }
 
 
 Future ideas
 ------------
     
 Other potential message types, currently unimplemented, listed below as ideas.
     
 Message type: ``file``::
 
     content = {
     'path' : 'cool.jpg',
     'mimetype' : str,
     'data' : str,
     }
 
     
 Messages on the REQ/REP socket
 ==============================
 
 This is a socket that goes in the opposite direction: from the kernel to a
 *single* frontend, and its purpose is to allow ``raw_input`` and similar
 operations that read from ``sys.stdin`` on the kernel to be fulfilled by the
 client.  For now we will keep these messages as simple as possible, since they
 basically only mean to convey the ``raw_input(prompt)`` call.
 
 Message type: ``input_request``::
 
     content = { 'prompt' : str }
 
 Message type: ``input_reply``::
 
     content = { 'value' : str }
     
 .. Note::
 
    We do not explicitly try to forward the raw ``sys.stdin`` object, because in
    practice the kernel should behave like an interactive program.  When a
    program is opened on the console, the keyboard effectively takes over the
    ``stdin`` file descriptor, and it can't be used for raw reading anymore.
    Since the IPython kernel effectively behaves like a console program (albeit
    one whose "keyboard" is actually living in a separate process and
    transported over the zmq connection), raw ``stdin`` isn't expected to be
    available.
 
    
 Heartbeat for kernels
 =====================
 
 Initially we had considered using messages like those above over ZMQ for a
 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
 alive at all, even if it may be busy executing user code).  But this has the
 problem that if the kernel is locked inside extension code, it wouldn't execute
 the python heartbeat code.  But it turns out that we can implement a basic
 heartbeat with pure ZMQ, without using any Python messaging at all.
 
 The monitor sends out a single zmq message (right now, it is a str of the
 monitor's lifetime in seconds), and gets the same message right back, prefixed
 with the zmq identity of the XREQ socket in the heartbeat process. This can be
 a uuid, or even a full message, but there doesn't seem to be a need for packing
 up a message when the sender and receiver are the exact same Python object.
 
 The model is this::
 
     monitor.send(str(self.lifetime)) # '1.2345678910'
 
 and the monitor receives some number of messages of the form::
 
     ['uuid-abcd-dead-beef', '1.2345678910']
 
 where the first part is the zmq.IDENTITY of the heart's XREQ on the engine, and
 the rest is the message sent by the monitor.  No Python code ever has any
 access to the message between the monitor's send, and the monitor's recv.
 
 
 ToDo
 ====
 
 Missing things include:
 
 * Important: finish thinking through the payload concept and API.
 
 * Important: ensure that we have a good solution for magics like %edit.  It's
   likely that with the payload concept we can build a full solution, but not
   100% clear yet.
 
 * Finishing the details of the heartbeat protocol.
 
 * Signal handling: specify what kind of information kernel should broadcast (or
   not) when it receives signals.
 
 .. include:: ../links.rst