updates per review

- two-part protocol version (5.0)
- default value for cursor_pos is end of code
- docs, comment, and docstring touchups

IPython/core/page.py

@@ -1,357 +1,360 b''
 # encoding: utf-8
 """
 Paging capabilities for IPython.core
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 
 Notes
 -----
 
 For now this uses ipapi, so it can't be in IPython.utils.  If we can get
 rid of that dependency, we could move it there.
 -----
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  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
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 import os
 import re
 import sys
 import tempfile
 
 from io import UnsupportedOperation
 
 from IPython import get_ipython
 from IPython.core.error import TryNext
 from IPython.utils.data import chop
 from IPython.utils import io
 from IPython.utils.process import system
 from IPython.utils.terminal import get_terminal_size
 from IPython.utils import py3compat
 
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 esc_re = re.compile(r"(\x1b[^m]+m)")
 
 def page_dumb(strng, start=0, screen_lines=25):
     """Very dumb 'pager' in Python, for when nothing else works.
 
     Only moves forward, same interface as page(), except for pager_cmd and
     mode."""
 
     out_ln  = strng.splitlines()[start:]
     screens = chop(out_ln,screen_lines-1)
     if len(screens) == 1:
         print(os.linesep.join(screens[0]), file=io.stdout)
     else:
         last_escape = ""
         for scr in screens[0:-1]:
             hunk = os.linesep.join(scr)
             print(last_escape + hunk, file=io.stdout)
             if not page_more():
                 return
             esc_list = esc_re.findall(hunk)
             if len(esc_list) > 0:
                 last_escape = esc_list[-1]
         print(last_escape + os.linesep.join(screens[-1]), file=io.stdout)
 
 def _detect_screen_size(screen_lines_def):
     """Attempt to work out the number of lines on the screen.
 
     This is called by page(). It can raise an error (e.g. when run in the
     test suite), so it's separated out so it can easily be called in a try block.
     """
     TERM = os.environ.get('TERM',None)
     if not((TERM=='xterm' or TERM=='xterm-color') and sys.platform != 'sunos5'):
         # curses causes problems on many terminals other than xterm, and
         # some termios calls lock up on Sun OS5.
         return screen_lines_def
     
     try:
         import termios
         import curses
     except ImportError:
         return screen_lines_def
     
     # There is a bug in curses, where *sometimes* it fails to properly
     # initialize, and then after the endwin() call is made, the
     # terminal is left in an unusable state.  Rather than trying to
     # check everytime for this (by requesting and comparing termios
     # flags each time), we just save the initial terminal state and
     # unconditionally reset it every time.  It's cheaper than making
     # the checks.
     term_flags = termios.tcgetattr(sys.stdout)
 
     # Curses modifies the stdout buffer size by default, which messes
     # up Python's normal stdout buffering.  This would manifest itself
     # to IPython users as delayed printing on stdout after having used
     # the pager.
     #
     # We can prevent this by manually setting the NCURSES_NO_SETBUF
     # environment variable.  For more details, see:
     # http://bugs.python.org/issue10144
     NCURSES_NO_SETBUF = os.environ.get('NCURSES_NO_SETBUF', None)
     os.environ['NCURSES_NO_SETBUF'] = ''
 
     # Proceed with curses initialization
     try:
         scr = curses.initscr()
     except AttributeError:
         # Curses on Solaris may not be complete, so we can't use it there
         return screen_lines_def
     
     screen_lines_real,screen_cols = scr.getmaxyx()
     curses.endwin()
 
     # Restore environment
     if NCURSES_NO_SETBUF is None:
         del os.environ['NCURSES_NO_SETBUF']
     else:
         os.environ['NCURSES_NO_SETBUF'] = NCURSES_NO_SETBUF
 
     # Restore terminal state in case endwin() didn't.
     termios.tcsetattr(sys.stdout,termios.TCSANOW,term_flags)
     # Now we have what we needed: the screen size in rows/columns
     return screen_lines_real
     #print '***Screen size:',screen_lines_real,'lines x',\
     #screen_cols,'columns.' # dbg
 
 def page(strng, start=0, screen_lines=0, pager_cmd=None):
-    """Print a string, piping through a pager after a certain length.
+    """Display a string, piping through a pager after a certain length.
+    
+    strng can be a mime-bundle dict, supplying multiple representations,
+    keyed by mime-type.
 
     The screen_lines parameter specifies the number of *usable* lines of your
     terminal screen (total lines minus lines you need to reserve to show other
     information).
 
     If you set screen_lines to a number <=0, page() will try to auto-determine
     your screen size and will only use up to (screen_size+screen_lines) for
     printing, paging after that. That is, if you want auto-detection but need
     to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
     auto-detection without any lines reserved simply use screen_lines = 0.
 
     If a string won't fit in the allowed lines, it is sent through the
     specified pager command. If none given, look for PAGER in the environment,
     and ultimately default to less.
 
     If no system pager works, the string is sent through a 'dumb pager'
     written in python, very simplistic.
     """
     
     # for compatibility with mime-bundle form:
     if isinstance(strng, dict):
         strng = strng['text/plain']
 
     # Some routines may auto-compute start offsets incorrectly and pass a
     # negative value.  Offset to 0 for robustness.
     start = max(0, start)
 
     # first, try the hook
     ip = get_ipython()
     if ip:
         try:
             ip.hooks.show_in_pager(strng)
             return
         except TryNext:
             pass
 
     # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
     TERM = os.environ.get('TERM','dumb')
     if TERM in ['dumb','emacs'] and os.name != 'nt':
         print(strng)
         return
     # chop off the topmost part of the string we don't want to see
     str_lines = strng.splitlines()[start:]
     str_toprint = os.linesep.join(str_lines)
     num_newlines = len(str_lines)
     len_str = len(str_toprint)
 
     # Dumb heuristics to guesstimate number of on-screen lines the string
     # takes.  Very basic, but good enough for docstrings in reasonable
     # terminals. If someone later feels like refining it, it's not hard.
     numlines = max(num_newlines,int(len_str/80)+1)
 
     screen_lines_def = get_terminal_size()[1]
 
     # auto-determine screen size
     if screen_lines <= 0:
         try:
             screen_lines += _detect_screen_size(screen_lines_def)
         except (TypeError, UnsupportedOperation):
             print(str_toprint, file=io.stdout)
             return
 
     #print 'numlines',numlines,'screenlines',screen_lines  # dbg
     if numlines <= screen_lines :
         #print '*** normal print'  # dbg
         print(str_toprint, file=io.stdout)
     else:
         # Try to open pager and default to internal one if that fails.
         # All failure modes are tagged as 'retval=1', to match the return
         # value of a failed system command.  If any intermediate attempt
         # sets retval to 1, at the end we resort to our own page_dumb() pager.
         pager_cmd = get_pager_cmd(pager_cmd)
         pager_cmd += ' ' + get_pager_start(pager_cmd,start)
         if os.name == 'nt':
             if pager_cmd.startswith('type'):
                 # The default WinXP 'type' command is failing on complex strings.
                 retval = 1
             else:
                 fd, tmpname = tempfile.mkstemp('.txt')
                 try:
                     os.close(fd)
                     with open(tmpname, 'wt') as tmpfile:
                         tmpfile.write(strng)
                         cmd = "%s < %s" % (pager_cmd, tmpname)
                     # tmpfile needs to be closed for windows
                     if os.system(cmd):
                         retval = 1
                     else:
                         retval = None
                 finally:
                     os.remove(tmpname)
         else:
             try:
                 retval = None
                 # if I use popen4, things hang. No idea why.
                 #pager,shell_out = os.popen4(pager_cmd)
                 pager = os.popen(pager_cmd, 'w')
                 try:
                     pager_encoding = pager.encoding or sys.stdout.encoding
                     pager.write(py3compat.cast_bytes_py2(
                         strng, encoding=pager_encoding))
                 finally:
                     retval = pager.close()
             except IOError as msg:  # broken pipe when user quits
                 if msg.args == (32, 'Broken pipe'):
                     retval = None
                 else:
                     retval = 1
             except OSError:
                 # Other strange problems, sometimes seen in Win2k/cygwin
                 retval = 1
         if retval is not None:
             page_dumb(strng,screen_lines=screen_lines)
 
 
 def page_file(fname, start=0, pager_cmd=None):
     """Page a file, using an optional pager command and starting line.
     """
 
     pager_cmd = get_pager_cmd(pager_cmd)
     pager_cmd += ' ' + get_pager_start(pager_cmd,start)
 
     try:
         if os.environ['TERM'] in ['emacs','dumb']:
             raise EnvironmentError
         system(pager_cmd + ' ' + fname)
     except:
         try:
             if start > 0:
                 start -= 1
             page(open(fname).read(),start)
         except:
             print('Unable to show file',repr(fname))
 
 
 def get_pager_cmd(pager_cmd=None):
     """Return a pager command.
 
     Makes some attempts at finding an OS-correct one.
     """
     if os.name == 'posix':
         default_pager_cmd = 'less -r'  # -r for color control sequences
     elif os.name in ['nt','dos']:
         default_pager_cmd = 'type'
 
     if pager_cmd is None:
         try:
             pager_cmd = os.environ['PAGER']
         except:
             pager_cmd = default_pager_cmd
     return pager_cmd
 
 
 def get_pager_start(pager, start):
     """Return the string for paging files with an offset.
 
     This is the '+N' argument which less and more (under Unix) accept.
     """
 
     if pager in ['less','more']:
         if start:
             start_string = '+' + str(start)
         else:
             start_string = ''
     else:
         start_string = ''
     return start_string
 
 
 # (X)emacs on win32 doesn't like to be bypassed with msvcrt.getch()
 if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs':
     import msvcrt
     def page_more():
         """ Smart pausing between pages
 
         @return:    True if need print more lines, False if quit
         """
         io.stdout.write('---Return to continue, q to quit--- ')
         ans = msvcrt.getwch()
         if ans in ("q", "Q"):
             result = False
         else:
             result = True
         io.stdout.write("\b"*37 + " "*37 + "\b"*37)
         return result
 else:
     def page_more():
         ans = py3compat.input('---Return to continue, q to quit--- ')
         if ans.lower().startswith('q'):
             return False
         else:
             return True
 
 
 def snip_print(str,width = 75,print_full = 0,header = ''):
     """Print a string snipping the midsection to fit in width.
 
     print_full: mode control:
     
       - 0: only snip long strings
       - 1: send to page() directly.
       - 2: snip long strings and ask for full length viewing with page()
     
     Return 1 if snipping was necessary, 0 otherwise."""
 
     if print_full == 1:
         page(header+str)
         return 0
 
     print(header, end=' ')
     if len(str) < width:
         print(str)
         snip = 0
     else:
         whalf = int((width -5)/2)
         print(str[:whalf] + ' <...> ' + str[-whalf:])
         snip = 1
     if snip and print_full == 2:
         if py3compat.input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
             page(str)
     return snip

IPython/core/release.py

@@ -1,150 +1,150 b''
 # -*- coding: utf-8 -*-
 """Release data for the IPython project."""
 
 #-----------------------------------------------------------------------------
 #  Copyright (c) 2008, IPython Development Team.
 #  Copyright (c) 2001, Fernando Perez <[e-mail]>
 #  Copyright (c) 2001, Janko Hauser <[e-mail]>
 #  Copyright (c) 2001, Nathaniel Gray <[e-mail]>
 #
 #  Distributed under the terms of the Modified BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 # Name of the package for release purposes.  This is the name which labels
 # the tarballs and RPMs made by distutils, so it's best to lowercase it.
 name = 'ipython'
 
 # IPython version information.  An empty _version_extra corresponds to a full
 # release.  'dev' as a _version_extra string means this is a development
 # version
 _version_major = 3
 _version_minor = 0
 _version_patch = 0
 _version_extra = 'dev'
 # _version_extra = 'rc1'
 # _version_extra = ''  # Uncomment this for full releases
 
 # release.codename is deprecated in 2.0, will be removed in 3.0
 codename = ''
 
 # Construct full version string from these.
 _ver = [_version_major, _version_minor, _version_patch]
 
 __version__ = '.'.join(map(str, _ver))
 if _version_extra:
     __version__ = __version__ + '-' + _version_extra
 
 version = __version__  # backwards compatibility name
 version_info = (_version_major, _version_minor, _version_patch, _version_extra)
 
 # Change this when incrementing the kernel protocol version
-kernel_protocol_version_info = (5, 0, 0)
-kernel_protocol_version = "%i.%i.%i" % kernel_protocol_version_info
+kernel_protocol_version_info = (5, 0)
+kernel_protocol_version = "%i.%i" % kernel_protocol_version_info
 
 description = "IPython: Productive Interactive Computing"
 
 long_description = \
 """
 IPython provides a rich toolkit to help you make the most out of using Python
 interactively.  Its main components are:
 
 * Powerful interactive Python shells (terminal- and Qt-based).
 * A web-based interactive notebook environment with all shell features plus
   support for embedded figures, animations and rich media.
 * Support for interactive data visualization and use of GUI toolkits.
 * Flexible, embeddable interpreters to load into your own projects.
 * A high-performance library for high level and interactive parallel computing
   that works in multicore systems, clusters, supercomputing and cloud scenarios.
 
 The enhanced interactive Python shells have the following main features:
 
 * Comprehensive object introspection.
 
 * Input history, persistent across sessions.
 
 * Caching of output results during a session with automatically generated
   references.
 
 * Extensible tab completion, with support by default for completion of python
   variables and keywords, filenames and function keywords.
 
 * Extensible system of 'magic' commands for controlling the environment and
   performing many tasks related either to IPython or the operating system.
 
 * A rich configuration system with easy switching between different setups
   (simpler than changing $PYTHONSTARTUP environment variables every time).
 
 * Session logging and reloading.
 
 * Extensible syntax processing for special purpose situations.
 
 * Access to the system shell with user-extensible alias system.
 
 * Easily embeddable in other Python programs and GUIs.
 
 * Integrated access to the pdb debugger and the Python profiler.
 
 The parallel computing architecture has the following main features:
 
 * Quickly parallelize Python code from an interactive Python/IPython session.
 
 * A flexible and dynamic process model that be deployed on anything from
   multicore workstations to supercomputers.
 
 * An architecture that supports many different styles of parallelism, from
   message passing to task farming.
 
 * Both blocking and fully asynchronous interfaces.
 
 * High level APIs that enable many things to be parallelized in a few lines
   of code.
 
 * Share live parallel jobs with other users securely.
 
 * Dynamically load balanced task farming system.
 
 * Robust error handling in parallel code.
 
 The latest development version is always available from IPython's `GitHub
 site <http://github.com/ipython>`_.
 """
 
 license = 'BSD'
 
 authors = {'Fernando' : ('Fernando Perez','[e-mail]'),
            'Janko'    : ('Janko Hauser','[e-mail]'),
            'Nathan'   : ('Nathaniel Gray','[e-mail]'),
            'Ville'    : ('Ville Vainio','[e-mail]'),
            'Brian'    : ('Brian E Granger', '[e-mail]'),
            'Min'      : ('Min Ragan-Kelley', '[e-mail]'),
            'Thomas'   : ('Thomas A. Kluyver', '[e-mail]'),
            'Jorgen'   : ('Jorgen Stenarson', '[e-mail]'),
            'Matthias' : ('Matthias Bussonnier', '[e-mail]'),
            }
 
 author = 'The IPython Development Team'
 
 author_email = '[e-mail]'
 
 url = 'http://ipython.org'
 
 download_url = 'https://github.com/ipython/ipython/downloads'
 
 platforms = ['Linux','Mac OSX','Windows XP/Vista/7/8']
 
 keywords = ['Interactive','Interpreter','Shell','Parallel','Distributed',
             'Web-based computing', 'Qt console', 'Embedding']
 
 classifiers = [
     'Intended Audience :: Developers',
     'Intended Audience :: Science/Research',
     'License :: OSI Approved :: BSD License',
     'Programming Language :: Python',
     'Programming Language :: Python :: 2',
     'Programming Language :: Python :: 2.7',
     'Programming Language :: Python :: 3',
     'Topic :: System :: Distributed Computing',
     'Topic :: System :: Shells'
     ]

IPython/html/static/notebook/js/tooltip.js

@@ -1,350 +1,345 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 //============================================================================
 // Tooltip
 //============================================================================
 //
 // you can set the autocall time by setting `IPython.tooltip.time_before_tooltip` in ms
 //
 // you can configure the differents action of pressing shift-tab several times in a row by
 // setting/appending different fonction in the array
 // IPython.tooltip.tabs_functions
 //
 // eg :
 // IPython.tooltip.tabs_functions[4] = function (){console.log('this is the action of the 4th tab pressing')}
 //
 var IPython = (function (IPython) {
     "use strict";
 
     var utils = IPython.utils;
 
     // tooltip constructor
     var Tooltip = function () {
             var that = this;
             this.time_before_tooltip = 1200;
 
             // handle to html
             this.tooltip = $('#tooltip');
             this._hidden = true;
 
             // variable for consecutive call
             this._old_cell = null;
             this._old_request = null;
             this._consecutive_counter = 0;
 
             // 'sticky ?'
             this._sticky = false;
 
             // display tooltip if the docstring is empty?
             this._hide_if_no_docstring = false;
 
             // contain the button in the upper right corner
             this.buttons = $('<div/>').addClass('tooltipbuttons');
 
             // will contain the docstring
             this.text = $('<div/>').addClass('tooltiptext').addClass('smalltooltip');
 
             // build the buttons menu on the upper right
             // expand the tooltip to see more
             var expandlink = $('<a/>').attr('href', "#").addClass("ui-corner-all") //rounded corner
             .attr('role', "button").attr('id', 'expanbutton').attr('title', 'Grow the tooltip vertically (press shift-tab twice)').click(function () {
                 that.expand();
             }).append(
             $('<span/>').text('Expand').addClass('ui-icon').addClass('ui-icon-plus'));
 
             // open in pager
             var morelink = $('<a/>').attr('href', "#").attr('role', "button").addClass('ui-button').attr('title', 'show the current docstring in pager (press shift-tab 4 times)');
             var morespan = $('<span/>').text('Open in Pager').addClass('ui-icon').addClass('ui-icon-arrowstop-l-n');
             morelink.append(morespan);
             morelink.click(function () {
                 that.showInPager(that._old_cell);
             });
 
             // close the tooltip
             var closelink = $('<a/>').attr('href', "#").attr('role', "button").addClass('ui-button');
             var closespan = $('<span/>').text('Close').addClass('ui-icon').addClass('ui-icon-close');
             closelink.append(closespan);
             closelink.click(function () {
                 that.remove_and_cancel_tooltip(true);
             });
 
             this._clocklink = $('<a/>').attr('href', "#");
             this._clocklink.attr('role', "button");
             this._clocklink.addClass('ui-button');
             this._clocklink.attr('title', 'Tootip is not dismissed while typing for 10 seconds');
             var clockspan = $('<span/>').text('Close');
             clockspan.addClass('ui-icon');
             clockspan.addClass('ui-icon-clock');
             this._clocklink.append(clockspan);
             this._clocklink.click(function () {
                 that.cancel_stick();
             });
 
 
 
 
             //construct the tooltip
             // add in the reverse order you want them to appear
             this.buttons.append(closelink);
             this.buttons.append(expandlink);
             this.buttons.append(morelink);
             this.buttons.append(this._clocklink);
             this._clocklink.hide();
 
 
             // we need a phony element to make the small arrow
             // of the tooltip in css
             // we will move the arrow later
             this.arrow = $('<div/>').addClass('pretooltiparrow');
             this.tooltip.append(this.buttons);
             this.tooltip.append(this.arrow);
             this.tooltip.append(this.text);
 
             // function that will be called if you press tab 1, 2, 3... times in a row
             this.tabs_functions = [function (cell, text, cursor) {
                 that._request_tooltip(cell, text, cursor);
             }, function () {
                 that.expand();
             }, function () {
                 that.stick();
             }, function (cell) {
                 that.cancel_stick();
                 that.showInPager(cell);
             }];
             // call after all the tabs function above have bee call to clean their effects
             // if necessary
             this.reset_tabs_function = function (cell, text) {
                 this._old_cell = (cell) ? cell : null;
                 this._old_request = (text) ? text : null;
                 this._consecutive_counter = 0;
             };
         };
 
     Tooltip.prototype.is_visible = function () {
         return !this._hidden;
     };
 
     Tooltip.prototype.showInPager = function (cell) {
         // reexecute last call in pager by appending ? to show back in pager
         var that = this;
         var payload = {};
         payload.text = that._reply.content.data['text/plain'];
         
         $([IPython.events]).trigger('open_with_text.Pager', payload);
         this.remove_and_cancel_tooltip();
     };
 
     // grow the tooltip verticaly
     Tooltip.prototype.expand = function () {
         this.text.removeClass('smalltooltip');
         this.text.addClass('bigtooltip');
         $('#expanbutton').hide('slow');
     };
 
     // deal with all the logic of hiding the tooltip
     // and reset it's status
     Tooltip.prototype._hide = function () {
         this._hidden = true;
         this.tooltip.fadeOut('fast');
         $('#expanbutton').show('slow');
         this.text.removeClass('bigtooltip');
         this.text.addClass('smalltooltip');
         // keep scroll top to be sure to always see the first line
         this.text.scrollTop(0);
         this.code_mirror = null;
     };
 
     // return true on successfully removing a visible tooltip; otherwise return
     // false.
     Tooltip.prototype.remove_and_cancel_tooltip = function (force) {
         // note that we don't handle closing directly inside the calltip
         // as in the completer, because it is not focusable, so won't
         // get the event.
         this.cancel_pending();
         if (!this._hidden) {
           if (force || !this._sticky) {
               this.cancel_stick();
               this._hide();
           }
           this.reset_tabs_function();
           return true;
         } else {
           return false;
         }
     };
 
     // cancel autocall done after '(' for example.
     Tooltip.prototype.cancel_pending = function () {
         if (this._tooltip_timeout !== null) {
             clearTimeout(this._tooltip_timeout);
             this._tooltip_timeout = null;
         }
     };
 
     // will trigger tooltip after timeout
     Tooltip.prototype.pending = function (cell, hide_if_no_docstring) {
         var that = this;
         this._tooltip_timeout = setTimeout(function () {
             that.request(cell, hide_if_no_docstring);
         }, that.time_before_tooltip);
     };
 
     // easy access for julia monkey patching.
     Tooltip.last_token_re = /[a-z_][0-9a-z._]*$/gi;
 
     Tooltip.prototype.extract_oir_token = function(line){
         // use internally just to make the request to the kernel
         // Feel free to shorten this logic if you are better
         // than me in regEx
         // basicaly you shoul be able to get xxx.xxx.xxx from
         // something(range(10), kwarg=smth) ; xxx.xxx.xxx( firstarg, rand(234,23), kwarg1=2,
         // remove everything between matchin bracket (need to iterate)
         var matchBracket = /\([^\(\)]+\)/g;
         var endBracket = /\([^\(]*$/g;
         var oldline = line;
 
         line = line.replace(matchBracket, "");
         while (oldline != line) {
             oldline = line;
             line = line.replace(matchBracket, "");
         }
         // remove everything after last open bracket
         line = line.replace(endBracket, "");
         // reset the regex object
         Tooltip.last_token_re.lastIndex = 0;
         return Tooltip.last_token_re.exec(line);
     };
 
     Tooltip.prototype._request_tooltip = function (cell, text, cursor_pos) {
         var callbacks = $.proxy(this._show, this);
         var msg_id = cell.kernel.inspect(text, cursor_pos, callbacks);
     };
 
     // make an imediate completion request
     Tooltip.prototype.request = function (cell, hide_if_no_docstring) {
         // request(codecell)
         // Deal with extracting the text from the cell and counting
         // call in a row
         this.cancel_pending();
         var editor = cell.code_mirror;
         var cursor = editor.getCursor();
         var cursor_pos = utils.to_absolute_cursor_pos(editor, cursor);
         var text = cell.get_text();
 
         this._hide_if_no_docstring = hide_if_no_docstring;
 
         if(editor.somethingSelected()){
             text = editor.getSelection();
         }
 
         // need a permanent handel to code_mirror for future auto recall
         this.code_mirror = editor;
 
         // now we treat the different number of keypress
         // first if same cell, same text, increment counter by 1
         if (this._old_cell == cell && this._old_request == text && this._hidden === false) {
             this._consecutive_counter++;
         } else {
             // else reset
             this.cancel_stick();
             this.reset_tabs_function (cell, text);
         }
 
-        // don't do anything if line begins with '(' or is empty
-        // if (text === "" || text === "(") {
-        //     return;
-        // }
-
         this.tabs_functions[this._consecutive_counter](cell, text, cursor_pos);
 
         // then if we are at the end of list function, reset
         if (this._consecutive_counter == this.tabs_functions.length) {
             this.reset_tabs_function (cell, text, cursor);
         }
 
         return;
     };
 
     // cancel the option of having the tooltip to stick
     Tooltip.prototype.cancel_stick = function () {
         clearTimeout(this._stick_timeout);
         this._stick_timeout = null;
         this._clocklink.hide('slow');
         this._sticky = false;
     };
 
     // put the tooltip in a sicky state for 10 seconds
     // it won't be removed by remove_and_cancell() unless you called with
     // the first parameter set to true.
     // remove_and_cancell_tooltip(true)
     Tooltip.prototype.stick = function (time) {
         time = (time !== undefined) ? time : 10;
         var that = this;
         this._sticky = true;
         this._clocklink.show('slow');
         this._stick_timeout = setTimeout(function () {
             that._sticky = false;
             that._clocklink.hide('slow');
         }, time * 1000);
     };
 
     // should be called with the kernel reply to actually show the tooltip
     Tooltip.prototype._show = function (reply) {
         // move the bubble if it is not hidden
         // otherwise fade it
         this._reply = reply;
         var content = reply.content;
         if (!content.found) {
             // object not found, nothing to show
             return;
         }
         this.name = content.name;
 
         // do some math to have the tooltip arrow on more or less on left or right
         // width of the editor
         var w = $(this.code_mirror.getScrollerElement()).width();
         // ofset of the editor
         var o = $(this.code_mirror.getScrollerElement()).offset();
 
         // whatever anchor/head order but arrow at mid x selection
         var anchor = this.code_mirror.cursorCoords(false);
         var head  = this.code_mirror.cursorCoords(true);
         var xinit = (head.left+anchor.left)/2;
         var xinter = o.left + (xinit - o.left) / w * (w - 450);
         var posarrowleft = xinit - xinter;
 
         if (this._hidden === false) {
             this.tooltip.animate({
                 'left': xinter - 30 + 'px',
                 'top': (head.bottom + 10) + 'px'
             });
         } else {
             this.tooltip.css({
                 'left': xinter - 30 + 'px'
             });
             this.tooltip.css({
                 'top': (head.bottom + 10) + 'px'
             });
         }
         this.arrow.animate({
             'left': posarrowleft + 'px'
         });
         
         this._hidden = false;
         this.tooltip.fadeIn('fast');
         this.text.children().remove();
         
         // This should support rich data types, but only text/plain for now
         // Any HTML within the docstring is escaped by the fixConsole() method.
         var pre = $('<pre/>').html(utils.fixConsole(content.data['text/plain']));
         this.text.append(pre);
         // keep scroll top to be sure to always see the first line
         this.text.scrollTop(0);
     };
 
     IPython.Tooltip = Tooltip;
 
     return IPython;
 
 }(IPython));

IPython/kernel/channels.py

@@ -1,620 +1,626 b''
 """Base classes to manage a Client's interaction with a running kernel"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import absolute_import
 
 import atexit
 import errno
 from threading import Thread
 import time
 
 import zmq
 # import ZMQError in top-level namespace, to avoid ugly attribute-error messages
 # during garbage collection of threads at exit:
 from zmq import ZMQError
 from zmq.eventloop import ioloop, zmqstream
 
 # Local imports
 from .channelsabc import (
     ShellChannelABC, IOPubChannelABC,
     HBChannelABC, StdInChannelABC,
 )
 from IPython.utils.py3compat import string_types, iteritems
 
 #-----------------------------------------------------------------------------
 # Constants and exceptions
 #-----------------------------------------------------------------------------
 
 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, string_types):
             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 iteritems(dct):
         if not isinstance(k, string_types):
             raise ValueError('key %r in dict must be a string' % k)
         if not isinstance(v, string_types):
             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
     stream = None
     _address = None
     _exiting = False
     proxy_methods = []
 
     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 : zmq url
             Standard (ip, port) tuple that the kernel is listening on.
         """
         super(ZMQSocketChannel, self).__init__()
         self.daemon = True
 
         self.context = context
         self.session = session
         if isinstance(address, tuple):
             if address[1] == 0:
                 message = 'The port number for a channel cannot be 0.'
                 raise InvalidPortNumber(message)
             address = "tcp://%s:%i" % address
         self._address = address
         atexit.register(self._notice_exit)
 
     def _notice_exit(self):
         self._exiting = True
 
     def _run_loop(self):
         """Run my loop, ignoring EINTR events in the poller"""
         while True:
             try:
                 self.ioloop.start()
             except ZMQError as e:
                 if e.errno == errno.EINTR:
                     continue
                 else:
                     raise
             except Exception:
                 if self._exiting:
                     break
                 else:
                     raise
             else:
                 break
 
     def stop(self):
         """Stop the channel's event loop and join its thread.
 
         This calls :meth:`~threading.Thread.join` and returns when the thread
         terminates. :class:`RuntimeError` will be raised if
         :meth:`~threading.Thread.start` is called again.
         """
         if self.ioloop is not None:
             self.ioloop.stop()
         self.join()
         self.close()
     
     def close(self):
         if self.ioloop is not None:
             try:
                 self.ioloop.close(all_fds=True)
             except Exception:
                 pass
         if self.socket is not None:
             try:
                 self.socket.close(linger=0)
             except Exception:
                 pass
             self.socket = None
 
     @property
     def address(self):
         """Get the channel's address as a zmq url string.
 
         These URLS have the form: 'tcp://127.0.0.1:5555'.
         """
         return self._address
 
     def _queue_send(self, msg):
         """Queue a message to be sent from the IOLoop's thread.
 
         Parameters
         ----------
         msg : message to send
 
         This is threadsafe, as it uses IOLoop.add_callback to give the loop's
         thread control of the action.
         """
         def thread_send():
             self.session.send(self.stream, msg)
         self.ioloop.add_callback(thread_send)
 
     def _handle_recv(self, msg):
         """Callback for stream.on_recv.
 
         Unpacks message, and calls handlers with it.
         """
         ident,smsg = self.session.feed_identities(msg)
         self.call_handlers(self.session.unserialize(smsg))
 
 
 
 class ShellChannel(ZMQSocketChannel):
     """The shell channel for issuing request/replies to the kernel."""
 
     command_queue = None
     # flag for whether execute requests should be allowed to call raw_input:
     allow_stdin = True
     proxy_methods = [
         'execute',
         'complete',
         'inspect',
         'history',
         'kernel_info',
         'shutdown',
     ]
 
     def __init__(self, context, session, address):
         super(ShellChannel, 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.DEALER)
         self.socket.linger = 1000
         self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
         self.socket.connect(self.address)
         self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
         self.stream.on_recv(self._handle_recv)
         self._run_loop()
 
     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 level
         handlers are called in the application thread.
         """
         raise NotImplementedError('call_handlers must be defined in a subclass.')
 
     def execute(self, code, silent=False, store_history=True,
                 user_expressions=None, allow_stdin=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, and
             will force store_history to be False.
 
         store_history : bool, optional (default True)
             If set, the kernel will store command history.  This is forced
             to be False if silent is True.
 
         user_expressions : dict, optional
             A dict mapping names to expressions to be evaluated in the user's
             dict. The expression values are returned as strings formatted using
             :func:`repr`.
 
         allow_stdin : bool, optional (default self.allow_stdin)
             Flag for whether the kernel can send stdin requests to frontends.
 
             Some frontends (e.g. the Notebook) do not support stdin requests.
             If raw_input is called from code executed from such a frontend, a
             StdinNotImplementedError will be raised.
 
         Returns
         -------
         The msg_id of the message sent.
         """
         if user_expressions is None:
             user_expressions = {}
         if allow_stdin is None:
             allow_stdin = self.allow_stdin
 
 
         # Don't waste network traffic if inputs are invalid
         if not isinstance(code, string_types):
             raise ValueError('code %r must be a string' % code)
         validate_string_dict(user_expressions)
 
         # Create class for content/msg creation. Related to, but possibly
         # not in Session.
         content = dict(code=code, silent=silent, store_history=store_history,
                        user_expressions=user_expressions,
                        allow_stdin=allow_stdin,
                        )
         msg = self.session.msg('execute_request', content)
         self._queue_send(msg)
         return msg['header']['msg_id']
 
-    def complete(self, code, cursor_pos=0, block=None):
+    def complete(self, code, cursor_pos=None):
         """Tab complete text in the kernel's namespace.
 
         Parameters
         ----------
         code : str
             The context in which completion is requested.
             Can be anything between a variable name and an entire cell.
         cursor_pos : int, optional
             The position of the cursor in the block of code where the completion was requested.
+            Default: ``len(code)``
 
         Returns
         -------
         The msg_id of the message sent.
         """
+        if cursor_pos is None:
+            cursor_pos = len(code)
         content = dict(code=code, cursor_pos=cursor_pos)
         msg = self.session.msg('complete_request', content)
         self._queue_send(msg)
         return msg['header']['msg_id']
 
-    def inspect(self, code, cursor_pos=0, detail_level=0):
+    def inspect(self, code, cursor_pos=None, detail_level=0):
         """Get metadata information about an object in the kernel's namespace.
 
         It is up to the kernel to determine the appropriate object to inspect.
 
         Parameters
         ----------
         code : str
             The context in which info is requested.
             Can be anything between a variable name and an entire cell.
         cursor_pos : int, optional
             The position of the cursor in the block of code where the info was requested.
+            Default: ``len(code)``
         detail_level : int, optional
             The level of detail for the introspection (0-2)
 
         Returns
         -------
         The msg_id of the message sent.
         """
+        if cursor_pos is None:
+            cursor_pos = len(code)
         content = dict(code=code, cursor_pos=cursor_pos,
             detail_level=detail_level,
         )
         msg = self.session.msg('inspect_request', content)
         self._queue_send(msg)
         return msg['header']['msg_id']
 
     def history(self, raw=True, output=False, hist_access_type='range', **kwargs):
         """Get entries from the kernel's history list.
 
         Parameters
         ----------
         raw : bool
             If True, return the raw input.
         output : bool
             If True, then return the output as well.
         hist_access_type : str
             'range' (fill in session, start and stop params), 'tail' (fill in n)
              or 'search' (fill in pattern param).
 
         session : int
             For a range request, the session from which to get lines. Session
             numbers are positive integers; negative ones count back from the
             current session.
         start : int
             The first line number of a history range.
         stop : int
             The final (excluded) line number of a history range.
 
         n : int
             The number of lines of history to get for a tail request.
 
         pattern : str
             The glob-syntax pattern for a search request.
 
         Returns
         -------
         The msg_id of the message sent.
         """
         content = dict(raw=raw, output=output, hist_access_type=hist_access_type,
                                                                     **kwargs)
         msg = self.session.msg('history_request', content)
         self._queue_send(msg)
         return msg['header']['msg_id']
 
     def kernel_info(self):
         """Request kernel info."""
         msg = self.session.msg('kernel_info_request')
         self._queue_send(msg)
         return msg['header']['msg_id']
 
     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', {'restart':restart})
         self._queue_send(msg)
         return msg['header']['msg_id']
 
 
 
 class IOPubChannel(ZMQSocketChannel):
     """The iopub channel which listens for messages that the kernel publishes.
 
     This channel is where all output is published to frontends.
     """
 
     def __init__(self, context, session, address):
         super(IOPubChannel, 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.linger = 1000
         self.socket.setsockopt(zmq.SUBSCRIBE,b'')
         self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
         self.socket.connect(self.address)
         self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
         self.stream.on_recv(self._handle_recv)
         self._run_loop()
 
     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 iopub channel.
 
         Callers should use this method to ensure that :meth:`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 range(2):
             self._flushed = False
             self.ioloop.add_callback(self._flush)
             while not self._flushed and time.time() < stop_time:
                 time.sleep(0.01)
 
     def _flush(self):
         """Callback for :method:`self.flush`."""
         self.stream.flush()
         self._flushed = True
 
 
 class StdInChannel(ZMQSocketChannel):
     """The stdin channel to handle raw_input requests that the kernel makes."""
 
     msg_queue = None
     proxy_methods = ['input']
 
     def __init__(self, context, session, address):
         super(StdInChannel, 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.DEALER)
         self.socket.linger = 1000
         self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
         self.socket.connect(self.address)
         self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
         self.stream.on_recv(self._handle_recv)
         self._run_loop()
 
     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_send(msg)
 
 
 class HBChannel(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
     _beating = None
 
     def __init__(self, context, session, address):
         super(HBChannel, self).__init__(context, session, address)
         self._running = False
         self._pause =True
         self.poller = zmq.Poller()
 
     def _create_socket(self):
         if self.socket is not None:
             # close previous socket, before opening a new one
             self.poller.unregister(self.socket)
             self.socket.close()
         self.socket = self.context.socket(zmq.REQ)
         self.socket.linger = 1000
         self.socket.connect(self.address)
 
         self.poller.register(self.socket, zmq.POLLIN)
 
     def _poll(self, start_time):
         """poll for heartbeat replies until we reach self.time_to_dead.
 
         Ignores interrupts, and returns the result of poll(), which
         will be an empty list if no messages arrived before the timeout,
         or the event tuple if there is a message to receive.
         """
 
         until_dead = self.time_to_dead - (time.time() - start_time)
         # ensure poll at least once
         until_dead = max(until_dead, 1e-3)
         events = []
         while True:
             try:
                 events = self.poller.poll(1000 * until_dead)
             except ZMQError as e:
                 if e.errno == errno.EINTR:
                     # ignore interrupts during heartbeat
                     # this may never actually happen
                     until_dead = self.time_to_dead - (time.time() - start_time)
                     until_dead = max(until_dead, 1e-3)
                     pass
                 else:
                     raise
             except Exception:
                 if self._exiting:
                     break
                 else:
                     raise
             else:
                 break
         return events
 
     def run(self):
         """The thread's main activity.  Call start() instead."""
         self._create_socket()
         self._running = True
         self._beating = True
 
         while self._running:
             if self._pause:
                 # just sleep, and skip the rest of the loop
                 time.sleep(self.time_to_dead)
                 continue
 
             since_last_heartbeat = 0.0
             # io.rprint('Ping from HB channel') # dbg
             # no need to catch EFSM here, because the previous event was
             # either a recv or connect, which cannot be followed by EFSM
             self.socket.send(b'ping')
             request_time = time.time()
             ready = self._poll(request_time)
             if ready:
                 self._beating = True
                 # the poll above guarantees we have something to recv
                 self.socket.recv()
                 # sleep the remainder of the cycle
                 remainder = self.time_to_dead - (time.time() - request_time)
                 if remainder > 0:
                     time.sleep(remainder)
                 continue
             else:
                 # nothing was received within the time limit, signal heart failure
                 self._beating = False
                 since_last_heartbeat = time.time() - request_time
                 self.call_handlers(since_last_heartbeat)
                 # and close/reopen the socket, because the REQ/REP cycle has been broken
                 self._create_socket()
                 continue
 
     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 responsive (and not paused)."""
         if self.is_alive() and not self._pause and self._beating:
             return True
         else:
             return False
 
     def stop(self):
         """Stop the channel's event loop and join its thread."""
         self._running = False
         super(HBChannel, 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 level
         handlers are called in the application thread.
         """
         raise NotImplementedError('call_handlers must be defined in a subclass.')
 
 
 #---------------------------------------------------------------------#-----------------------------------------------------------------------------
 # ABC Registration
 #-----------------------------------------------------------------------------
 
 ShellChannelABC.register(ShellChannel)
 IOPubChannelABC.register(IOPubChannel)
 HBChannelABC.register(HBChannel)
 StdInChannelABC.register(StdInChannel)

IPython/kernel/inprocess/channels.py

@@ -1,192 +1,196 b''
 """A kernel client for in-process kernels."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from IPython.kernel.channelsabc import (
     ShellChannelABC, IOPubChannelABC,
     HBChannelABC, StdInChannelABC,
 )
 
 from .socket import DummySocket
 
 #-----------------------------------------------------------------------------
 # Channel classes
 #-----------------------------------------------------------------------------
 
 class InProcessChannel(object):
     """Base class for in-process channels."""
     proxy_methods = []
 
     def __init__(self, client=None):
         super(InProcessChannel, self).__init__()
         self.client = client
         self._is_alive = False
 
     #--------------------------------------------------------------------------
     # Channel interface
     #--------------------------------------------------------------------------
 
     def is_alive(self):
         return self._is_alive
 
     def start(self):
         self._is_alive = True
 
     def stop(self):
         self._is_alive = False
 
     def call_handlers(self, msg):
         """ This method is called in the main thread when a message arrives.
 
         Subclasses should override this method to handle incoming messages.
         """
         raise NotImplementedError('call_handlers must be defined in a subclass.')
 
     #--------------------------------------------------------------------------
     # InProcessChannel interface
     #--------------------------------------------------------------------------
 
     def call_handlers_later(self, *args, **kwds):
         """ Call the message handlers later.
 
         The default implementation just calls the handlers immediately, but this
         method exists so that GUI toolkits can defer calling the handlers until
         after the event loop has run, as expected by GUI frontends.
         """
         self.call_handlers(*args, **kwds)
 
     def process_events(self):
         """ Process any pending GUI events.
 
         This method will be never be called from a frontend without an event
         loop (e.g., a terminal frontend).
         """
         raise NotImplementedError
 
 
 class InProcessShellChannel(InProcessChannel):
     """See `IPython.kernel.channels.ShellChannel` for docstrings."""
 
     # flag for whether execute requests should be allowed to call raw_input
     allow_stdin = True
     proxy_methods = [
         'execute',
         'complete',
         'inspect',
         'history',
         'shutdown',
         'kernel_info',
     ]
 
     #--------------------------------------------------------------------------
     # ShellChannel interface
     #--------------------------------------------------------------------------
 
     def execute(self, code, silent=False, store_history=True,
                 user_expressions={}, allow_stdin=None):
         if allow_stdin is None:
             allow_stdin = self.allow_stdin
         content = dict(code=code, silent=silent, store_history=store_history,
                        user_expressions=user_expressions,
                        allow_stdin=allow_stdin)
         msg = self.client.session.msg('execute_request', content)
         self._dispatch_to_kernel(msg)
         return msg['header']['msg_id']
 
-    def complete(self, code, cursor_pos=0):
+    def complete(self, code, cursor_pos=None):
+        if cursor_pos is None:
+            cursor_pos = len(code)
         content = dict(code=code, cursor_pos=cursor_pos)
         msg = self.client.session.msg('complete_request', content)
         self._dispatch_to_kernel(msg)
         return msg['header']['msg_id']
 
-    def inspect(self, code, cursor_pos=0, detail_level=0):
+    def inspect(self, code, cursor_pos=None, detail_level=0):
+        if cursor_pos is None:
+            cursor_pos = len(code)
         content = dict(code=code, cursor_pos=cursor_pos,
             detail_level=detail_level,
         )
         msg = self.client.session.msg('inspect_request', content)
         self._dispatch_to_kernel(msg)
         return msg['header']['msg_id']
 
     def history(self, raw=True, output=False, hist_access_type='range', **kwds):
         content = dict(raw=raw, output=output,
                        hist_access_type=hist_access_type, **kwds)
         msg = self.client.session.msg('history_request', content)
         self._dispatch_to_kernel(msg)
         return msg['header']['msg_id']
 
     def shutdown(self, restart=False):
         # FIXME: What to do here?
         raise NotImplementedError('Cannot shutdown in-process kernel')
 
     def kernel_info(self):
         """Request kernel info."""
         msg = self.client.session.msg('kernel_info_request')
         self._dispatch_to_kernel(msg)
         return msg['header']['msg_id']
 
     #--------------------------------------------------------------------------
     # Protected interface
     #--------------------------------------------------------------------------
 
     def _dispatch_to_kernel(self, msg):
         """ Send a message to the kernel and handle a reply.
         """
         kernel = self.client.kernel
         if kernel is None:
             raise RuntimeError('Cannot send request. No kernel exists.')
 
         stream = DummySocket()
         self.client.session.send(stream, msg)
         msg_parts = stream.recv_multipart()
         kernel.dispatch_shell(stream, msg_parts)
 
         idents, reply_msg = self.client.session.recv(stream, copy=False)
         self.call_handlers_later(reply_msg)
 
 
 class InProcessIOPubChannel(InProcessChannel):
     """See `IPython.kernel.channels.IOPubChannel` for docstrings."""
 
     def flush(self, timeout=1.0):
         pass
 
 
 class InProcessStdInChannel(InProcessChannel):
     """See `IPython.kernel.channels.StdInChannel` for docstrings."""
 
     proxy_methods = ['input']
 
     def input(self, string):
         kernel = self.client.kernel
         if kernel is None:
             raise RuntimeError('Cannot send input reply. No kernel exists.')
         kernel.raw_input_str = string
 
 
 class InProcessHBChannel(InProcessChannel):
     """See `IPython.kernel.channels.HBChannel` for docstrings."""
 
     time_to_dead = 3.0
 
     def __init__(self, *args, **kwds):
         super(InProcessHBChannel, self).__init__(*args, **kwds)
         self._pause = True
 
     def pause(self):
         self._pause = True
 
     def unpause(self):
         self._pause = False
 
     def is_beating(self):
         return not self._pause
 
 #-----------------------------------------------------------------------------
 # ABC Registration
 #-----------------------------------------------------------------------------
 
 ShellChannelABC.register(InProcessShellChannel)
 IOPubChannelABC.register(InProcessIOPubChannel)
 HBChannelABC.register(InProcessHBChannel)
 StdInChannelABC.register(InProcessStdInChannel)

IPython/kernel/tests/test_message_spec.py

@@ -1,400 +1,409 b''
 """Test suite for our zeromq-based message specification."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import re
 from distutils.version import LooseVersion as V
 from subprocess import PIPE
 try:
     from queue import Empty  # Py 3
 except ImportError:
     from Queue import Empty  # Py 2
 
 import nose.tools as nt
 
 from IPython.kernel import KernelManager
 
 from IPython.utils.traitlets import (
     HasTraits, TraitError, Bool, Unicode, Dict, Integer, List, Enum, Any,
 )
 from IPython.utils.py3compat import string_types, iteritems
 
 from .utils import TIMEOUT, start_global_kernel, flush_channels, execute
 
 #-----------------------------------------------------------------------------
 # Globals
 #-----------------------------------------------------------------------------
 KC = None
 
 def setup():
     global KC
     KC = start_global_kernel()
 
 #-----------------------------------------------------------------------------
 # Message Spec References
 #-----------------------------------------------------------------------------
 
 class Reference(HasTraits):
 
     """
     Base class for message spec specification testing.
 
     This class is the core of the message specification test.  The
     idea is that child classes implement trait attributes for each
     message keys, so that message keys can be tested against these
     traits using :meth:`check` method.
 
     """
 
     def check(self, d):
         """validate a dict against our traits"""
         for key in self.trait_names():
             nt.assert_in(key, d)
             # FIXME: always allow None, probably not a good idea
             if d[key] is None:
                 continue
             try:
                 setattr(self, key, d[key])
             except TraitError as e:
                 assert False, str(e)
 
+
 class Version(Unicode):
+    def __init__(self, *args, **kwargs):
+        self.min = kwargs.pop('min', None)
+        self.max = kwargs.pop('max', None)
+        kwargs['default_value'] = self.min
+        super(Version, self).__init__(*args, **kwargs)
+    
     def validate(self, obj, value):
-        min_version = self.default_value
-        if V(value) < V(min_version):
-            raise TraitError("bad version: %s < %s" % (value, min_version))
+        if self.min and V(value) < V(self.min):
+            raise TraitError("bad version: %s < %s" % (value, self.min))
+        if self.max and (V(value) > V(self.max)):
+            raise TraitError("bad version: %s > %s" % (value, self.max))
+
 
 class RMessage(Reference):
     msg_id = Unicode()
     msg_type = Unicode()
     header = Dict()
     parent_header = Dict()
     content = Dict()
     
     def check(self, d):
         super(RMessage, self).check(d)
         RHeader().check(self.header)
         if self.parent_header:
             RHeader().check(self.parent_header)
 
 class RHeader(Reference):
     msg_id = Unicode()
     msg_type = Unicode()
     session = Unicode()
     username = Unicode()
-    version = Version('5.0')
+    version = Version(min='5.0')
 
-mime_pat = re.compile(r'\w+/\w+')
+mime_pat = re.compile(r'^[\w\-\+\.]+/[\w\-\+\.]+$')
 
 class MimeBundle(Reference):
     metadata = Dict()
     data = Dict()
     def _data_changed(self, name, old, new):
         for k,v in iteritems(new):
             assert mime_pat.match(k)
             nt.assert_is_instance(v, string_types)
 
 # shell replies
 
 class ExecuteReply(Reference):
     execution_count = Integer()
     status = Enum((u'ok', u'error'))
     
     def check(self, d):
         Reference.check(self, d)
         if d['status'] == 'ok':
             ExecuteReplyOkay().check(d)
         elif d['status'] == 'error':
             ExecuteReplyError().check(d)
 
 
 class ExecuteReplyOkay(Reference):
     payload = List(Dict)
     user_expressions = Dict()
 
 
 class ExecuteReplyError(Reference):
     ename = Unicode()
     evalue = Unicode()
     traceback = List(Unicode)
 
 
 class InspectReply(MimeBundle):
     found = Bool()
 
 
 class ArgSpec(Reference):
     args = List(Unicode)
     varargs = Unicode()
     varkw = Unicode()
     defaults = List()
 
 
 class Status(Reference):
     execution_state = Enum((u'busy', u'idle', u'starting'))
 
 
 class CompleteReply(Reference):
     matches = List(Unicode)
     cursor_start = Integer()
     cursor_end = Integer()
     status = Unicode()
 
 
 class KernelInfoReply(Reference):
-    protocol_version = Version('5.0')
+    protocol_version = Version(min='5.0')
     implementation = Unicode('ipython')
-    implementation_version = Version('2.1')
-    language_version = Version('2.7')
+    implementation_version = Version(min='2.1')
+    language_version = Version(min='2.7')
     language = Unicode('python')
     banner = Unicode()
 
 
 # IOPub messages
 
 class ExecuteInput(Reference):
     code = Unicode()
     execution_count = Integer()
 
 
 Error = ExecuteReplyError
 
 
 class Stream(Reference):
     name = Enum((u'stdout', u'stderr'))
     data = Unicode()
 
 
 class DisplayData(MimeBundle):
     pass
 
 
 class ExecuteResult(MimeBundle):
     execution_count = Integer()
 
 
 references = {
     'execute_reply' : ExecuteReply(),
     'inspect_reply' : InspectReply(),
     'status' : Status(),
     'complete_reply' : CompleteReply(),
     'kernel_info_reply': KernelInfoReply(),
     'execute_input' : ExecuteInput(),
     'execute_result' : ExecuteResult(),
     'error' : Error(),
     'stream' : Stream(),
     'display_data' : DisplayData(),
     'header' : RHeader(),
 }
 """
 Specifications of `content` part of the reply messages.
 """
 
 
 def validate_message(msg, msg_type=None, parent=None):
     """validate a message
     
     This is a generator, and must be iterated through to actually
     trigger each test.
     
     If msg_type and/or parent are given, the msg_type and/or parent msg_id
     are compared with the given values.
     """
     RMessage().check(msg)
     if msg_type:
         nt.assert_equal(msg['msg_type'], msg_type)
     if parent:
         nt.assert_equal(msg['parent_header']['msg_id'], parent)
     content = msg['content']
     ref = references[msg['msg_type']]
     ref.check(content)
 
 
 #-----------------------------------------------------------------------------
 # Tests
 #-----------------------------------------------------------------------------
 
 # Shell channel
 
 def test_execute():
     flush_channels()
     
     msg_id = KC.execute(code='x=1')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'execute_reply', msg_id)
 
 
 def test_execute_silent():
     flush_channels()
     msg_id, reply = execute(code='x=1', silent=True)
     
     # flush status=idle
     status = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(status, 'status', msg_id)
     nt.assert_equal(status['content']['execution_state'], 'idle')
 
     nt.assert_raises(Empty, KC.iopub_channel.get_msg, timeout=0.1)
     count = reply['execution_count']
     
     msg_id, reply = execute(code='x=2', silent=True)
     
     # flush status=idle
     status = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(status, 'status', msg_id)
     nt.assert_equal(status['content']['execution_state'], 'idle')
     
     nt.assert_raises(Empty, KC.iopub_channel.get_msg, timeout=0.1)
     count_2 = reply['execution_count']
     nt.assert_equal(count_2, count)
 
 
 def test_execute_error():
     flush_channels()
     
     msg_id, reply = execute(code='1/0')
     nt.assert_equal(reply['status'], 'error')
     nt.assert_equal(reply['ename'], 'ZeroDivisionError')
     
     error = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(error, 'error', msg_id)
 
 
 def test_execute_inc():
     """execute request should increment execution_count"""
     flush_channels()
 
     msg_id, reply = execute(code='x=1')
     count = reply['execution_count']
     
     flush_channels()
     
     msg_id, reply = execute(code='x=2')
     count_2 = reply['execution_count']
     nt.assert_equal(count_2, count+1)
 
 
 def test_user_expressions():
     flush_channels()
 
     msg_id, reply = execute(code='x=1', user_expressions=dict(foo='x+1'))
     user_expressions = reply['user_expressions']
     nt.assert_equal(user_expressions, {u'foo': {
         u'status': u'ok',
         u'data': {u'text/plain': u'2'},
         u'metadata': {},
     }})
 
 
 def test_user_expressions_fail():
     flush_channels()
 
     msg_id, reply = execute(code='x=0', user_expressions=dict(foo='nosuchname'))
     user_expressions = reply['user_expressions']
     foo = user_expressions['foo']
     nt.assert_equal(foo['status'], 'error')
     nt.assert_equal(foo['ename'], 'NameError')
 
 
 def test_oinfo():
     flush_channels()
 
     msg_id = KC.inspect('a')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
 
 
 def test_oinfo_found():
     flush_channels()
 
     msg_id, reply = execute(code='a=5')
     
     msg_id = KC.inspect('a')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
     content = reply['content']
     assert content['found']
     text = content['data']['text/plain']
     nt.assert_in('Type:', text)
     nt.assert_in('Docstring:', text)
 
 
 def test_oinfo_detail():
     flush_channels()
 
     msg_id, reply = execute(code='ip=get_ipython()')
     
     msg_id = KC.inspect('ip.object_inspect', cursor_pos=10, detail_level=1)
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
     content = reply['content']
     assert content['found']
     text = content['data']['text/plain']
     nt.assert_in('Definition:', text)
     nt.assert_in('Source:', text)
 
 
 def test_oinfo_not_found():
     flush_channels()
 
     msg_id = KC.inspect('dne')
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'inspect_reply', msg_id)
     content = reply['content']
     nt.assert_false(content['found'])
 
 
 def test_complete():
     flush_channels()
 
     msg_id, reply = execute(code="alpha = albert = 5")
     
     msg_id = KC.complete('al', 2)
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'complete_reply', msg_id)
     matches = reply['content']['matches']
     for name in ('alpha', 'albert'):
         nt.assert_in(name, matches)
 
 
 def test_kernel_info_request():
     flush_channels()
 
     msg_id = KC.kernel_info()
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'kernel_info_reply', msg_id)
 
 
 def test_single_payload():
     flush_channels()
     msg_id, reply = execute(code="for i in range(3):\n"+
                                  "   x=range?\n")
     payload = reply['payload']
     next_input_pls = [pl for pl in payload if pl["source"] == "set_next_input"]
     nt.assert_equal(len(next_input_pls), 1)
 
 
 # IOPub channel
 
 
 def test_stream():
     flush_channels()
 
     msg_id, reply = execute("print('hi')")
 
     stdout = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(stdout, 'stream', msg_id)
     content = stdout['content']
     nt.assert_equal(content['data'], u'hi\n')
 
 
 def test_display_data():
     flush_channels()
 
     msg_id, reply = execute("from IPython.core.display import display; display(1)")
     
     display = KC.iopub_channel.get_msg(timeout=TIMEOUT)
     validate_message(display, 'display_data', parent=msg_id)
     data = display['content']['data']
     nt.assert_equal(data['text/plain'], u'1')
 

IPython/kernel/zmq/ipkernel.py

@@ -1,853 +1,854 b''
 """An interactive kernel that talks to frontends over 0MQ."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 import getpass
 import sys
 import time
 import traceback
 import logging
 import uuid
 
 from datetime import datetime
 from signal import (
         signal, default_int_handler, SIGINT
 )
 
 import zmq
 from zmq.eventloop import ioloop
 from zmq.eventloop.zmqstream import ZMQStream
 
 from IPython.config.configurable import Configurable
 from IPython.core.error import StdinNotImplementedError
 from IPython.core import release
 from IPython.utils import py3compat
 from IPython.utils.py3compat import builtin_mod, unicode_type, string_types
 from IPython.utils.jsonutil import json_clean
 from IPython.utils.tokenutil import token_at_cursor
 from IPython.utils.traitlets import (
     Any, Instance, Float, Dict, List, Set, Integer, Unicode,
     Type, Bool,
 )
 
 from .serialize import serialize_object, unpack_apply_message
 from .session import Session
 from .zmqshell import ZMQInteractiveShell
 
 
 #-----------------------------------------------------------------------------
 # Main kernel class
 #-----------------------------------------------------------------------------
 
 protocol_version = release.kernel_protocol_version
 ipython_version = release.version
 language_version = sys.version.split()[0]
 
 
 class Kernel(Configurable):
 
     #---------------------------------------------------------------------------
     # Kernel interface
     #---------------------------------------------------------------------------
 
     # attribute to override with a GUI
     eventloop = Any(None)
     def _eventloop_changed(self, name, old, new):
         """schedule call to eventloop from IOLoop"""
         loop = ioloop.IOLoop.instance()
         loop.add_callback(self.enter_eventloop)
 
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
     shell_class = Type(ZMQInteractiveShell)
 
     session = Instance(Session)
     profile_dir = Instance('IPython.core.profiledir.ProfileDir')
     shell_streams = List()
     control_stream = Instance(ZMQStream)
     iopub_socket = Instance(zmq.Socket)
     stdin_socket = Instance(zmq.Socket)
     log = Instance(logging.Logger)
     
     user_module = Any()
     def _user_module_changed(self, name, old, new):
         if self.shell is not None:
             self.shell.user_module = new
     
     user_ns = Instance(dict, args=None, allow_none=True)
     def _user_ns_changed(self, name, old, new):
         if self.shell is not None:
             self.shell.user_ns = new
             self.shell.init_user_ns()
 
     # identities:
     int_id = Integer(-1)
     ident = Unicode()
 
     def _ident_default(self):
         return unicode_type(uuid.uuid4())
 
     # Private interface
     
     _darwin_app_nap = Bool(True, config=True,
         help="""Whether to use appnope for compatiblity with OS X App Nap.
         
         Only affects OS X >= 10.9.
         """
     )
 
     # track associations with current request
     _allow_stdin = Bool(False)
     _parent_header = Dict()
     _parent_ident = Any(b'')
     # 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 = Dict()
 
     # A reference to the Python builtin 'raw_input' function.
     # (i.e., __builtin__.raw_input for Python 2.7, builtins.input for Python 3)
     _sys_raw_input = Any()
     _sys_eval_input = Any()
 
     # set of aborted msg_ids
     aborted = Set()
 
 
     def __init__(self, **kwargs):
         super(Kernel, self).__init__(**kwargs)
 
         # Initialize the InteractiveShell subclass
         self.shell = self.shell_class.instance(parent=self,
             profile_dir = self.profile_dir,
             user_module = self.user_module,
             user_ns     = self.user_ns,
             kernel      = self,
         )
         self.shell.displayhook.session = self.session
         self.shell.displayhook.pub_socket = self.iopub_socket
         self.shell.displayhook.topic = self._topic('execute_result')
         self.shell.display_pub.session = self.session
         self.shell.display_pub.pub_socket = self.iopub_socket
         self.shell.data_pub.session = self.session
         self.shell.data_pub.pub_socket = self.iopub_socket
 
         # TMP - hack while developing
         self.shell._reply_content = None
 
         # Build dict of handlers for message types
         msg_types = [ 'execute_request', 'complete_request',
                       'inspect_request', 'history_request',
                       'kernel_info_request',
                       'connect_request', 'shutdown_request',
                       'apply_request',
                     ]
         self.shell_handlers = {}
         for msg_type in msg_types:
             self.shell_handlers[msg_type] = getattr(self, msg_type)
         
         comm_msg_types = [ 'comm_open', 'comm_msg', 'comm_close' ]
         comm_manager = self.shell.comm_manager
         for msg_type in comm_msg_types:
             self.shell_handlers[msg_type] = getattr(comm_manager, msg_type)
         
         control_msg_types = msg_types + [ 'clear_request', 'abort_request' ]
         self.control_handlers = {}
         for msg_type in control_msg_types:
             self.control_handlers[msg_type] = getattr(self, msg_type)
 
 
     def dispatch_control(self, msg):
         """dispatch control requests"""
         idents,msg = self.session.feed_identities(msg, copy=False)
         try:
             msg = self.session.unserialize(msg, content=True, copy=False)
         except:
             self.log.error("Invalid Control Message", exc_info=True)
             return
 
         self.log.debug("Control received: %s", msg)
 
         header = msg['header']
         msg_id = header['msg_id']
         msg_type = header['msg_type']
 
         handler = self.control_handlers.get(msg_type, None)
         if handler is None:
             self.log.error("UNKNOWN CONTROL MESSAGE TYPE: %r", msg_type)
         else:
             try:
                 handler(self.control_stream, idents, msg)
             except Exception:
                 self.log.error("Exception in control handler:", exc_info=True)
     
     def dispatch_shell(self, stream, msg):
         """dispatch shell requests"""
         # flush control requests first
         if self.control_stream:
             self.control_stream.flush()
         
         idents,msg = self.session.feed_identities(msg, copy=False)
         try:
             msg = self.session.unserialize(msg, content=True, copy=False)
         except:
             self.log.error("Invalid Message", exc_info=True)
             return
 
         header = msg['header']
         msg_id = header['msg_id']
         msg_type = msg['header']['msg_type']
         
         # 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.
         self.log.debug('\n*** MESSAGE TYPE:%s***', msg_type)
         self.log.debug('   Content: %s\n   --->\n   ', msg['content'])
 
         if msg_id in self.aborted:
             self.aborted.remove(msg_id)
             # is it safe to assume a msg_id will not be resubmitted?
             reply_type = msg_type.split('_')[0] + '_reply'
             status = {'status' : 'aborted'}
             md = {'engine' : self.ident}
             md.update(status)
             reply_msg = self.session.send(stream, reply_type, metadata=md,
                         content=status, parent=msg, ident=idents)
             return
         
         handler = self.shell_handlers.get(msg_type, None)
         if handler is None:
             self.log.error("UNKNOWN MESSAGE TYPE: %r", msg_type)
         else:
             # ensure default_int_handler during handler call
             sig = signal(SIGINT, default_int_handler)
             self.log.debug("%s: %s", msg_type, msg)
             try:
                 handler(stream, idents, msg)
             except Exception:
                 self.log.error("Exception in message handler:", exc_info=True)
             finally:
                 signal(SIGINT, sig)
     
     def enter_eventloop(self):
         """enter eventloop"""
         self.log.info("entering eventloop %s", self.eventloop)
         for stream in self.shell_streams:
             # flush any pending replies,
             # which may be skipped by entering the eventloop
             stream.flush(zmq.POLLOUT)
         # restore default_int_handler
         signal(SIGINT, default_int_handler)
         while self.eventloop is not None:
             try:
                 self.eventloop(self)
             except KeyboardInterrupt:
                 # Ctrl-C shouldn't crash the kernel
                 self.log.error("KeyboardInterrupt caught in kernel")
                 continue
             else:
                 # eventloop exited cleanly, this means we should stop (right?)
                 self.eventloop = None
                 break
         self.log.info("exiting eventloop")
 
     def start(self):
         """register dispatchers for streams"""
         self.shell.exit_now = False
         if self.control_stream:
             self.control_stream.on_recv(self.dispatch_control, copy=False)
 
         def make_dispatcher(stream):
             def dispatcher(msg):
                 return self.dispatch_shell(stream, msg)
             return dispatcher
 
         for s in self.shell_streams:
             s.on_recv(make_dispatcher(s), copy=False)
 
         # publish idle status
         self._publish_status('starting')
     
     def do_one_iteration(self):
         """step eventloop just once"""
         if self.control_stream:
             self.control_stream.flush()
         for stream in self.shell_streams:
             # handle at most one request per iteration
             stream.flush(zmq.POLLIN, 1)
             stream.flush(zmq.POLLOUT)
 
 
     def record_ports(self, ports):
         """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 = ports
 
     #---------------------------------------------------------------------------
     # Kernel request handlers
     #---------------------------------------------------------------------------
     
     def _make_metadata(self, other=None):
         """init metadata dict, for execute/apply_reply"""
         new_md = {
             'dependencies_met' : True,
             'engine' : self.ident,
             'started': datetime.now(),
         }
         if other:
             new_md.update(other)
         return new_md
     
     def _publish_execute_input(self, code, parent, execution_count):
         """Publish the code request on the iopub stream."""
 
         self.session.send(self.iopub_socket, u'execute_input',
                             {u'code':code, u'execution_count': execution_count},
                             parent=parent, ident=self._topic('execute_input')
         )
     
     def _publish_status(self, status, parent=None):
         """send status (busy/idle) on IOPub"""
         self.session.send(self.iopub_socket,
                           u'status',
                           {u'execution_state': status},
                           parent=parent,
                           ident=self._topic('status'),
                           )
     
     def _forward_input(self, allow_stdin=False):
         """Forward raw_input and getpass to the current frontend.
         
         via input_request
         """
         self._allow_stdin = allow_stdin
         
         if py3compat.PY3:
             self._sys_raw_input = builtin_mod.input
             builtin_mod.input = self.raw_input
         else:
             self._sys_raw_input = builtin_mod.raw_input
             self._sys_eval_input = builtin_mod.input
             builtin_mod.raw_input = self.raw_input
             builtin_mod.input = lambda prompt='': eval(self.raw_input(prompt))
         self._save_getpass = getpass.getpass
         getpass.getpass = self.getpass
     
     def _restore_input(self):
         """Restore raw_input, getpass"""
         if py3compat.PY3:
             builtin_mod.input = self._sys_raw_input
         else:
             builtin_mod.raw_input = self._sys_raw_input
             builtin_mod.input = self._sys_eval_input
         
         getpass.getpass = self._save_getpass
     
     def set_parent(self, ident, parent):
-        """Record the parent state
+        """Set the current parent_header
         
-        For associating side effects with their requests.
+        Side effects (IOPub messages) and replies are associated with
+        the request that caused them via the parent_header.
+        
+        The parent identity is used to route input_request messages
+        on the stdin channel.
         """
         self._parent_ident = ident
         self._parent_header = parent
         self.shell.set_parent(parent)
     
     def execute_request(self, stream, ident, parent):
         """handle an execute_request"""
         
         self._publish_status(u'busy', parent)
         
         try:
             content = parent[u'content']
             code = py3compat.cast_unicode_py2(content[u'code'])
             silent = content[u'silent']
             store_history = content.get(u'store_history', not silent)
         except:
             self.log.error("Got bad msg: ")
             self.log.error("%s", parent)
             return
         
         md = self._make_metadata(parent['metadata'])
         
         shell = self.shell # we'll need this a lot here
         
         self._forward_input(content.get('allow_stdin', False))
         # Set the parent message of the display hook and out streams.
         self.set_parent(ident, parent)
         
         # Re-broadcast our input for the benefit of listening clients, and
         # start computing output
         if not silent:
             self._publish_execute_input(code, parent, shell.execution_count)
 
         reply_content = {}
         # FIXME: the shell calls the exception handler itself.
         shell._reply_content = None
         try:
             shell.run_cell(code, store_history=store_history, silent=silent)
         except:
             status = u'error'
             # FIXME: this code right now isn't being used yet by default,
             # because the run_cell() 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'
         finally:
             self._restore_input()
 
         reply_content[u'status'] = status
 
         # Return the execution counter so clients can display prompts
         reply_content['execution_count'] = shell.execution_count - 1
 
         # 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)
             e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='execute')
             reply_content['engine_info'] = e_info
             # reset after use
             shell._reply_content = None
         
         if 'traceback' in reply_content:
             self.log.info("Exception in execute request:\n%s", '\n'.join(reply_content['traceback']))
         
 
         # At this point, we can tell whether the main code execution succeeded
         # or not.  If it did, we proceed to evaluate user_expressions
         if reply_content['status'] == 'ok':
             reply_content[u'user_expressions'] = \
                          shell.user_expressions(content.get(u'user_expressions', {}))
         else:
             # If there was an error, don't even try to compute expressions
             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()
 
         # 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)
 
         # Send the reply.
         reply_content = json_clean(reply_content)
         
         md['status'] = reply_content['status']
         if reply_content['status'] == 'error' and \
                         reply_content['ename'] == 'UnmetDependency':
                 md['dependencies_met'] = False
 
         reply_msg = self.session.send(stream, u'execute_reply',
                                       reply_content, parent, metadata=md,
                                       ident=ident)
         
         self.log.debug("%s", reply_msg)
 
         if not silent and reply_msg['content']['status'] == u'error':
             self._abort_queues()
 
         self._publish_status(u'idle', parent)
 
     def complete_request(self, stream, ident, parent):
         content = parent['content']
         code = content['code']
         cursor_pos = content['cursor_pos']
         
         txt, matches = self.shell.complete('', code, cursor_pos)
         matches = {'matches' : matches,
                    'cursor_end' : cursor_pos,
                    'cursor_start' : cursor_pos - len(txt),
                    'metadata' : {},
                    'status' : 'ok'}
         matches = json_clean(matches)
         completion_msg = self.session.send(stream, 'complete_reply',
                                            matches, parent, ident)
         self.log.debug("%s", completion_msg)
 
     def inspect_request(self, stream, ident, parent):
         content = parent['content']
         
         name = token_at_cursor(content['code'], content['cursor_pos'])
         info = self.shell.object_inspect(name)
         
         reply_content = {'status' : 'ok'}
         reply_content['data'] = data = {}
         reply_content['metadata'] = {}
         reply_content['found'] = info['found']
         if info['found']:
             info_text = self.shell.object_inspect_text(
                 name,
                 detail_level=content.get('detail_level', 0),
             )
             reply_content['data']['text/plain'] = info_text
         # Before we send this object over, we scrub it for JSON usage
         reply_content = json_clean(reply_content)
         msg = self.session.send(stream, 'inspect_reply',
                                 reply_content, parent, ident)
         self.log.debug("%s", msg)
 
     def history_request(self, stream, ident, parent):
         # We need to pull these out, as passing **kwargs doesn't work with
         # unicode keys before Python 2.6.5.
         hist_access_type = parent['content']['hist_access_type']
         raw = parent['content']['raw']
         output = parent['content']['output']
         if hist_access_type == 'tail':
             n = parent['content']['n']
             hist = self.shell.history_manager.get_tail(n, raw=raw, output=output,
                                                             include_latest=True)
 
         elif hist_access_type == 'range':
             session = parent['content']['session']
             start = parent['content']['start']
             stop = parent['content']['stop']
             hist = self.shell.history_manager.get_range(session, start, stop,
                                                         raw=raw, output=output)
 
         elif hist_access_type == 'search':
             n = parent['content'].get('n')
             unique = parent['content'].get('unique', False)
             pattern = parent['content']['pattern']
             hist = self.shell.history_manager.search(
                 pattern, raw=raw, output=output, n=n, unique=unique)
 
         else:
             hist = []
         hist = list(hist)
         content = {'history' : hist}
         content = json_clean(content)
         msg = self.session.send(stream, 'history_reply',
                                 content, parent, ident)
         self.log.debug("Sending history reply with %i entries", len(hist))
 
     def connect_request(self, stream, ident, parent):
         if self._recorded_ports is not None:
             content = self._recorded_ports.copy()
         else:
             content = {}
         msg = self.session.send(stream, 'connect_reply',
                                 content, parent, ident)
         self.log.debug("%s", msg)
 
     def kernel_info_request(self, stream, ident, parent):
         vinfo = {
             'protocol_version': protocol_version,
             'implementation': 'ipython',
             'implementation_version': ipython_version,
             'language_version': language_version,
             'language': 'python',
             'banner': self.shell.banner,
         }
         msg = self.session.send(stream, 'kernel_info_reply',
                                 vinfo, parent, ident)
         self.log.debug("%s", msg)
 
     def shutdown_request(self, stream, ident, parent):
         self.shell.exit_now = True
         content = dict(status='ok')
         content.update(parent['content'])
         self.session.send(stream, u'shutdown_reply', content, parent, ident=ident)
         # same content, but different msg_id for broadcasting on IOPub
         self._shutdown_message = self.session.msg(u'shutdown_reply',
                                                   content, parent
         )
 
         self._at_shutdown()
         # call sys.exit after a short delay
         loop = ioloop.IOLoop.instance()
         loop.add_timeout(time.time()+0.1, loop.stop)
 
     #---------------------------------------------------------------------------
     # Engine methods
     #---------------------------------------------------------------------------
 
     def apply_request(self, stream, ident, parent):
         try:
             content = parent[u'content']
             bufs = parent[u'buffers']
             msg_id = parent['header']['msg_id']
         except:
             self.log.error("Got bad msg: %s", parent, exc_info=True)
             return
 
         self._publish_status(u'busy', parent)
 
         # Set the parent message of the display hook and out streams.
         shell = self.shell
         shell.set_parent(parent)
 
-        # execute_input_msg = self.session.msg(u'execute_input',{u'code':code}, parent=parent)
-        # self.iopub_socket.send(execute_input_msg)
-        # self.session.send(self.iopub_socket, u'execute_input', {u'code':code},parent=parent)
         md = self._make_metadata(parent['metadata'])
         try:
             working = shell.user_ns
 
             prefix = "_"+str(msg_id).replace("-","")+"_"
 
             f,args,kwargs = unpack_apply_message(bufs, working, copy=False)
 
             fname = getattr(f, '__name__', 'f')
 
             fname = prefix+"f"
             argname = prefix+"args"
             kwargname = prefix+"kwargs"
             resultname = prefix+"result"
 
             ns = { fname : f, argname : args, kwargname : kwargs , resultname : None }
             # print ns
             working.update(ns)
             code = "%s = %s(*%s,**%s)" % (resultname, fname, argname, kwargname)
             try:
                 exec(code, shell.user_global_ns, shell.user_ns)
                 result = working.get(resultname)
             finally:
                 for key in ns:
                     working.pop(key)
 
             result_buf = serialize_object(result,
                 buffer_threshold=self.session.buffer_threshold,
                 item_threshold=self.session.item_threshold,
             )
         
         except:
             # invoke IPython traceback formatting
             shell.showtraceback()
             # FIXME - fish exception info out of shell, possibly left there by
             # run_code.  We'll need to clean up this logic later.
             reply_content = {}
             if shell._reply_content is not None:
                 reply_content.update(shell._reply_content)
                 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='apply')
                 reply_content['engine_info'] = e_info
                 # reset after use
                 shell._reply_content = None
             
             self.session.send(self.iopub_socket, u'error', reply_content, parent=parent,
                                 ident=self._topic('error'))
             self.log.info("Exception in apply request:\n%s", '\n'.join(reply_content['traceback']))
             result_buf = []
 
             if reply_content['ename'] == 'UnmetDependency':
                 md['dependencies_met'] = False
         else:
             reply_content = {'status' : 'ok'}
 
         # put 'ok'/'error' status in header, for scheduler introspection:
         md['status'] = reply_content['status']
 
         # flush i/o
         sys.stdout.flush()
         sys.stderr.flush()
         
         reply_msg = self.session.send(stream, u'apply_reply', reply_content,
                     parent=parent, ident=ident,buffers=result_buf, metadata=md)
 
         self._publish_status(u'idle', parent)
 
     #---------------------------------------------------------------------------
     # Control messages
     #---------------------------------------------------------------------------
 
     def abort_request(self, stream, ident, parent):
         """abort a specifig msg by id"""
         msg_ids = parent['content'].get('msg_ids', None)
         if isinstance(msg_ids, string_types):
             msg_ids = [msg_ids]
         if not msg_ids:
             self.abort_queues()
         for mid in msg_ids:
             self.aborted.add(str(mid))
 
         content = dict(status='ok')
         reply_msg = self.session.send(stream, 'abort_reply', content=content,
                 parent=parent, ident=ident)
         self.log.debug("%s", reply_msg)
 
     def clear_request(self, stream, idents, parent):
         """Clear our namespace."""
         self.shell.reset(False)
         msg = self.session.send(stream, 'clear_reply', ident=idents, parent=parent,
                 content = dict(status='ok'))
 
 
     #---------------------------------------------------------------------------
     # Protected interface
     #---------------------------------------------------------------------------
 
     def _wrap_exception(self, method=None):
         # import here, because _wrap_exception is only used in parallel,
         # and parallel has higher min pyzmq version
         from IPython.parallel.error import wrap_exception
         e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method=method)
         content = wrap_exception(e_info)
         return content
 
     def _topic(self, topic):
         """prefixed topic for IOPub messages"""
         if self.int_id >= 0:
             base = "engine.%i" % self.int_id
         else:
             base = "kernel.%s" % self.ident
         
         return py3compat.cast_bytes("%s.%s" % (base, topic))
     
     def _abort_queues(self):
         for stream in self.shell_streams:
             if stream:
                 self._abort_queue(stream)
 
     def _abort_queue(self, stream):
         poller = zmq.Poller()
         poller.register(stream.socket, zmq.POLLIN)
         while True:
             idents,msg = self.session.recv(stream, zmq.NOBLOCK, content=True)
             if msg is None:
                 return
 
             self.log.info("Aborting:")
             self.log.info("%s", msg)
             msg_type = msg['header']['msg_type']
             reply_type = msg_type.split('_')[0] + '_reply'
 
             status = {'status' : 'aborted'}
             md = {'engine' : self.ident}
             md.update(status)
             reply_msg = self.session.send(stream, reply_type, metadata=md,
                         content=status, parent=msg, ident=idents)
             self.log.debug("%s", reply_msg)
             # We need to wait a bit for requests to come in. This can probably
             # be set shorter for true asynchronous clients.
             poller.poll(50)
 
 
     def _no_raw_input(self):
         """Raise StdinNotImplentedError if active frontend doesn't support
         stdin."""
         raise StdinNotImplementedError("raw_input was called, but this "
                                        "frontend does not support stdin.") 
     
     def getpass(self, prompt=''):
         """Forward getpass to frontends
         
         Raises
         ------
         StdinNotImplentedError if active frontend doesn't support stdin.
         """
         if not self._allow_stdin:
             raise StdinNotImplementedError(
                 "getpass was called, but this frontend does not support input requests."
             )
         return self._input_request(prompt,
             self._parent_ident,
             self._parent_header,
             password=True,
         )
     
     def raw_input(self, prompt=''):
         """Forward raw_input to frontends
         
         Raises
         ------
         StdinNotImplentedError if active frontend doesn't support stdin.
         """
         if not self._allow_stdin:
             raise StdinNotImplementedError(
                 "raw_input was called, but this frontend does not support input requests."
             )
         return self._input_request(prompt,
             self._parent_ident,
             self._parent_header,
             password=False,
         )
     
     def _input_request(self, prompt, ident, parent, password=False):
         # Flush output before making the request.
         sys.stderr.flush()
         sys.stdout.flush()
         # flush the stdin socket, to purge stale replies
         while True:
             try:
                 self.stdin_socket.recv_multipart(zmq.NOBLOCK)
             except zmq.ZMQError as e:
                 if e.errno == zmq.EAGAIN:
                     break
                 else:
                     raise
         
         # Send the input request.
         content = json_clean(dict(prompt=prompt, password=password))
         self.session.send(self.stdin_socket, u'input_request', content, parent,
                           ident=ident)
 
         # Await a response.
         while True:
             try:
                 ident, reply = self.session.recv(self.stdin_socket, 0)
             except Exception:
                 self.log.warn("Invalid Message:", exc_info=True)
             except KeyboardInterrupt:
                 # re-raise KeyboardInterrupt, to truncate traceback
                 raise KeyboardInterrupt
             else:
                 break
         try:
             value = py3compat.unicode_to_str(reply['content']['value'])
         except:
             self.log.error("Bad input_reply: %s", parent)
             value = ''
         if value == '\x04':
             # EOF
             raise EOFError
         return value
 
     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.session.send(self.iopub_socket, self._shutdown_message, ident=self._topic('shutdown'))
             self.log.debug("%s", self._shutdown_message)
         [ s.flush(zmq.POLLOUT) for s in self.shell_streams ]
 

IPython/qt/console/frontend_widget.py

@@ -1,825 +1,821 b''
 """Frontend widget for the Qt Console"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 from collections import namedtuple
 import sys
 import uuid
 
 from IPython.external import qt
 from IPython.external.qt import QtCore, QtGui
 from IPython.utils import py3compat
 from IPython.utils.importstring import import_item
 
 from IPython.core.inputsplitter import InputSplitter, IPythonInputSplitter
 from IPython.core.inputtransformer import classic_prompt
 from IPython.core.oinspect import call_tip
 from IPython.qt.base_frontend_mixin import BaseFrontendMixin
 from IPython.utils.traitlets import Any, Bool, Instance, Unicode, DottedObjectName
 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 understands and ignores prompts.
     """
 
     def __init__(self, frontend, lexer=None):
         super(FrontendHighlighter, self).__init__(frontend._control.document(), lexer=lexer)
         self._current_offset = 0
         self._frontend = frontend
         self.highlighting_on = False
 
     def highlightBlock(self, string):
         """ Highlight a block of text. Reimplemented to highlight selectively.
         """
         if not self.highlighting_on:
             return
 
         # The input to this function is a 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
 
         # Only highlight if we can identify a prompt, but make sure not to
         # highlight the prompt.
         if string.startswith(prompt):
             self._current_offset = len(prompt)
             string = string[len(prompt):]
             super(FrontendHighlighter, self).highlightBlock(string)
 
     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
         super(FrontendHighlighter, self).setFormat(start, count, format)
 
 
 class FrontendWidget(HistoryConsoleWidget, BaseFrontendMixin):
     """ A Qt frontend for a generic Python kernel.
     """
 
     # The text to show when the kernel is (re)started.
     banner = Unicode(config=True)
     kernel_banner = Unicode()
 
     # An option and corresponding signal for overriding the default kernel
     # interrupt behavior.
     custom_interrupt = Bool(False)
     custom_interrupt_requested = QtCore.Signal()
 
     # An option and corresponding signals for overriding the default kernel
     # restart behavior.
     custom_restart = Bool(False)
     custom_restart_kernel_died = QtCore.Signal(float)
     custom_restart_requested = QtCore.Signal()
 
     # Whether to automatically show calltips on open-parentheses.
     enable_calltips = Bool(True, config=True,
         help="Whether to draw information calltips on open-parentheses.")
 
     clear_on_kernel_restart = Bool(True, config=True,
         help="Whether to clear the console when the kernel is restarted")
 
     confirm_restart = Bool(True, config=True,
         help="Whether to ask for user confirmation when restarting kernel")
     
     lexer_class = DottedObjectName(config=True,
         help="The pygments lexer class to use."
     )
     def _lexer_class_changed(self, name, old, new):
         lexer_class = import_item(new)
         self.lexer = lexer_class()
     
     def _lexer_class_default(self):
         if py3compat.PY3:
             return 'pygments.lexers.Python3Lexer'
         else:
             return 'pygments.lexers.PythonLexer'
     
     lexer = Any()
     def _lexer_default(self):
         lexer_class = import_item(self.lexer_class)
         return lexer_class()
 
     # Emitted when a user visible 'execute_request' has been submitted to the
     # kernel from the FrontendWidget. Contains the code to be executed.
     executing = QtCore.Signal(object)
 
     # Emitted when a user-visible 'execute_reply' has been received from the
     # kernel and processed by the FrontendWidget. Contains the response message.
     executed = QtCore.Signal(object)
 
     # Emitted when an exit request has been received from the kernel.
     exit_requested = QtCore.Signal(object)
 
     # Protected class variables.
     _prompt_transformer = IPythonInputSplitter(physical_line_transforms=[classic_prompt()],
                                                logical_line_transforms=[],
                                                python_line_transforms=[],
                                               )
     _CallTipRequest = namedtuple('_CallTipRequest', ['id', 'pos'])
     _CompletionRequest = namedtuple('_CompletionRequest', ['id', 'pos'])
     _ExecutionRequest = namedtuple('_ExecutionRequest', ['id', 'kind'])
     _input_splitter_class = InputSplitter
     _local_kernel = False
     _highlighter = Instance(FrontendHighlighter)
 
     #---------------------------------------------------------------------------
     # 'object' interface
     #---------------------------------------------------------------------------
 
     def __init__(self, *args, **kw):
         super(FrontendWidget, self).__init__(*args, **kw)
         # FIXME: remove this when PySide min version is updated past 1.0.7
         # forcefully disable calltips if PySide is < 1.0.7, because they crash
         if qt.QT_API == qt.QT_API_PYSIDE:
             import PySide
             if PySide.__version_info__ < (1,0,7):
                 self.log.warn("PySide %s < 1.0.7 detected, disabling calltips" % PySide.__version__)
                 self.enable_calltips = False
 
         # FrontendWidget protected variables.
         self._bracket_matcher = BracketMatcher(self._control)
         self._call_tip_widget = CallTipWidget(self._control)
         self._completion_lexer = CompletionLexer(self.lexer)
         self._copy_raw_action = QtGui.QAction('Copy (Raw Text)', None)
         self._hidden = False
         self._highlighter = FrontendHighlighter(self, lexer=self.lexer)
         self._input_splitter = self._input_splitter_class()
         self._kernel_manager = None
         self._kernel_client = None
         self._request_info = {}
         self._request_info['execute'] = {};
         self._callback_dict = {}
 
         # 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)
 
         # Set flag for whether we are connected via localhost.
         self._local_kernel = kw.get('local_kernel',
                                     FrontendWidget._local_kernel)
 
         # Whether or not a clear_output call is pending new output.
         self._pending_clearoutput = False
 
     #---------------------------------------------------------------------------
     # 'ConsoleWidget' public interface
     #---------------------------------------------------------------------------
 
     def copy(self):
         """ Copy the currently selected text to the clipboard, removing prompts.
         """
         if self._page_control is not None and self._page_control.hasFocus():
             self._page_control.copy()
         elif self._control.hasFocus():
             text = self._control.textCursor().selection().toPlainText()
             if text:
                 text = self._prompt_transformer.transform_cell(text)
                 QtGui.QApplication.clipboard().setText(text)
         else:
             self.log.debug("frontend widget : unknown copy target")
 
     #---------------------------------------------------------------------------
     # '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.
         """
         self._input_splitter.reset()
         try:
             complete = self._input_splitter.push(source)
         except SyntaxError:
             return True
         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_client.execute(source, hidden)
         self._request_info['execute'][msg_id] = self._ExecutionRequest(msg_id, 'user')
         self._hidden = hidden
         if not hidden:
             self.executing.emit(source)
 
     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.
         """
         # Flush all state from the input splitter so the next round of
         # reading input starts with a clean buffer.
         self._input_splitter.reset()
 
         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 request_interrupt_kernel(self):
         if self._executing:
             self.interrupt_kernel()
 
     def request_restart_kernel(self):
         message = 'Are you sure you want to restart the kernel?'
         self.restart_kernel(message, now=False)
 
     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.request_interrupt_kernel()
                 return True
 
             elif key == QtCore.Qt.Key_Period:
                 self.request_restart_kernel()
                 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_clear_output(self, msg):
         """Handle clear output messages."""
         if not self._hidden and self._is_from_this_session(msg):
             wait = msg['content'].get('wait', True)
             if wait:
                 self._pending_clearoutput = True
             else:
                 self.clear_output()
 
     def _handle_complete_reply(self, rep):
         """ Handle replies for tab completion.
         """
         self.log.debug("complete: %s", rep.get('content', ''))
         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 _silent_exec_callback(self, expr, callback):
         """Silently execute `expr` in the kernel and call `callback` with reply
 
         the `expr` is evaluated silently in the kernel (without) output in
         the frontend. Call `callback` with the
         `repr <http://docs.python.org/library/functions.html#repr> `_ as first argument
 
         Parameters
         ----------
         expr : string
             valid string to be executed by the kernel.
         callback : function
             function accepting one argument, as a string. The string will be
             the `repr` of the result of evaluating `expr`
 
         The `callback` is called with the `repr()` of the result of `expr` as
         first argument. To get the object, do `eval()` on the passed value.
 
         See Also
         --------
         _handle_exec_callback : private method, deal with calling callback with reply
 
         """
 
         # generate uuid, which would be used as an indication of whether or
         # not the unique request originated from here (can use msg id ?)
         local_uuid = str(uuid.uuid1())
         msg_id = self.kernel_client.execute('',
             silent=True, user_expressions={ local_uuid:expr })
         self._callback_dict[local_uuid] = callback
         self._request_info['execute'][msg_id] = self._ExecutionRequest(msg_id, 'silent_exec_callback')
 
     def _handle_exec_callback(self, msg):
         """Execute `callback` corresponding to `msg` reply, after ``_silent_exec_callback``
 
         Parameters
         ----------
         msg : raw message send by the kernel containing an `user_expressions`
                 and having a 'silent_exec_callback' kind.
 
         Notes
         -----
         This function will look for a `callback` associated with the
         corresponding message id. Association has been made by
         `_silent_exec_callback`. `callback` is then called with the `repr()`
         of the value of corresponding `user_expressions` as argument.
         `callback` is then removed from the known list so that any message
         coming again with the same id won't trigger it.
 
         """
 
         user_exp = msg['content'].get('user_expressions')
         if not user_exp:
             return
         for expression in user_exp:
             if expression in self._callback_dict:
                 self._callback_dict.pop(expression)(user_exp[expression])
 
     def _handle_execute_reply(self, msg):
         """ Handles replies for code execution.
         """
         self.log.debug("execute: %s", msg.get('content', ''))
         msg_id = msg['parent_header']['msg_id']
         info = self._request_info['execute'].get(msg_id)
         # unset reading flag, because if execute finished, raw_input can't
         # still be pending.
         self._reading = False
         if info 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_client.iopub_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 == 'aborted':
                 self._process_execute_abort(msg)
 
             self._show_interpreter_prompt_for_reply(msg)
             self.executed.emit(msg)
             self._request_info['execute'].pop(msg_id)
         elif info and info.kind == 'silent_exec_callback' and not self._hidden:
             self._handle_exec_callback(msg)
             self._request_info['execute'].pop(msg_id)
         else:
             super(FrontendWidget, self)._handle_execute_reply(msg)
 
     def _handle_input_request(self, msg):
         """ Handle requests for raw_input.
         """
         self.log.debug("input: %s", msg.get('content', ''))
         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_client.iopub_channel.flush()
 
         def callback(line):
             self.kernel_client.stdin_channel.input(line)
         if self._reading:
             self.log.debug("Got second input request, assuming first was interrupted.")
             self._reading = False
         self._readline(msg['content']['prompt'], callback=callback)
 
     def _kernel_restarted_message(self, died=True):
         msg = "Kernel died, restarting" if died else "Kernel restarting"
         self._append_html("<br>%s<hr><br>" % msg,
             before_prompt=False
         )
 
     def _handle_kernel_died(self, since_last_heartbeat):
         """Handle the kernel's death (if we do not own the kernel).
         """
         self.log.warn("kernel died: %s", since_last_heartbeat)
         if self.custom_restart:
             self.custom_restart_kernel_died.emit(since_last_heartbeat)
         else:
             self._kernel_restarted_message(died=True)
             self.reset()
 
     def _handle_kernel_restarted(self, died=True):
         """Notice that the autorestarter restarted the kernel.
 
         There's nothing to do but show a message.
         """
         self.log.warn("kernel restarted")
         self._kernel_restarted_message(died=died)
         self.reset()
 
     def _handle_inspect_reply(self, rep):
         """Handle replies for call tips."""
         self.log.debug("oinfo: %s", rep.get('content', ''))
         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.
             content = rep['content']
             if content.get('status') == 'ok':
                 self._call_tip_widget.show_inspect_data(content)
 
     def _handle_execute_result(self, msg):
         """ Handle display hook output.
         """
         self.log.debug("execute_result: %s", msg.get('content', ''))
         if not self._hidden and self._is_from_this_session(msg):
             self.flush_clearoutput()
             text = msg['content']['data']
             self._append_plain_text(text + '\n', before_prompt=True)
 
     def _handle_stream(self, msg):
         """ Handle stdout, stderr, and stdin.
         """
         self.log.debug("stream: %s", msg.get('content', ''))
         if not self._hidden and self._is_from_this_session(msg):
             self.flush_clearoutput()
             self.append_stream(msg['content']['data'])
 
     def _handle_shutdown_reply(self, msg):
         """ Handle shutdown signal, only if from other console.
         """
         self.log.warn("shutdown: %s", msg.get('content', ''))
         restart = msg.get('content', {}).get('restart', False)
         if not self._hidden and not self._is_from_this_session(msg):
             # got shutdown reply, request came from session other than ours
             if restart:
                 # someone restarted the kernel, handle it
                 self._handle_kernel_restarted(died=False)
             else:
                 # kernel was shutdown permanently
                 # this triggers exit_requested if the kernel was local,
                 # and a dialog if the kernel was remote,
                 # so we don't suddenly clear the qtconsole without asking.
                 if self._local_kernel:
                     self.exit_requested.emit(self)
                 else:
                     title = self.window().windowTitle()
                     reply = QtGui.QMessageBox.question(self, title,
                         "Kernel has been shutdown permanently. "
                         "Close the Console?",
                         QtGui.QMessageBox.Yes,QtGui.QMessageBox.No)
                     if reply == QtGui.QMessageBox.Yes:
                         self.exit_requested.emit(self)
 
     def _handle_status(self, msg):
         """Handle status message"""
         # This is where a busy/idle indicator would be triggered,
         # when we make one.
         state = msg['content'].get('execution_state', '')
         if state == 'starting':
             # kernel started while we were running
             if self._executing:
                 self._handle_kernel_restarted(died=True)
         elif state == 'idle':
             pass
         elif state == 'busy':
             pass
 
     def _started_channels(self):
         """ Called when the KernelManager channels have started listening or
             when the frontend is assigned an already listening KernelManager.
         """
         self.reset(clear=True)
 
     #---------------------------------------------------------------------------
     # '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(%r)' % path, hidden=hidden)
 
     def interrupt_kernel(self):
         """ Attempts to interrupt the running kernel.
         
         Also unsets _reading flag, to avoid runtime errors
         if raw_input is called again.
         """
         if self.custom_interrupt:
             self._reading = False
             self.custom_interrupt_requested.emit()
         elif self.kernel_manager:
             self._reading = False
             self.kernel_manager.interrupt_kernel()
         else:
             self._append_plain_text('Cannot interrupt a kernel I did not start.\n')
 
     def reset(self, clear=False):
         """ Resets the widget to its initial state if ``clear`` parameter
         is True, otherwise
         prints a visual indication of the fact that the kernel restarted, but
         does not clear the traces from previous usage of the kernel before it
         was restarted.  With ``clear=True``, it is similar to ``%clear``, but
         also re-writes the banner and aborts execution if necessary.
         """
         if self._executing:
             self._executing = False
             self._request_info['execute'] = {}
         self._reading = False
         self._highlighter.highlighting_on = False
 
         if clear:
             self._control.clear()
             self._append_plain_text(self.banner)
             if self.kernel_banner:
                 self._append_plain_text(self.kernel_banner)
                 
         # update output marker for stdout/stderr, so that startup
         # messages appear after banner:
         self._append_before_prompt_pos = self._get_cursor().position()
         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()
             return
 
         if self.kernel_manager:
             # Pause the heart beat channel to prevent further warnings.
             self.kernel_client.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.)
             if self.confirm_restart:
                 buttons = QtGui.QMessageBox.Yes | QtGui.QMessageBox.No
                 result = QtGui.QMessageBox.question(self, 'Restart kernel?',
                                                     message, buttons)
                 do_restart = result == QtGui.QMessageBox.Yes
             else:
                 # confirm_restart is False, so we don't need to ask user
                 # anything, just do the restart
                 do_restart = True
             if do_restart:
                 try:
                     self.kernel_manager.restart_kernel(now=now)
                 except RuntimeError as e:
                     self._append_plain_text(
                         'Error restarting kernel: %s\n' % e,
                         before_prompt=True
                     )
                 else:
                     self._append_html("<br>Restarting kernel...\n<hr><br>",
                         before_prompt=True,
                     )
             else:
                 self.kernel_client.hb_channel.unpause()
 
         else:
             self._append_plain_text(
                 'Cannot restart a Kernel I did not start\n',
                 before_prompt=True
             )
 
     def append_stream(self, text):
         """Appends text to the output stream."""
         # 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 = text.expandtabs(8)
         self._append_plain_text(text, before_prompt=True)
         self._control.moveCursor(QtGui.QTextCursor.End)
 
     def flush_clearoutput(self):
         """If a clearoutput is pending, execute it."""
         if self._pending_clearoutput:
             self._pending_clearoutput = False
             self.clear_output()
 
     def clear_output(self):
         """Clears the current line of output."""
         cursor = self._control.textCursor()
         cursor.beginEditBlock()
         cursor.movePosition(cursor.StartOfLine, cursor.KeepAnchor)
         cursor.insertText('')
         cursor.endEditBlock()
 
     #---------------------------------------------------------------------------
     # '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
         if not self.enable_calltips:
             return False
         cursor_pos = self._get_input_buffer_cursor_pos()
         code = self.input_buffer
         # Send the metadata request to the kernel
         msg_id = self.kernel_client.inspect(code, cursor_pos)
         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_client.complete(
                 code=self.input_buffer,
                 cursor_pos=self._get_input_buffer_cursor_pos(),
             )
             pos = self._get_cursor().position()
             info = self._CompletionRequest(msg_id, pos)
             self._request_info['complete'] = info
 
     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 = 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']
         # If a SystemExit is passed along, this means exit() was called - also
         # all the ipython %exit magic syntax of '-k' to be used to keep
         # the kernel running
         if content['ename']=='SystemExit':
             keepkernel = content['evalue']=='-k' or content['evalue']=='True'
             self._keep_kernel_on_exit = keepkernel
             self.exit_requested.emit(self)
         else:
             traceback = ''.join(content['traceback'])
             self._append_plain_text(traceback)
 
     def _process_execute_ok(self, msg):
         """ Process a reply for a successful execution request.
         """
         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()
 
     #------ Trait default initializers -----------------------------------------
 
     def _banner_default(self):
         """ Returns the standard Python banner.
         """
         banner = 'Python %s on %s\nType "help", "copyright", "credits" or ' \
             '"license" for more information.'
         return banner % (sys.version, sys.platform)

docs/source/development/execution.rst

@@ -1,70 +1,64 b''
 .. _execution_semantics:
 
 Execution semantics in the IPython kernel
 =========================================
 
 The execution of use code consists of the following phases:
 
 1. Fire the ``pre_execute`` event.
 2. Fire the ``pre_run_cell`` event unless silent is True.
 3. Execute the ``code`` field, see below for details.
 4. If execution succeeds, expressions in ``user_expressions`` are computed.
    This ensures that any error in the expressions don't affect the main code execution.
-5. Fire the post_execute eventCall any method registered with :meth:`register_post_execute`.
+5. Fire the post_execute event.
 
-.. warning::
+.. seealso::
+
+    :doc:`config/callbacks`
 
-   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.
 
 
-Errors in any registered post_execute functions are reported,
-and the failing function is removed from the post_execution set so that it does
-not continue triggering failures.
-

docs/source/development/messaging.rst

@@ -1,1052 +1,1052 b''
 .. _messaging:
 
 ======================
  Messaging in IPython
 ======================
 
 
 Versioning
 ==========
 
 The IPython message specification is versioned independently of IPython.
-The current version of the specification is 5.0.0.
+The current version of the specification is 5.0.
 
 
 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:: figs/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. Shell: this single ROUTER socket 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.
 
 2. IOPub: 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 shell socket and its own requests on the stdin 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 shell channel
    to be made available to all clients in a uniform manner.
 
 3. stdin: this ROUTER socket is connected to all frontends, and it allows
    the kernel to request input from the active frontend when :func:`raw_input` is called.
    The frontend that executed the code has a DEALER socket that 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.
 
    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.
 
 4. Control: This channel is identical to Shell, but operates on a separate socket,
    to allow important messages to avoid queueing behind execution requests (e.g. shutdown or abort).
 
 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.
 
 General Message Format
 ======================
 
 A message is defined by the following four-dictionary 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,
                     # All recognized message type strings are listed below.
                     'msg_type' : str,
                     # the message protocol version
-                    'version' : '5.0.0',
+                    'version' : '5.0',
          },
 
       # In a chain of messages, the header from the parent is copied so that
       # clients can track where messages come from.
       'parent_header' : dict,
       
       # Any metadata associated with the message.
       'metadata' : dict,
       
       # The actual content of the message must be a dict, whose structure
       # depends on the message type.
       'content' : dict,
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``version`` key added to the header.
 
 The Wire Protocol
 =================
 
 
 This message format exists at a high level,
 but does not describe the actual *implementation* at the wire level in zeromq.
 The canonical implementation of the message spec is our :class:`~IPython.kernel.zmq.session.Session` class.
 
 .. note::
 
     This section should only be relevant to non-Python consumers of the protocol.
     Python consumers should simply import and use IPython's own implementation of the wire protocol
     in the :class:`IPython.kernel.zmq.session.Session` object.
 
 Every message is serialized to a sequence of at least six blobs of bytes:
 
 .. sourcecode:: python
 
     [
       b'u-u-i-d',         # zmq identity(ies)
       b'<IDS|MSG>',       # delimiter
       b'baddad42',        # HMAC signature
       b'{header}',        # serialized header dict
       b'{parent_header}', # serialized parent header dict
       b'{metadata}',      # serialized metadata dict
       b'{content},        # serialized content dict
       b'blob',            # extra raw data buffer(s)
       ...
     ]
 
 The front of the message is the ZeroMQ routing prefix,
 which can be zero or more socket identities.
 This is every piece of the message prior to the delimiter key ``<IDS|MSG>``.
 In the case of IOPub, there should be just one prefix component,
 which is the topic for IOPub subscribers, e.g. ``execute_result``, ``display_data``.
 
 .. note::
 
     In most cases, the IOPub topics are irrelevant and completely ignored,
     because frontends just subscribe to all topics.
     The convention used in the IPython kernel is to use the msg_type as the topic,
     and possibly extra information about the message, e.g. ``execute_result`` or ``stream.stdout``
 
 After the delimiter is the `HMAC`_ signature of the message, used for authentication.
 If authentication is disabled, this should be an empty string.
 By default, the hashing function used for computing these signatures is sha256.
 
 .. _HMAC: http://en.wikipedia.org/wiki/HMAC
 
 .. note::
 
     To disable authentication and signature checking,
     set the `key` field of a connection file to an empty string.
 
 The signature is the HMAC hex digest of the concatenation of:
 
 - A shared key (typically the ``key`` field of a connection file)
 - The serialized header dict
 - The serialized parent header dict
 - The serialized metadata dict
 - The serialized content dict
 
 In Python, this is implemented via:
 
 .. sourcecode:: python
 
     # once:
     digester = HMAC(key, digestmod=hashlib.sha256)
     
     # for each message
     d = digester.copy()
     for serialized_dict in (header, parent, metadata, content):
         d.update(serialized_dict)
     signature = d.hexdigest()
 
 After the signature is the actual message, always in four frames of bytes.
 The four dictionaries that compose a message are serialized separately,
 in the order of header, parent header, metadata, and content.
 These can be serialized by any function that turns a dict into bytes.
 The default and most common serialization is JSON, but msgpack and pickle
 are common alternatives.
 
 After the serialized dicts are zero to many raw data buffers,
 which can be used by message types that support binary data (mainly apply and data_pub).
 
 
 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.
 
 In addition, the Python implementation of the message specification extends
 messages upon deserialization to the following form for convenience::
 
     {
       'header' : dict,
       # The msg's unique identifier and type are always stored in the header,
       # but the Python implementation copies them to the top level.
       'msg_id' : uuid,
       'msg_type' : str,
       'parent_header' : dict,
       'content' : dict,
       'metadata' : dict,
     }
 
 All messages sent to or received by any IPython process should have this
 extended structure.
 
 
 Messages on the shell ROUTER/DEALER sockets
 ===========================================
 
 .. _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.
     # silent=True forces store_history to be False,
     # and will *not*:
     #   - broadcast output on the IOPUB channel
     #   - have an execute_result
     # The default is False.
     'silent' : bool,
 
     # A boolean flag which, if True, signals the kernel to populate history
     # The default is True if silent is False.  If silent is True, store_history
     # is forced to be False.
     'store_history' : bool,
 
     # A dict mapping names to expressions to be evaluated in the
     # user's dict. The rich display-data representation of each will be evaluated after execution.
     # See the display_data content for the structure of the representation data.
     'user_expressions' : dict,
 
     # Some frontends do not support stdin requests.
     # If raw_input is called from code executed from such a frontend,
     # a StdinNotImplementedError will be raised.
     'allow_stdin' : True,
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``user_variables`` removed, because it is redundant with user_expressions.
 
 The ``code`` field contains a single string (possibly multiline) to be executed.
 
 The ``user_expressions`` field deserves 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 acquired 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 feature, and it should be even possible for different
 frontends to display different prompts while interacting with the same kernel.
 ``user_expressions`` can be used to retrieve this information.
 
 Any error in evaluating any expression in ``user_expressions`` will result in
 only that key containing a standard error message, of the form::
 
     {
         'status' : 'error',
         'ename' : 'NameError',
         'evalue' : 'foo',
         'traceback' : ...
     }
 
 .. Note::
 
    In order to obtain the current execution counter for the purposes of
    displaying input prompts, frontends may make an execution request with an
    empty code string and ``silent=True``.
 
 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.
 
 .. seealso::
 
     :ref:`execution_semantics`
 
 .. _execution_counter:
 
 Execution counter (prompt number)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The kernel should have a single, monotonically increasing counter of all execution
 requests that are made with ``store_history=True``. This counter is used to populate
 the ``In[n]`` and ``Out[n]`` prompts.  The value of this counter will be returned as the
 ``execution_count`` field of all ``execute_reply`` and ``execute_input`` 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 request that 
       # stores history.  This will typically be used by clients to display
       # prompt numbers to the user.  If the request did not store history, 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::
 
     {
       # 'payload' will be a list of payload dicts.
       # Each 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.
       # The only requirement of each payload dict is that it have a 'source' key,
       # which is a string classifying the payload (e.g. 'pager').
       'payload' : list(dict),
 
       # Results for the user_expressions.
       'user_expressions' : dict,
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``user_variables`` is removed, use user_expressions instead.
 
 .. 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 execute_result 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
    has an API for this in the PayloadManager::
 
        ip.payload_manager.write_payload(payload_dict)
 
    which appends a dictionary to the list of payloads.
    
    The payload API is not yet stabilized,
    and should probably not be supported by non-Python kernels at this time.
    In such cases, the payload list should always be empty.
 
    
 When status is 'error', the following extra fields are present::
 
     {
       'ename' : str,   # Exception name, as a string
       'evalue' : 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.
 
 
 Introspection
 -------------
 
 Code can be inspected to show useful information to the user.
 It is up to the Kernel to decide what information should be displayed, and its formatting.
 
 Message type: ``inspect_request``::
 
     content = {
         # The code context in which introspection is requested
         # this may be up to an entire multiline cell.
         'code' : str,
         
         # The cursor position within 'code' (in unicode characters) where inspection is requested
         'cursor_pos' : int,
 
         # The level of detail desired.  In IPython, the default (0) is equivalent to typing
         # 'x?' at the prompt, 1 is equivalent to 'x??'.
         # The difference is up to kernels, but in IPython level 1 includes the source code
         # if available.
         'detail_level' : 0 or 1,
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``object_info_request`` renamed to ``inspect_request``.
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``name`` key replaced with ``code`` and ``cursor_pos``,
     moving the lexing responsibility to the kernel.
 
 The reply is a mime-bundle, like a `display_data`_ message,
 which should be a formatted representation of information about the context.
 In the notebook, this is used to show tooltips over function calls, etc.
 
 Message type: ``inspect_reply``::
 
     content = {
         # 'ok' if the request succeeded or 'error', with error information as in all other replies.
         'status' : 'ok',
         
         # data can be empty if nothing is found
         'data' : dict,
         'metadata' : dict,
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``object_info_reply`` renamed to ``inspect_reply``.
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     Reply is changed from structured data to a mime bundle,  allowing formatting decisions to be made by the kernel.
 
 Completion
 ----------
 
 Message type: ``complete_request``::
 
     content = {
         # The code context in which completion is requested
         # this may be up to an entire multiline cell, such as
         # 'foo = a.isal'
         'code' : str,
         
         # The cursor position within 'code' (in unicode characters) where completion is requested
         'cursor_pos' : int,
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``line``, ``block``, and ``text`` keys are removed in favor of a single ``code`` for context.
     Lexing is up to the kernel.
 
 
 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,
     
     # The range of text that should be replaced by the above matches when a completion is accepted.
     # typically cursor_end is the same as cursor_pos in the request.
     'cursor_start' : int,
     'cursor_end' : int,
     
     # Information that frontend plugins might use for extra display information about completions.
     'metadata' : dict,
     
     # status should be 'ok' unless an exception was raised during the request,
     # in which case it should be 'error', along with the usual error message content
     # in other messages.
     'status' : 'ok'
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``.
     - ``metadata`` is added for extended information.
 
 
 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,
 
       # So far, this can be 'range', 'tail' or 'search'.
       'hist_access_type' : str,
       
       # If hist_access_type is 'range', get a range of input cells. session can
       # be a positive session number, or a negative number to count back from
       # the current session.
       'session' : int,
       # start and stop are line numbers within that session.
       'start' : int,
       'stop' : int,
       
       # If hist_access_type is 'tail' or 'search', get the last n cells.
       'n' : int,
       
       # If hist_access_type is 'search', get cells matching the specified glob
       # pattern (with * and ? as wildcards).
       'pattern' : str,
 
       # If hist_access_type is 'search' and unique is true, do not
       # include duplicated history.  Default is false.
       'unique' : bool,
       
     }
 
 .. versionadded:: 4.0
    The key ``unique`` for ``history_request``.
 
 Message type: ``history_reply``::
 
     content = {
       # A list of 3 tuples, either:
       # (session, line_number, input) or
       # (session, line_number, (input, output)),
       # depending on whether output was False or True, respectively.
       'history' : list,
     }
 
 
 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 shell channel) to connect to a kernel.
 
 Message type: ``connect_request``::
 
     content = {
     }
 
 Message type: ``connect_reply``::
 
     content = {
         'shell_port' : int,   # The port the shell ROUTER socket is listening on.
         'iopub_port' : int,   # The port the PUB socket is listening on.
         'stdin_port' : int,   # The port the stdin ROUTER socket is listening on.
         'hb_port' : int,      # The port the heartbeat socket is listening on.
     }
 
 
 Kernel info
 -----------
 
 If a client needs to know information about the kernel, it can
 make a request of the kernel's information.
 This message can be used to fetch core information of the
 kernel, including language (e.g., Python), language version number and
 IPython version number, and the IPython message spec version number.
 
 Message type: ``kernel_info_request``::
 
     content = {
     }
 
 Message type: ``kernel_info_reply``::
 
     content = {
         # Version of messaging protocol.
         # The first integer indicates major version.  It is incremented when
         # there is any backward incompatible change.
         # The second integer indicates minor version.  It is incremented when
         # there is any backward compatible change.
         'protocol_version': 'X.Y.Z',
 
         # The kernel implementation name
         # (e.g. 'ipython' for the IPython kernel)
         'implementation': str,
 
         # Implementation version number.
         # The version number of the kernel's implementation
         # (e.g. IPython.__version__ for the IPython kernel)
         'implementation_version': 'X.Y.Z', 
 
         # Programming language in which kernel is implemented.
         # Kernel included in IPython returns 'python'.
         'language': str,
         
         # Language version number.
         # It is Python version number (e.g., '2.7.3') for the kernel
         # included in IPython.
         'language_version': 'X.Y.Z',
 
         # A banner of information about the kernel,
         # which may be desplayed in console environments.
         'banner' : str,
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     Versions changed from lists of integers to strings.
     
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``ipython_version`` is removed.
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``implementation``, ``implementation_version``, and ``banner`` keys are added.
 
 
 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.
 
 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 'stdout', 'stderr'
         'name' : str,
     
         # The data is an arbitrary string to be written to that stream
         'data' : str,
     }
 
 Display Data
 ------------
 
 This type of message is used to bring back data that should be displayed (text,
 html, svg, etc.) in the frontends. This data is published to all frontends.
 Each message can have multiple representations of the data; it is up to the
 frontend to decide which to use and how. A single message should contain all
 possible representations of the same information. Each representation should
 be a JSON'able data structure, and should be a valid MIME type.
 
 Some questions remain about this design:
 
 * Do we use this message type for execute_result/displayhook? Probably not, because
   the displayhook also has to handle the Out prompt display. On the other hand
   we could put that information into the metadata section.
 
 .. _display_data:
 
 Message type: ``display_data``::
 
     content = {
 
         # Who create the data
         'source' : str,
 
         # The data dict contains key/value pairs, where the keys are MIME
         # types and the values are the raw data of the representation in that
         # format.
         'data' : dict,
 
         # Any metadata that describes the data
         'metadata' : dict
     }
 
 
 The ``metadata`` contains any metadata that describes the output.
 Global keys are assumed to apply to the output as a whole.
 The ``metadata`` dict can also contain mime-type keys, which will be sub-dictionaries,
 which are interpreted as applying only to output of that type.
 Third parties should put any data they write into a single dict
 with a reasonably unique name to avoid conflicts.
 
 The only metadata keys currently defined in IPython are the width and height
 of images::
 
     metadata = {
       'image/png' : {
         'width': 640,
         'height': 480
       }
     }
 
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     `application/json` data should be unpacked JSON data,
     not double-serialized as a JSON string.
 
 
 Raw Data Publication
 --------------------
 
 ``display_data`` lets you publish *representations* of data, such as images and html.
 This ``data_pub`` message lets you publish *actual raw data*, sent via message buffers.
 
 data_pub messages are constructed via the :func:`IPython.lib.datapub.publish_data` function:
 
 .. sourcecode:: python
 
     from IPython.kernel.zmq.datapub import publish_data
     ns = dict(x=my_array)
     publish_data(ns)
 
 
 Message type: ``data_pub``::
 
     content = {
         # the keys of the data dict, after it has been unserialized
         'keys' : ['a', 'b']
     }
     # the namespace dict will be serialized in the message buffers,
     # which will have a length of at least one
     buffers = [b'pdict', ...]
 
 
 The interpretation of a sequence of data_pub messages for a given parent request should be
 to update a single namespace with subsequent results.
 
 .. note::
 
     No frontends directly handle data_pub messages at this time.
     It is currently only used by the client/engines in :mod:`IPython.parallel`,
     where engines may publish *data* to the Client,
     of which the Client can then publish *representations* via ``display_data``
     to various frontends.
 
 Code inputs
 -----------
 
 To let all frontends know what code is being executed at any given time, these
 messages contain a re-broadcast of the ``code`` portion of an
 :ref:`execute_request <execute>`, along with the :ref:`execution_count
 <execution_counter>`.
 
 Message type: ``execute_input``::
 
     content = {
         'code' : str,  # Source code to be executed, one or more lines
 
         # The counter for this execution is also provided so that clients can
         # display it, since IPython automatically creates variables called _iN
         # (for input prompt In[N]).
         'execution_count' : int
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``pyin`` is renamed to ``execute_input``.
 
 
 Execution results
 -----------------
 
 Results of an execution are published as an ``execute_result``.
 These are identical to `display_data`_ messages, with the addition of an ``execution_count`` key.
 
 Results can have multiple simultaneous formats depending on its
 configuration. A plain text representation should always be provided
 in the ``text/plain`` mime-type. Frontends are free to display any or all of these
 according to its capabilities.
 Frontends should ignore mime-types they do not understand. The data itself is
 any JSON object and depends on the format. It is often, but not always a string.
 
 Message type: ``execute_result``::
 
     content = {
 
         # 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,
 
         # data and metadata are identical to a display_data message.
         # the object being displayed is that passed to the display hook,
         # i.e. the *result* of the execution.
         'data' : dict,
         'metadata' : dict,
     }
 
 Execution errors
 ----------------
 
 When an error occurs during code execution
 
 Message type: ``error``::
 
     content = {
        # Similar content to the execute_reply messages for the 'error' case,
        # except the 'status' field is omitted.
     }
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``pyerr`` renamed to ``error``
 
 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.
         # The kernel will publish state 'starting' exactly once at process startup.
         execution_state : ('busy', 'idle', 'starting')
     }
 
 Clear output
 ------------
 
 This message type is used to clear the output that is visible on the frontend.
 
 Message type: ``clear_output``::
 
     content = {
 
         # Wait to clear the output until new output is available.  Clears the
         # existing output immediately before the new output is displayed.  
         # Useful for creating simple animations with minimal flickering.
         'wait' : bool,
     }
 
 .. versionchanged:: 4.1
 
     ``stdout``, ``stderr``, and ``display`` boolean keys for selective clearing are removed,
     and ``wait`` is added.
     The selective clearing keys are ignored in v4 and the default behavior remains the same,
     so v4 clear_output messages will be safely handled by a v4.1 frontend.
 
 
 Messages on the stdin ROUTER/DEALER sockets
 ===========================================
 
 This is a socket where the request/reply pattern 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. The request should be made to the frontend that
 made the execution request that prompted ``raw_input`` to be called. For now we
 will keep these messages as simple as possible, since they only mean to convey
 the ``raw_input(prompt)`` call.
 
 Message type: ``input_request``::
 
     content = {
         # the text to show at the prompt
         'prompt' : str,
         # Is the request for a password?
         # If so, the frontend shouldn't echo input.
         'password' : bool
     }
 
 Message type: ``input_reply``::
 
     content = { 'value' : str }
 
 
 When ``password`` is True, the frontend should not echo the input as it is entered.
 
-.. versionchanged:: 5.0.0
+.. versionchanged:: 5.0
 
     ``password`` key added.
 
 .. note::
 
     The stdin socket of the client is required to have the same zmq IDENTITY
     as the client's shell socket.
     Because of this, the ``input_request`` must be sent with the same IDENTITY
     routing prefix as the ``execute_reply`` in order for the frontend to receive
     the message.
 
 .. 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
 =====================
 
 Clients send ping messages on a REQ socket, which are echoed right back
 from the Kernel's REP socket. These are simple bytestrings, not full JSON messages described above.
 
 
 Custom Messages
 ===============
 
 .. versionadded:: 4.1
 
 IPython 2.0 (msgspec v4.1) adds a messaging system for developers to add their own objects with Frontend
 and Kernel-side components, and allow them to communicate with each other.
 To do this, IPython adds a notion of a ``Comm``, which exists on both sides,
 and can communicate in either direction.
 
 These messages are fully symmetrical - both the Kernel and the Frontend can send each message,
 and no messages expect a reply.
 The Kernel listens for these messages on the Shell channel,
 and the Frontend listens for them on the IOPub channel.
 
 Opening a Comm
 --------------
 
 Opening a Comm produces a ``comm_open`` message, to be sent to the other side::
 
     {
       'comm_id' : 'u-u-i-d',
       'target_name' : 'my_comm',
       'data' : {}
     }
 
 Every Comm has an ID and a target name.
 The code handling the message on the receiving side is responsible for maintaining a mapping
 of target_name keys to constructors.
 After a ``comm_open`` message has been sent,
 there should be a corresponding Comm instance on both sides.
 The ``data`` key is always a dict and can be any extra JSON information used in initialization of the comm.
 
 If the ``target_name`` key is not found on the receiving side,
 then it should immediately reply with a ``comm_close`` message to avoid an inconsistent state.
 
 Comm Messages
 -------------
 
 Comm messages are one-way communications to update comm state,
 used for synchronizing widget state, or simply requesting actions of a comm's counterpart.
 
 Essentially, each comm pair defines their own message specification implemented inside the ``data`` dict.
 
 There are no expected replies (of course, one side can send another ``comm_msg`` in reply).
 
 Message type: ``comm_msg``::
 
     {
       'comm_id' : 'u-u-i-d',
       'data' : {}
     }
 
 Tearing Down Comms
 ------------------
 
 Since comms live on both sides, when a comm is destroyed the other side must be notified.
 This is done with a ``comm_close`` message.
 
 Message type: ``comm_close``::
 
     {
       'comm_id' : 'u-u-i-d',
       'data' : {}
     }
 
 Output Side Effects
 -------------------
 
 Since comm messages can execute arbitrary user code,
 handlers should set the parent header and publish status busy / idle,
 just like an execute request.
 
 
 To Do
 =====
 
 Missing things include:
 
 * Important: finish thinking through the payload concept and API.
 
 .. include:: ../links.txt