Four possible states for completion reply, & indent hint

IPython/core/inputsplitter.py

@@ -1,654 +1,679 b''
 """Input handling and transformation machinery.
 
 The first class in this module, :class:`InputSplitter`, is designed to tell when
 input from a line-oriented frontend is complete and should be executed, and when
 the user should be prompted for another line of code instead. The name 'input
 splitter' is largely for historical reasons.
 
 A companion, :class:`IPythonInputSplitter`, provides the same functionality but
 with full support for the extended IPython syntax (magics, system calls, etc).
 The code to actually do these transformations is in :mod:`IPython.core.inputtransformer`.
 :class:`IPythonInputSplitter` feeds the raw code to the transformers in order
 and stores the results.
 
 For more details, see the class docstrings below.
 
 Authors
 -------
 
 * Fernando Perez
 * Brian Granger
 * Thomas Kluyver
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 # stdlib
 import ast
 import codeop
 import re
 import sys
 
 # IPython modules
 from IPython.utils.py3compat import cast_unicode
 from IPython.core.inputtransformer import (leading_indent,
                                            classic_prompt,
                                            ipy_prompt,
                                            strip_encoding_cookie,
                                            cellmagic,
                                            assemble_logical_lines,
                                            help_end,
                                            escaped_commands,
                                            assign_from_magic,
                                            assign_from_system,
                                            assemble_python_lines,
                                            )
 
 # These are available in this module for backwards compatibility.
 from IPython.core.inputtransformer import (ESC_SHELL, ESC_SH_CAP, ESC_HELP,
                                         ESC_HELP2, ESC_MAGIC, ESC_MAGIC2,
                                         ESC_QUOTE, ESC_QUOTE2, ESC_PAREN, ESC_SEQUENCES)
 
 #-----------------------------------------------------------------------------
 # Utilities
 #-----------------------------------------------------------------------------
 
 # FIXME: These are general-purpose utilities that later can be moved to the
 # general ward.  Kept here for now because we're being very strict about test
 # coverage with this code, and this lets us ensure that we keep 100% coverage
 # while developing.
 
 # compiled regexps for autoindent management
 dedent_re = re.compile('|'.join([
     r'^\s+raise(\s.*)?$', # raise statement (+ space + other stuff, maybe)
     r'^\s+raise\([^\)]*\).*$', # wacky raise with immediate open paren
     r'^\s+return(\s.*)?$', # normal return (+ space + other stuff, maybe)
     r'^\s+return\([^\)]*\).*$', # wacky return with immediate open paren
     r'^\s+pass\s*$', # pass (optionally followed by trailing spaces)
     r'^\s+break\s*$', # break (optionally followed by trailing spaces)
     r'^\s+continue\s*$', # continue (optionally followed by trailing spaces)
 ]))
 ini_spaces_re = re.compile(r'^([ \t\r\f\v]+)')
 
 # regexp to match pure comment lines so we don't accidentally insert 'if 1:'
 # before pure comments
 comment_line_re = re.compile('^\s*\#')
 
 
 def num_ini_spaces(s):
     """Return the number of initial spaces in a string.
 
     Note that tabs are counted as a single space.  For now, we do *not* support
     mixing of tabs and spaces in the user's input.
 
     Parameters
     ----------
     s : string
 
     Returns
     -------
     n : int
     """
 
     ini_spaces = ini_spaces_re.match(s)
     if ini_spaces:
         return ini_spaces.end()
     else:
         return 0
 
 def last_blank(src):
     """Determine if the input source ends in a blank.
 
     A blank is either a newline or a line consisting of whitespace.
 
     Parameters
     ----------
     src : string
       A single or multiline string.
     """
     if not src: return False
     ll  = src.splitlines()[-1]
     return (ll == '') or ll.isspace()
 
 
 last_two_blanks_re = re.compile(r'\n\s*\n\s*$', re.MULTILINE)
 last_two_blanks_re2 = re.compile(r'.+\n\s*\n\s+$', re.MULTILINE)
 
 def last_two_blanks(src):
     """Determine if the input source ends in two blanks.
 
     A blank is either a newline or a line consisting of whitespace.
 
     Parameters
     ----------
     src : string
       A single or multiline string.
     """
     if not src: return False
     # The logic here is tricky: I couldn't get a regexp to work and pass all
     # the tests, so I took a different approach: split the source by lines,
     # grab the last two and prepend '###\n' as a stand-in for whatever was in
     # the body before the last two lines.  Then, with that structure, it's
     # possible to analyze with two regexps.  Not the most elegant solution, but
     # it works.  If anyone tries to change this logic, make sure to validate
     # the whole test suite first!
     new_src = '\n'.join(['###\n'] + src.splitlines()[-2:])
     return (bool(last_two_blanks_re.match(new_src)) or
             bool(last_two_blanks_re2.match(new_src)) )
 
 
 def remove_comments(src):
     """Remove all comments from input source.
 
     Note: comments are NOT recognized inside of strings!
 
     Parameters
     ----------
     src : string
       A single or multiline input string.
 
     Returns
     -------
     String with all Python comments removed.
     """
 
     return re.sub('#.*', '', src)
 
 
 def get_input_encoding():
     """Return the default standard input encoding.
 
     If sys.stdin has no encoding, 'ascii' is returned."""
     # There are strange environments for which sys.stdin.encoding is None. We
     # ensure that a valid encoding is returned.
     encoding = getattr(sys.stdin, 'encoding', None)
     if encoding is None:
         encoding = 'ascii'
     return encoding
 
 #-----------------------------------------------------------------------------
 # Classes and functions for normal Python syntax handling
 #-----------------------------------------------------------------------------
 
 class InputSplitter(object):
     r"""An object that can accumulate lines of Python source before execution.
 
     This object is designed to be fed python source line-by-line, using
     :meth:`push`. It will return on each push whether the currently pushed
     code could be executed already. In addition, it provides a method called
     :meth:`push_accepts_more` that can be used to query whether more input
     can be pushed into a single interactive block.
 
     This is a simple example of how an interactive terminal-based client can use
     this tool::
 
         isp = InputSplitter()
         while isp.push_accepts_more():
             indent = ' '*isp.indent_spaces
             prompt = '>>> ' + indent
             line = indent + raw_input(prompt)
             isp.push(line)
         print 'Input source was:\n', isp.source_reset(),
     """
     # Number of spaces of indentation computed from input that has been pushed
     # so far.  This is the attributes callers should query to get the current
     # indentation level, in order to provide auto-indent facilities.
     indent_spaces = 0
     # String, indicating the default input encoding.  It is computed by default
     # at initialization time via get_input_encoding(), but it can be reset by a
     # client with specific knowledge of the encoding.
     encoding = ''
     # String where the current full source input is stored, properly encoded.
     # Reading this attribute is the normal way of querying the currently pushed
     # source code, that has been properly encoded.
     source = ''
     # Code object corresponding to the current source.  It is automatically
     # synced to the source, so it can be queried at any time to obtain the code
     # object; it will be None if the source doesn't compile to valid Python.
     code = None
 
     # Private attributes
 
     # List with lines of input accumulated so far
     _buffer = None
     # Command compiler
     _compile = None
     # Mark when input has changed indentation all the way back to flush-left
     _full_dedent = False
     # Boolean indicating whether the current block is complete
     _is_complete = None
+    # Boolean indicating whether the current block has an unrecoverable syntax error
+    _is_invalid = False
 
     def __init__(self):
         """Create a new InputSplitter instance.
         """
         self._buffer = []
         self._compile = codeop.CommandCompiler()
         self.encoding = get_input_encoding()
 
     def reset(self):
         """Reset the input buffer and associated state."""
         self.indent_spaces = 0
         self._buffer[:] = []
         self.source = ''
         self.code = None
         self._is_complete = False
+        self._is_invalid = False
         self._full_dedent = False
 
     def source_reset(self):
         """Return the input source and perform a full reset.
         """
         out = self.source
         self.reset()
         return out
 
-    def is_complete(self, source):
+    def check_complete(self, source):
         """Return whether a block of code is ready to execute, or should be continued
         
         This is a non-stateful API, and will reset the state of this InputSplitter.
+        
+        Parameters
+        ----------
+        source : string
+          Python input code, which can be multiline.
+        
+        Returns
+        -------
+        status : str
+          One of 'complete', 'incomplete', or 'invalid' if source is not a
+          prefix of valid code.
+        indent_spaces : int or None
+          The number of spaces by which to indent the next line of code. If
+          status is not 'incomplete', this is None.
         """
         self.reset()
         try:
             self.push(source)
-            return not self.push_accepts_more()
         except SyntaxError:
             # Transformers in IPythonInputSplitter can raise SyntaxError,
             # which push() will not catch.
-            return True
+            return 'invalid', None
+        else:
+            if self._is_invalid:
+                return 'invalid', None
+            elif self.push_accepts_more():
+                return 'incomplete', self.indent_spaces
+            else:
+                return 'complete', None
         finally:
             self.reset()
 
     def push(self, lines):
         """Push one or more lines of input.
 
         This stores the given lines and returns a status code indicating
         whether the code forms a complete Python block or not.
 
         Any exceptions generated in compilation are swallowed, but if an
         exception was produced, the method returns True.
 
         Parameters
         ----------
         lines : string
           One or more lines of Python input.
 
         Returns
         -------
         is_complete : boolean
           True if the current input source (the result of the current input
           plus prior inputs) forms a complete Python execution block.  Note that
           this value is also stored as a private attribute (``_is_complete``), so it
           can be queried at any time.
         """
         self._store(lines)
         source = self.source
 
         # Before calling _compile(), reset the code object to None so that if an
         # exception is raised in compilation, we don't mislead by having
         # inconsistent code/source attributes.
         self.code, self._is_complete = None, None
+        self._is_invalid = False
 
         # Honor termination lines properly
         if source.endswith('\\\n'):
             return False
 
         self._update_indent(lines)
         try:
             self.code = self._compile(source, symbol="exec")
         # Invalid syntax can produce any of a number of different errors from
         # inside the compiler, so we have to catch them all.  Syntax errors
         # immediately produce a 'ready' block, so the invalid Python can be
         # sent to the kernel for evaluation with possible ipython
         # special-syntax conversion.
         except (SyntaxError, OverflowError, ValueError, TypeError,
                 MemoryError):
             self._is_complete = True
+            self._is_invalid = True
         else:
             # Compilation didn't produce any exceptions (though it may not have
             # given a complete code object)
             self._is_complete = self.code is not None
 
         return self._is_complete
 
     def push_accepts_more(self):
         """Return whether a block of interactive input can accept more input.
 
         This method is meant to be used by line-oriented frontends, who need to
         guess whether a block is complete or not based solely on prior and
         current input lines.  The InputSplitter considers it has a complete
         interactive block and will not accept more input when either:
         
         * A SyntaxError is raised
 
         * The code is complete and consists of a single line or a single
           non-compound statement
 
         * The code is complete and has a blank line at the end
 
         If the current input produces a syntax error, this method immediately
         returns False but does *not* raise the syntax error exception, as
         typically clients will want to send invalid syntax to an execution
         backend which might convert the invalid syntax into valid Python via
         one of the dynamic IPython mechanisms.
         """
 
         # With incomplete input, unconditionally accept more
         # A syntax error also sets _is_complete to True - see push()
         if not self._is_complete:
             #print("Not complete")  # debug
             return True
         
         # The user can make any (complete) input execute by leaving a blank line
         last_line = self.source.splitlines()[-1]
         if (not last_line) or last_line.isspace():
             #print("Blank line")  # debug
             return False
         
         # If there's just a single line or AST node, and we're flush left, as is
         # the case after a simple statement such as 'a=1', we want to execute it
         # straight away.
         if self.indent_spaces==0:
             if len(self.source.splitlines()) <= 1:
                 return False
             
             try:
                 code_ast = ast.parse(u''.join(self._buffer))
             except Exception:
                 #print("Can't parse AST")  # debug
                 return False
             else:
                 if len(code_ast.body) == 1 and \
                                     not hasattr(code_ast.body[0], 'body'):
                     #print("Simple statement")  # debug
                     return False
 
         # General fallback - accept more code
         return True
 
     #------------------------------------------------------------------------
     # Private interface
     #------------------------------------------------------------------------
 
     def _find_indent(self, line):
         """Compute the new indentation level for a single line.
 
         Parameters
         ----------
         line : str
           A single new line of non-whitespace, non-comment Python input.
 
         Returns
         -------
         indent_spaces : int
           New value for the indent level (it may be equal to self.indent_spaces
         if indentation doesn't change.
 
         full_dedent : boolean
           Whether the new line causes a full flush-left dedent.
         """
         indent_spaces = self.indent_spaces
         full_dedent = self._full_dedent
 
         inisp = num_ini_spaces(line)
         if inisp < indent_spaces:
             indent_spaces = inisp
             if indent_spaces <= 0:
                 #print 'Full dedent in text',self.source # dbg
                 full_dedent = True
 
         if line.rstrip()[-1] == ':':
             indent_spaces += 4
         elif dedent_re.match(line):
             indent_spaces -= 4
             if indent_spaces <= 0:
                 full_dedent = True
 
         # Safety
         if indent_spaces < 0:
             indent_spaces = 0
             #print 'safety' # dbg
 
         return indent_spaces, full_dedent
 
     def _update_indent(self, lines):
         for line in remove_comments(lines).splitlines():
             if line and not line.isspace():
                 self.indent_spaces, self._full_dedent = self._find_indent(line)
 
     def _store(self, lines, buffer=None, store='source'):
         """Store one or more lines of input.
 
         If input lines are not newline-terminated, a newline is automatically
         appended."""
 
         if buffer is None:
             buffer = self._buffer
 
         if lines.endswith('\n'):
             buffer.append(lines)
         else:
             buffer.append(lines+'\n')
         setattr(self, store, self._set_source(buffer))
 
     def _set_source(self, buffer):
         return u''.join(buffer)
 
 
 class IPythonInputSplitter(InputSplitter):
     """An input splitter that recognizes all of IPython's special syntax."""
 
     # String with raw, untransformed input.
     source_raw = ''
     
     # Flag to track when a transformer has stored input that it hasn't given
     # back yet.
     transformer_accumulating = False
     
     # Flag to track when assemble_python_lines has stored input that it hasn't
     # given back yet.
     within_python_line = False
 
     # Private attributes
 
     # List with lines of raw input accumulated so far.
     _buffer_raw = None
 
     def __init__(self, line_input_checker=True, physical_line_transforms=None,
                     logical_line_transforms=None, python_line_transforms=None):
         super(IPythonInputSplitter, self).__init__()
         self._buffer_raw = []
         self._validate = True
         
         if physical_line_transforms is not None:
             self.physical_line_transforms = physical_line_transforms
         else:
             self.physical_line_transforms = [
                                              leading_indent(),
                                              classic_prompt(),
                                              ipy_prompt(),
                                              strip_encoding_cookie(),
                                              cellmagic(end_on_blank_line=line_input_checker),
                                             ]
         
         self.assemble_logical_lines = assemble_logical_lines()
         if logical_line_transforms is not None:
             self.logical_line_transforms = logical_line_transforms
         else:
             self.logical_line_transforms = [
                                             help_end(),
                                             escaped_commands(),
                                             assign_from_magic(),
                                             assign_from_system(),
                                            ]
         
         self.assemble_python_lines = assemble_python_lines()
         if python_line_transforms is not None:
             self.python_line_transforms = python_line_transforms
         else:
             # We don't use any of these at present
             self.python_line_transforms = []
     
     @property
     def transforms(self):
         "Quick access to all transformers."
         return self.physical_line_transforms + \
             [self.assemble_logical_lines] + self.logical_line_transforms + \
             [self.assemble_python_lines]  + self.python_line_transforms
     
     @property
     def transforms_in_use(self):
         """Transformers, excluding logical line transformers if we're in a
         Python line."""
         t = self.physical_line_transforms[:]
         if not self.within_python_line:
             t += [self.assemble_logical_lines] + self.logical_line_transforms
         return t + [self.assemble_python_lines] + self.python_line_transforms
 
     def reset(self):
         """Reset the input buffer and associated state."""
         super(IPythonInputSplitter, self).reset()
         self._buffer_raw[:] = []
         self.source_raw = ''
         self.transformer_accumulating = False
         self.within_python_line = False
 
         for t in self.transforms:
             try:
                 t.reset()
             except SyntaxError:
                 # Nothing that calls reset() expects to handle transformer
                 # errors
                 pass
     
     def flush_transformers(self):
         def _flush(transform, out):
             if out is not None:
                 tmp = transform.push(out)
                 return tmp or transform.reset() or None
             else:
                 return transform.reset() or None
         
         out = None
         for t in self.transforms_in_use:
             out = _flush(t, out)
         
         if out is not None:
             self._store(out)
 
     def raw_reset(self):
         """Return raw input only and perform a full reset.
         """
         out = self.source_raw
         self.reset()
         return out
     
     def source_reset(self):
         try:
             self.flush_transformers()
             return self.source
         finally:
             self.reset()
 
     def push_accepts_more(self):
         if self.transformer_accumulating:
             return True
         else:
             return super(IPythonInputSplitter, self).push_accepts_more()
 
     def transform_cell(self, cell):
         """Process and translate a cell of input.
         """
         self.reset()
         try:
             self.push(cell)
             self.flush_transformers()
             return self.source
         finally:
             self.reset()
 
     def push(self, lines):
         """Push one or more lines of IPython input.
 
         This stores the given lines and returns a status code indicating
         whether the code forms a complete Python block or not, after processing
         all input lines for special IPython syntax.
 
         Any exceptions generated in compilation are swallowed, but if an
         exception was produced, the method returns True.
 
         Parameters
         ----------
         lines : string
           One or more lines of Python input.
 
         Returns
         -------
         is_complete : boolean
           True if the current input source (the result of the current input
           plus prior inputs) forms a complete Python execution block.  Note that
           this value is also stored as a private attribute (_is_complete), so it
           can be queried at any time.
         """
 
         # We must ensure all input is pure unicode
         lines = cast_unicode(lines, self.encoding)
         
         # ''.splitlines() --> [], but we need to push the empty line to transformers
         lines_list = lines.splitlines()
         if not lines_list:
             lines_list = ['']
 
         # Store raw source before applying any transformations to it.  Note
         # that this must be done *after* the reset() call that would otherwise
         # flush the buffer.
         self._store(lines, self._buffer_raw, 'source_raw')
 
         for line in lines_list:
             out = self.push_line(line)
 
         return out
     
     def push_line(self, line):
         buf = self._buffer
         
         def _accumulating(dbg):
             #print(dbg)
             self.transformer_accumulating = True
             return False
         
         for transformer in self.physical_line_transforms:
             line = transformer.push(line)
             if line is None:
                 return _accumulating(transformer)
         
         if not self.within_python_line:
             line = self.assemble_logical_lines.push(line)
             if line is None:
                 return _accumulating('acc logical line')        
         
             for transformer in self.logical_line_transforms:
                 line = transformer.push(line)
                 if line is None:
                     return _accumulating(transformer)
         
         line = self.assemble_python_lines.push(line)
         if line is None:
             self.within_python_line = True
             return _accumulating('acc python line')
         else:
             self.within_python_line = False
         
         for transformer in self.python_line_transforms:
             line = transformer.push(line)
             if line is None:
                 return _accumulating(transformer)
 
         #print("transformers clear") #debug
         self.transformer_accumulating = False
         return super(IPythonInputSplitter, self).push(line)

IPython/core/tests/test_inputsplitter.py

@@ -1,592 +1,592 b''
 # -*- coding: utf-8 -*-
 """Tests for the inputsplitter module.
 
 Authors
 -------
 * Fernando Perez
 * Robert Kern
 """
 from __future__ import print_function
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010-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
 #-----------------------------------------------------------------------------
 # stdlib
 import unittest
 import sys
 
 # Third party
 import nose.tools as nt
 
 # Our own
 from IPython.core import inputsplitter as isp
 from IPython.core.tests.test_inputtransformer import syntax, syntax_ml
 from IPython.testing import tools as tt
 from IPython.utils import py3compat
 from IPython.utils.py3compat import string_types, input
 
 #-----------------------------------------------------------------------------
 # Semi-complete examples (also used as tests)
 #-----------------------------------------------------------------------------
 
 # Note: at the bottom, there's a slightly more complete version of this that
 # can be useful during development of code here.
 
 def mini_interactive_loop(input_func):
     """Minimal example of the logic of an interactive interpreter loop.
 
     This serves as an example, and it is used by the test system with a fake
     raw_input that simulates interactive input."""
 
     from IPython.core.inputsplitter import InputSplitter
 
     isp = InputSplitter()
     # In practice, this input loop would be wrapped in an outside loop to read
     # input indefinitely, until some exit/quit command was issued.  Here we
     # only illustrate the basic inner loop.
     while isp.push_accepts_more():
         indent = ' '*isp.indent_spaces
         prompt = '>>> ' + indent
         line = indent + input_func(prompt)
         isp.push(line)
 
     # Here we just return input so we can use it in a test suite, but a real
     # interpreter would instead send it for execution somewhere.
     src = isp.source_reset()
     #print 'Input source was:\n', src  # dbg
     return src
 
 #-----------------------------------------------------------------------------
 # Test utilities, just for local use
 #-----------------------------------------------------------------------------
 
 def assemble(block):
     """Assemble a block into multi-line sub-blocks."""
     return ['\n'.join(sub_block)+'\n' for sub_block in block]
 
 
 def pseudo_input(lines):
     """Return a function that acts like raw_input but feeds the input list."""
     ilines = iter(lines)
     def raw_in(prompt):
         try:
             return next(ilines)
         except StopIteration:
             return ''
     return raw_in
 
 #-----------------------------------------------------------------------------
 # Tests
 #-----------------------------------------------------------------------------
 def test_spaces():
     tests = [('', 0),
              (' ', 1),
              ('\n', 0),
              (' \n', 1),
              ('x', 0),
              (' x', 1),
              ('  x',2),
              ('    x',4),
              # Note: tabs are counted as a single whitespace!
              ('\tx', 1),
              ('\t x', 2),
              ]
     tt.check_pairs(isp.num_ini_spaces, tests)
 
 
 def test_remove_comments():
     tests = [('text', 'text'),
              ('text # comment', 'text '),
              ('text # comment\n', 'text \n'),
              ('text # comment \n', 'text \n'),
              ('line # c \nline\n','line \nline\n'),
              ('line # c \nline#c2  \nline\nline #c\n\n',
               'line \nline\nline\nline \n\n'),
              ]
     tt.check_pairs(isp.remove_comments, tests)
 
 
 def test_get_input_encoding():
     encoding = isp.get_input_encoding()
     nt.assert_true(isinstance(encoding, string_types))
     # simple-minded check that at least encoding a simple string works with the
     # encoding we got.
     nt.assert_equal(u'test'.encode(encoding), b'test')
 
 
 class NoInputEncodingTestCase(unittest.TestCase):
     def setUp(self):
         self.old_stdin = sys.stdin
         class X: pass
         fake_stdin = X()
         sys.stdin = fake_stdin
 
     def test(self):
         # Verify that if sys.stdin has no 'encoding' attribute we do the right
         # thing
         enc = isp.get_input_encoding()
         self.assertEqual(enc, 'ascii')
 
     def tearDown(self):
         sys.stdin = self.old_stdin
 
 
 class InputSplitterTestCase(unittest.TestCase):
     def setUp(self):
         self.isp = isp.InputSplitter()
 
     def test_reset(self):
         isp = self.isp
         isp.push('x=1')
         isp.reset()
         self.assertEqual(isp._buffer, [])
         self.assertEqual(isp.indent_spaces, 0)
         self.assertEqual(isp.source, '')
         self.assertEqual(isp.code, None)
         self.assertEqual(isp._is_complete, False)
 
     def test_source(self):
         self.isp._store('1')
         self.isp._store('2')
         self.assertEqual(self.isp.source, '1\n2\n')
         self.assertTrue(len(self.isp._buffer)>0)
         self.assertEqual(self.isp.source_reset(), '1\n2\n')
         self.assertEqual(self.isp._buffer, [])
         self.assertEqual(self.isp.source, '')
 
     def test_indent(self):
         isp = self.isp # shorthand
         isp.push('x=1')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\n    x=1')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('y=2\n')
         self.assertEqual(isp.indent_spaces, 0)
 
     def test_indent2(self):
         isp = self.isp
         isp.push('if 1:')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('    x=1')
         self.assertEqual(isp.indent_spaces, 4)
         # Blank lines shouldn't change the indent level
         isp.push(' '*2)
         self.assertEqual(isp.indent_spaces, 4)
 
     def test_indent3(self):
         isp = self.isp
         # When a multiline statement contains parens or multiline strings, we
         # shouldn't get confused.
         isp.push("if 1:")
         isp.push("    x = (1+\n    2)")
         self.assertEqual(isp.indent_spaces, 4)
 
     def test_indent4(self):
         isp = self.isp
         # whitespace after ':' should not screw up indent level
         isp.push('if 1: \n    x=1')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('y=2\n')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\t\n    x=1')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('y=2\n')
         self.assertEqual(isp.indent_spaces, 0)
 
     def test_dedent_pass(self):
         isp = self.isp # shorthand
         # should NOT cause dedent
         isp.push('if 1:\n    passes = 5')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('if 1:\n     pass')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\n     pass   ')
         self.assertEqual(isp.indent_spaces, 0)
 
     def test_dedent_break(self):
         isp = self.isp # shorthand
         # should NOT cause dedent
         isp.push('while 1:\n    breaks = 5')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('while 1:\n     break')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('while 1:\n     break   ')
         self.assertEqual(isp.indent_spaces, 0)
 
     def test_dedent_continue(self):
         isp = self.isp # shorthand
         # should NOT cause dedent
         isp.push('while 1:\n    continues = 5')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('while 1:\n     continue')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('while 1:\n     continue   ')
         self.assertEqual(isp.indent_spaces, 0)
 
     def test_dedent_raise(self):
         isp = self.isp # shorthand
         # should NOT cause dedent
         isp.push('if 1:\n    raised = 4')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('if 1:\n     raise TypeError()')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\n     raise')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\n     raise      ')
         self.assertEqual(isp.indent_spaces, 0)
 
     def test_dedent_return(self):
         isp = self.isp # shorthand
         # should NOT cause dedent
         isp.push('if 1:\n    returning = 4')
         self.assertEqual(isp.indent_spaces, 4)
         isp.push('if 1:\n     return 5 + 493')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\n     return')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\n     return      ')
         self.assertEqual(isp.indent_spaces, 0)
         isp.push('if 1:\n     return(0)')
         self.assertEqual(isp.indent_spaces, 0)
 
     def test_push(self):
         isp = self.isp
         self.assertTrue(isp.push('x=1'))
 
     def test_push2(self):
         isp = self.isp
         self.assertFalse(isp.push('if 1:'))
         for line in ['  x=1', '# a comment', '  y=2']:
             print(line)
             self.assertTrue(isp.push(line))
 
     def test_push3(self):
         isp = self.isp
         isp.push('if True:')
         isp.push('  a = 1')
         self.assertFalse(isp.push('b = [1,'))
 
     def test_push_accepts_more(self):
         isp = self.isp
         isp.push('x=1')
         self.assertFalse(isp.push_accepts_more())
 
     def test_push_accepts_more2(self):
         isp = self.isp
         isp.push('if 1:')
         self.assertTrue(isp.push_accepts_more())
         isp.push('  x=1')
         self.assertTrue(isp.push_accepts_more())
         isp.push('')
         self.assertFalse(isp.push_accepts_more())
 
     def test_push_accepts_more3(self):
         isp = self.isp
         isp.push("x = (2+\n3)")
         self.assertFalse(isp.push_accepts_more())
 
     def test_push_accepts_more4(self):
         isp = self.isp
         # When a multiline statement contains parens or multiline strings, we
         # shouldn't get confused.
         # FIXME: we should be able to better handle de-dents in statements like
         # multiline strings and multiline expressions (continued with \ or
         # parens).  Right now we aren't handling the indentation tracking quite
         # correctly with this, though in practice it may not be too much of a
         # problem.  We'll need to see.
         isp.push("if 1:")
         isp.push("    x = (2+")
         isp.push("    3)")
         self.assertTrue(isp.push_accepts_more())
         isp.push("    y = 3")
         self.assertTrue(isp.push_accepts_more())
         isp.push('')
         self.assertFalse(isp.push_accepts_more())
 
     def test_push_accepts_more5(self):
         isp = self.isp
         isp.push('try:')
         isp.push('    a = 5')
         isp.push('except:')
         isp.push('    raise')
         # We want to be able to add an else: block at this point, so it should
         # wait for a blank line.
         self.assertTrue(isp.push_accepts_more())
 
     def test_continuation(self):
         isp = self.isp
         isp.push("import os, \\")
         self.assertTrue(isp.push_accepts_more())
         isp.push("sys")
         self.assertFalse(isp.push_accepts_more())
 
     def test_syntax_error(self):
         isp = self.isp
         # Syntax errors immediately produce a 'ready' block, so the invalid
         # Python can be sent to the kernel for evaluation with possible ipython
         # special-syntax conversion.
         isp.push('run foo')
         self.assertFalse(isp.push_accepts_more())
 
     def test_unicode(self):
         self.isp.push(u"Pérez")
         self.isp.push(u'\xc3\xa9')
         self.isp.push(u"u'\xc3\xa9'")
 
     def test_line_continuation(self):
         """ Test issue #2108."""
         isp = self.isp
         # A blank line after a line continuation should not accept more
         isp.push("1 \\\n\n")
         self.assertFalse(isp.push_accepts_more())
         # Whitespace after a \ is a SyntaxError.  The only way to test that
         # here is to test that push doesn't accept more (as with
         # test_syntax_error() above).
         isp.push(r"1 \ ")
         self.assertFalse(isp.push_accepts_more())
         # Even if the line is continuable (c.f. the regular Python
         # interpreter)
         isp.push(r"(1 \ ")
         self.assertFalse(isp.push_accepts_more())
 
-    def test_is_complete(self):
+    def test_check_complete(self):
         isp = self.isp
-        assert isp.is_complete("a = 1")
-        assert not isp.is_complete("for a in range(5):")
-        assert isp.is_complete("raise = 2")  # SyntaxError should mean complete
-        assert not isp.is_complete("a = [1,\n2,")
+        self.assertEqual(isp.check_complete("a = 1"), ('complete', None))
+        self.assertEqual(isp.check_complete("for a in range(5):"), ('incomplete', 4))
+        self.assertEqual(isp.check_complete("raise = 2"), ('invalid', None))
+        self.assertEqual(isp.check_complete("a = [1,\n2,"), ('incomplete', 0))
 
 class InteractiveLoopTestCase(unittest.TestCase):
     """Tests for an interactive loop like a python shell.
     """
     def check_ns(self, lines, ns):
         """Validate that the given input lines produce the resulting namespace.
 
         Note: the input lines are given exactly as they would be typed in an
         auto-indenting environment, as mini_interactive_loop above already does
         auto-indenting and prepends spaces to the input.
         """
         src = mini_interactive_loop(pseudo_input(lines))
         test_ns = {}
         exec(src, test_ns)
         # We can't check that the provided ns is identical to the test_ns,
         # because Python fills test_ns with extra keys (copyright, etc).  But
         # we can check that the given dict is *contained* in test_ns
         for k,v in ns.items():
             self.assertEqual(test_ns[k], v)
 
     def test_simple(self):
         self.check_ns(['x=1'], dict(x=1))
 
     def test_simple2(self):
         self.check_ns(['if 1:', 'x=2'], dict(x=2))
 
     def test_xy(self):
         self.check_ns(['x=1; y=2'], dict(x=1, y=2))
 
     def test_abc(self):
         self.check_ns(['if 1:','a=1','b=2','c=3'], dict(a=1, b=2, c=3))
 
     def test_multi(self):
         self.check_ns(['x =(1+','1+','2)'], dict(x=4))
 
 
 class IPythonInputTestCase(InputSplitterTestCase):
     """By just creating a new class whose .isp is a different instance, we
     re-run the same test battery on the new input splitter.
 
     In addition, this runs the tests over the syntax and syntax_ml dicts that
     were tested by individual functions, as part of the OO interface.
 
     It also makes some checks on the raw buffer storage.
     """
 
     def setUp(self):
         self.isp = isp.IPythonInputSplitter()
 
     def test_syntax(self):
         """Call all single-line syntax tests from the main object"""
         isp = self.isp
         for example in syntax.values():
             for raw, out_t in example:
                 if raw.startswith(' '):
                     continue
 
                 isp.push(raw+'\n')
                 out_raw = isp.source_raw
                 out = isp.source_reset()
                 self.assertEqual(out.rstrip(), out_t,
                         tt.pair_fail_msg.format("inputsplitter",raw, out_t, out))
                 self.assertEqual(out_raw.rstrip(), raw.rstrip())
 
     def test_syntax_multiline(self):
         isp = self.isp
         for example in syntax_ml.values():
             for line_pairs in example:
                 out_t_parts = []
                 raw_parts = []
                 for lraw, out_t_part in line_pairs:
                     if out_t_part is not None:
                         out_t_parts.append(out_t_part)
                     
                     if lraw is not None:
                         isp.push(lraw)
                         raw_parts.append(lraw)
 
                 out_raw = isp.source_raw
                 out = isp.source_reset()
                 out_t = '\n'.join(out_t_parts).rstrip()
                 raw = '\n'.join(raw_parts).rstrip()
                 self.assertEqual(out.rstrip(), out_t)
                 self.assertEqual(out_raw.rstrip(), raw)
 
     def test_syntax_multiline_cell(self):
         isp = self.isp
         for example in syntax_ml.values():
 
             out_t_parts = []
             for line_pairs in example:
                 raw = '\n'.join(r for r, _ in line_pairs if r is not None)
                 out_t = '\n'.join(t for _,t in line_pairs if t is not None)
                 out = isp.transform_cell(raw)
                 # Match ignoring trailing whitespace
                 self.assertEqual(out.rstrip(), out_t.rstrip())
     
     def test_cellmagic_preempt(self):
         isp = self.isp
         for raw, name, line, cell in [
             ("%%cellm a\nIn[1]:", u'cellm', u'a', u'In[1]:'),
             ("%%cellm \nline\n>>> hi", u'cellm', u'', u'line\n>>> hi'),
             (">>> %%cellm \nline\n>>> hi", u'cellm', u'', u'line\nhi'),
             ("%%cellm \n>>> hi", u'cellm', u'', u'hi'),
             ("%%cellm \nline1\nline2", u'cellm', u'', u'line1\nline2'),
             ("%%cellm \nline1\\\\\nline2", u'cellm', u'', u'line1\\\\\nline2'),
         ]:
             expected = "get_ipython().run_cell_magic(%r, %r, %r)" % (
                 name, line, cell
             )
             out = isp.transform_cell(raw)
             self.assertEqual(out.rstrip(), expected.rstrip())
         
         
 
 #-----------------------------------------------------------------------------
 # Main - use as a script, mostly for developer experiments
 #-----------------------------------------------------------------------------
 
 if __name__ == '__main__':
     # A simple demo for interactive experimentation.  This code will not get
     # picked up by any test suite.
     from IPython.core.inputsplitter import InputSplitter, IPythonInputSplitter
 
     # configure here the syntax to use, prompt and whether to autoindent
     #isp, start_prompt = InputSplitter(), '>>> '
     isp, start_prompt = IPythonInputSplitter(), 'In> '
 
     autoindent = True
     #autoindent = False
 
     try:
         while True:
             prompt = start_prompt
             while isp.push_accepts_more():
                 indent = ' '*isp.indent_spaces
                 if autoindent:
                     line = indent + input(prompt+indent)
                 else:
                     line = input(prompt)
                 isp.push(line)
                 prompt = '... '
 
             # Here we just return input so we can use it in a test suite, but a
             # real interpreter would instead send it for execution somewhere.
             #src = isp.source; raise EOFError # dbg
             raw = isp.source_raw
             src = isp.source_reset()
             print('Input source was:\n', src)
             print('Raw source was:\n', raw)
     except EOFError:
         print('Bye')
 
 # Tests for cell magics support
 
 def test_last_blank():
     nt.assert_false(isp.last_blank(''))
     nt.assert_false(isp.last_blank('abc'))
     nt.assert_false(isp.last_blank('abc\n'))
     nt.assert_false(isp.last_blank('abc\na'))
 
     nt.assert_true(isp.last_blank('\n'))
     nt.assert_true(isp.last_blank('\n '))
     nt.assert_true(isp.last_blank('abc\n '))
     nt.assert_true(isp.last_blank('abc\n\n'))
     nt.assert_true(isp.last_blank('abc\nd\n\n'))
     nt.assert_true(isp.last_blank('abc\nd\ne\n\n'))
     nt.assert_true(isp.last_blank('abc \n \n \n\n'))
 
 
 def test_last_two_blanks():
     nt.assert_false(isp.last_two_blanks(''))
     nt.assert_false(isp.last_two_blanks('abc'))
     nt.assert_false(isp.last_two_blanks('abc\n'))
     nt.assert_false(isp.last_two_blanks('abc\n\na'))
     nt.assert_false(isp.last_two_blanks('abc\n \n'))
     nt.assert_false(isp.last_two_blanks('abc\n\n'))
 
     nt.assert_true(isp.last_two_blanks('\n\n'))
     nt.assert_true(isp.last_two_blanks('\n\n '))
     nt.assert_true(isp.last_two_blanks('\n \n'))
     nt.assert_true(isp.last_two_blanks('abc\n\n '))
     nt.assert_true(isp.last_two_blanks('abc\n\n\n'))
     nt.assert_true(isp.last_two_blanks('abc\n\n \n'))
     nt.assert_true(isp.last_two_blanks('abc\n\n \n '))
     nt.assert_true(isp.last_two_blanks('abc\n\n \n \n'))
     nt.assert_true(isp.last_two_blanks('abc\nd\n\n\n'))
     nt.assert_true(isp.last_two_blanks('abc\nd\ne\nf\n\n\n'))
 
 
 class CellMagicsCommon(object):
 
     def test_whole_cell(self):
         src = "%%cellm line\nbody\n"
         out = self.sp.transform_cell(src)
         ref = u"get_ipython().run_cell_magic({u}'cellm', {u}'line', {u}'body')\n"
         nt.assert_equal(out, py3compat.u_format(ref))
     
     def test_cellmagic_help(self):
         self.sp.push('%%cellm?')
         nt.assert_false(self.sp.push_accepts_more())
 
     def tearDown(self):
         self.sp.reset()
 
 
 class CellModeCellMagics(CellMagicsCommon, unittest.TestCase):
     sp = isp.IPythonInputSplitter(line_input_checker=False)
 
     def test_incremental(self):
         sp = self.sp
         sp.push('%%cellm firstline\n')
         nt.assert_true(sp.push_accepts_more()) #1
         sp.push('line2\n')
         nt.assert_true(sp.push_accepts_more()) #2
         sp.push('\n')
         # This should accept a blank line and carry on until the cell is reset
         nt.assert_true(sp.push_accepts_more()) #3
 
 class LineModeCellMagics(CellMagicsCommon, unittest.TestCase):
     sp = isp.IPythonInputSplitter(line_input_checker=True)
 
     def test_incremental(self):
         sp = self.sp
         sp.push('%%cellm line2\n')
         nt.assert_true(sp.push_accepts_more()) #1
         sp.push('\n')
         # In this case, a blank line should end the cell magic
         nt.assert_false(sp.push_accepts_more()) #2

IPython/kernel/tests/test_kernel.py

@@ -1,223 +1,224 b''
 # coding: utf-8
 """test the IPython Kernel"""
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2013  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
 #-------------------------------------------------------------------------------
 
 import io
 import os.path
 import sys
 
 import nose.tools as nt
 
 from IPython.testing import decorators as dec, tools as tt
 from IPython.utils import py3compat
 from IPython.utils.path import locate_profile
 from IPython.utils.tempdir import TemporaryDirectory
 
 from .utils import (new_kernel, kernel, TIMEOUT, assemble_output, execute,
                     flush_channels, wait_for_idle)
 
 #-------------------------------------------------------------------------------
 # Tests
 #-------------------------------------------------------------------------------
 
 
 def _check_mp_mode(kc, expected=False, stream="stdout"):
     execute(kc=kc, code="import sys")
     flush_channels(kc)
     msg_id, content = execute(kc=kc, code="print (sys.%s._check_mp_mode())" % stream)
     stdout, stderr = assemble_output(kc.iopub_channel)
     nt.assert_equal(eval(stdout.strip()), expected)
 
 
 # printing tests
 
 def test_simple_print():
     """simple print statement in kernel"""
     with kernel() as kc:
         iopub = kc.iopub_channel
         msg_id, content = execute(kc=kc, code="print ('hi')")
         stdout, stderr = assemble_output(iopub)
         nt.assert_equal(stdout, 'hi\n')
         nt.assert_equal(stderr, '')
         _check_mp_mode(kc, expected=False)
 
 
 def test_sys_path():
     """test that sys.path doesn't get messed up by default"""
     with kernel() as kc:
         msg_id, content = execute(kc=kc, code="import sys; print (repr(sys.path[0]))")
         stdout, stderr = assemble_output(kc.iopub_channel)
         nt.assert_equal(stdout, "''\n")
 
 def test_sys_path_profile_dir():
     """test that sys.path doesn't get messed up when `--profile-dir` is specified"""
     
     with new_kernel(['--profile-dir', locate_profile('default')]) as kc:
         msg_id, content = execute(kc=kc, code="import sys; print (repr(sys.path[0]))")
         stdout, stderr = assemble_output(kc.iopub_channel)
         nt.assert_equal(stdout, "''\n")
 
 @dec.knownfailureif(sys.platform == 'win32', "subprocess prints fail on Windows")
 def test_subprocess_print():
     """printing from forked mp.Process"""
     with new_kernel() as kc:
         iopub = kc.iopub_channel
         
         _check_mp_mode(kc, expected=False)
         flush_channels(kc)
         np = 5
         code = '\n'.join([
             "from __future__ import print_function",
             "import multiprocessing as mp",
             "pool = [mp.Process(target=print, args=('hello', i,)) for i in range(%i)]" % np,
             "for p in pool: p.start()",
             "for p in pool: p.join()"
         ])
         
         expected = '\n'.join([
             "hello %s" % i for i in range(np)
         ]) + '\n'
         
         msg_id, content = execute(kc=kc, code=code)
         stdout, stderr = assemble_output(iopub)
         nt.assert_equal(stdout.count("hello"), np, stdout)
         for n in range(np):
             nt.assert_equal(stdout.count(str(n)), 1, stdout)
         nt.assert_equal(stderr, '')
         _check_mp_mode(kc, expected=False)
         _check_mp_mode(kc, expected=False, stream="stderr")
 
 
 def test_subprocess_noprint():
     """mp.Process without print doesn't trigger iostream mp_mode"""
     with kernel() as kc:
         iopub = kc.iopub_channel
         
         np = 5
         code = '\n'.join([
             "import multiprocessing as mp",
             "pool = [mp.Process(target=range, args=(i,)) for i in range(%i)]" % np,
             "for p in pool: p.start()",
             "for p in pool: p.join()"
         ])
         
         msg_id, content = execute(kc=kc, code=code)
         stdout, stderr = assemble_output(iopub)
         nt.assert_equal(stdout, '')
         nt.assert_equal(stderr, '')
 
         _check_mp_mode(kc, expected=False)
         _check_mp_mode(kc, expected=False, stream="stderr")
 
 
 @dec.knownfailureif(sys.platform == 'win32', "subprocess prints fail on Windows")
 def test_subprocess_error():
     """error in mp.Process doesn't crash"""
     with new_kernel() as kc:
         iopub = kc.iopub_channel
         
         code = '\n'.join([
             "import multiprocessing as mp",
             "p = mp.Process(target=int, args=('hi',))",
             "p.start()",
             "p.join()",
         ])
         
         msg_id, content = execute(kc=kc, code=code)
         stdout, stderr = assemble_output(iopub)
         nt.assert_equal(stdout, '')
         nt.assert_true("ValueError" in stderr, stderr)
 
         _check_mp_mode(kc, expected=False)
         _check_mp_mode(kc, expected=False, stream="stderr")
 
 # raw_input tests
 
 def test_raw_input():
     """test [raw_]input"""
     with kernel() as kc:
         iopub = kc.iopub_channel
         
         input_f = "input" if py3compat.PY3 else "raw_input"
         theprompt = "prompt> "
         code = 'print({input_f}("{theprompt}"))'.format(**locals())
         msg_id = kc.execute(code, allow_stdin=True)
         msg = kc.get_stdin_msg(block=True, timeout=TIMEOUT)
         nt.assert_equal(msg['header']['msg_type'], u'input_request')
         content = msg['content']
         nt.assert_equal(content['prompt'], theprompt)
         text = "some text"
         kc.input(text)
         reply = kc.get_shell_msg(block=True, timeout=TIMEOUT)
         nt.assert_equal(reply['content']['status'], 'ok')
         stdout, stderr = assemble_output(iopub)
         nt.assert_equal(stdout, text + "\n")
 
 
 @dec.skipif(py3compat.PY3)
 def test_eval_input():
     """test input() on Python 2"""
     with kernel() as kc:
         iopub = kc.iopub_channel
         
         input_f = "input" if py3compat.PY3 else "raw_input"
         theprompt = "prompt> "
         code = 'print(input("{theprompt}"))'.format(**locals())
         msg_id = kc.execute(code, allow_stdin=True)
         msg = kc.get_stdin_msg(block=True, timeout=TIMEOUT)
         nt.assert_equal(msg['header']['msg_type'], u'input_request')
         content = msg['content']
         nt.assert_equal(content['prompt'], theprompt)
         kc.input("1+1")
         reply = kc.get_shell_msg(block=True, timeout=TIMEOUT)
         nt.assert_equal(reply['content']['status'], 'ok')
         stdout, stderr = assemble_output(iopub)
         nt.assert_equal(stdout, "2\n")
 
 
 def test_save_history():
     # Saving history from the kernel with %hist -f was failing because of
     # unicode problems on Python 2.
     with kernel() as kc, TemporaryDirectory() as td:
         file = os.path.join(td, 'hist.out')
         execute(u'a=1', kc=kc)
         wait_for_idle(kc)
         execute(u'b=u"abcþ"', kc=kc)
         wait_for_idle(kc)
         _, reply = execute("%hist -f " + file, kc=kc)
         nt.assert_equal(reply['status'], 'ok')
         with io.open(file, encoding='utf-8') as f:
             content = f.read()
         nt.assert_in(u'a=1', content)
         nt.assert_in(u'b=u"abcþ"', content)
 
 def test_help_output():
     """ipython kernel --help-all works"""
     tt.help_all_output_test('kernel')
 
 def test_is_complete():
     with kernel() as kc:
         # There are more test cases for this in core - here we just check
         # that the kernel exposes the interface correctly.
         kc.is_complete('2+2')
         reply = kc.get_shell_msg(block=True, timeout=TIMEOUT)
-        assert reply['content']['complete']
+        assert reply['content']['status'] == 'complete'
 
         # SyntaxError should mean it's complete        
         kc.is_complete('raise = 2')
         reply = kc.get_shell_msg(block=True, timeout=TIMEOUT)
-        assert reply['content']['complete']
+        assert reply['content']['status'] == 'invalid'
         
         kc.is_complete('a = [1,\n2,')
         reply = kc.get_shell_msg(block=True, timeout=TIMEOUT)
-        assert not reply['content']['complete']
+        assert reply['content']['status'] == 'incomplete'
+        assert reply['content']['indent'] == ''
  No newline at end of file

IPython/kernel/tests/test_message_spec.py

@@ -1,420 +1,428 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):
         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(min='5.0')
 
 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(min='5.0')
     implementation = Unicode('ipython')
     implementation_version = Version(min='2.1')
     language_version = Version(min='2.7')
     language = Unicode('python')
     banner = Unicode()
 
 
 class IsCompleteReply(Reference):
-    complete = Bool()
+    status = Enum((u'complete', u'incomplete', u'invalid', u'unknown'))
+    
+    def check(self, d):
+        Reference.check(self, d)
+        if d['status'] == 'incomplete':
+            IsCompleteReplyIncomplete().check(d)
+
+class IsCompleteReplyIncomplete(Reference):
+    indent = 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(),
     'is_complete_reply': IsCompleteReply(),
     '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)
 
 def test_is_complete():
     flush_channels()
     
     msg_id = KC.is_complete("a = 1")
     reply = KC.get_shell_msg(timeout=TIMEOUT)
     validate_message(reply, 'is_complete_reply', msg_id)
 
 # 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,306 +1,309 b''
 """The IPython kernel implementation"""
 
 import getpass
 import sys
 import traceback
 
 from IPython.core import release
 from IPython.utils.py3compat import builtin_mod, PY3
 from IPython.utils.tokenutil import token_at_cursor
 from IPython.utils.traitlets import Instance, Type, Any
 from IPython.utils.decorators import undoc
 
 from .kernelbase import Kernel as KernelBase
 from .serialize import serialize_object, unpack_apply_message
 from .zmqshell import ZMQInteractiveShell
 
 class IPythonKernel(KernelBase):
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
     shell_class = Type(ZMQInteractiveShell)
 
     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()
 
     # 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()
 
     def __init__(self, **kwargs):
         super(IPythonKernel, 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
 
         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)
 
     # Kernel info fields
     implementation = 'ipython'
     implementation_version = release.version
     language = 'python'
     language_version = sys.version.split()[0]
     @property
     def banner(self):
         return self.shell.banner
 
     def start(self):
         self.shell.exit_now = False
         super(IPythonKernel, self).start()
 
     def set_parent(self, ident, parent):
         """Overridden from parent to tell the display hook and output streams
         about the parent message.
         """
         super(IPythonKernel, self).set_parent(ident, parent)
         self.shell.set_parent(parent)
 
     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 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 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
 
     @property
     def execution_count(self):
         return self.shell.execution_count
 
     @execution_count.setter
     def execution_count(self, value):
         # Ignore the incrememnting done by KernelBase, in favour of our shell's
         # execution counter.
         pass
 
     def do_execute(self, code, silent, store_history=True,
                    user_expressions=None, allow_stdin=False):
         shell = self.shell # we'll need this a lot here
 
         self._forward_input(allow_stdin)
 
         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(user_expressions or {})
         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()
 
         return reply_content
 
     def do_complete(self, code, cursor_pos):
         txt, matches = self.shell.complete('', code, cursor_pos)
         return {'matches' : matches,
                 'cursor_end' : cursor_pos,
                 'cursor_start' : cursor_pos - len(txt),
                 'metadata' : {},
                 'status' : 'ok'}
 
     def do_inspect(self, code, cursor_pos, detail_level=0):
         name = token_at_cursor(code, 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=detail_level,
             )
             data['text/plain'] = info_text
 
         return reply_content
 
     def do_history(self, hist_access_type, output, raw, session=None, start=None,
                    stop=None, n=None, pattern=None, unique=False):
         if hist_access_type == 'tail':
             hist = self.shell.history_manager.get_tail(n, raw=raw, output=output,
                                                             include_latest=True)
 
         elif hist_access_type == 'range':
             hist = self.shell.history_manager.get_range(session, start, stop,
                                                         raw=raw, output=output)
 
         elif hist_access_type == 'search':
             hist = self.shell.history_manager.search(
                 pattern, raw=raw, output=output, n=n, unique=unique)
         else:
             hist = []
 
         return {'history' : list(hist)}
 
     def do_shutdown(self, restart):
         self.shell.exit_now = True
         return dict(status='ok', restart=restart)
 
     def do_is_complete(self, code):
-        complete = self.shell.input_transformer_manager.is_complete(code)
-        return {'complete': complete}
+        status, indent_spaces = self.shell.input_transformer_manager.check_complete(code)
+        r = {'status': status}
+        if status == 'incomplete':
+            r['indent'] = ' ' * indent_spaces
+        return r
 
     def do_apply(self, content, bufs, msg_id, reply_metadata):
         shell = self.shell
         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.send_response(self.iopub_socket, u'error', reply_content,
                                 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':
                 reply_metadata['dependencies_met'] = False
         else:
             reply_content = {'status' : 'ok'}
 
         return reply_content, result_buf
 
     def do_clear(self):
         self.shell.reset(False)
         return dict(status='ok')
 
 
 # This exists only for backwards compatibility - use IPythonKernel instead
 
 @undoc
 class Kernel(IPythonKernel):
     def __init__(self, *args, **kwargs):
         import warnings
         warnings.warn('Kernel is a deprecated alias of IPython.kernel.zmq.ipkernel.IPythonKernel',
                       DeprecationWarning)
         super(Kernel, self).__init__(*args, **kwargs)
  No newline at end of file

IPython/kernel/zmq/kernelbase.py

@@ -1,693 +1,693 b''
 """Base class for a 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 sys
 import time
 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 unicode_type, string_types
 from IPython.utils.jsonutil import json_clean
 from IPython.utils.traitlets import (
     Any, Instance, Float, Dict, List, Set, Integer, Unicode, Bool,
 )
 
 from .session import Session
 
 
 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)
 
     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)
 
     # 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()
 
     # set of aborted msg_ids
     aborted = Set()
 
     # Track execution count here. For IPython, we override this to use the
     # execution count we store in the shell.
     execution_count = 0
 
 
     def __init__(self, **kwargs):
         super(Kernel, self).__init__(**kwargs)
 
         # 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', 'is_complete_request',
                     ]
         self.shell_handlers = {}
         for msg_type in msg_types:
             self.shell_handlers[msg_type] = getattr(self, 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)
         
         # Set the parent message for side effects.
         self.set_parent(idents, msg)
         self._publish_status(u'busy')
         
         header = msg['header']
         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)
         
         sys.stdout.flush()
         sys.stderr.flush()
         self._publish_status(u'idle')
     
     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
 
         # Set the parent message for side effects.
         self.set_parent(idents, msg)
         self._publish_status(u'busy')
         
         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)
             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)
         
         sys.stdout.flush()
         sys.stderr.flush()
         self._publish_status(u'idle')
     
     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"""
         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 or self._parent_header,
                           ident=self._topic('status'),
                           )
     
     def set_parent(self, ident, parent):
         """Set the current parent_header
         
         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
     
     def send_response(self, stream, msg_or_type, content=None, ident=None,
              buffers=None, track=False, header=None, metadata=None):
         """Send a response to the message we're currently processing.
         
         This accepts all the parameters of :meth:`IPython.kernel.zmq.session.Session.send`
         except ``parent``.
         
         This relies on :meth:`set_parent` having been called for the current
         message.
         """
         return self.session.send(stream, msg_or_type, content, self._parent_header,
                                  ident, buffers, track, header, metadata)
     
     def execute_request(self, stream, ident, parent):
         """handle an execute_request"""
         
         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)
             user_expressions = content.get('user_expressions', {})
             allow_stdin = content.get('allow_stdin', False)
         except:
             self.log.error("Got bad msg: ")
             self.log.error("%s", parent)
             return
         
         md = self._make_metadata(parent['metadata'])
         
         # Re-broadcast our input for the benefit of listening clients, and
         # start computing output
         if not silent:
             self.execution_count += 1
             self._publish_execute_input(code, parent, self.execution_count)
         
         reply_content = self.do_execute(code, silent, store_history,
                                         user_expressions, allow_stdin)
 
         # 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()
 
     def do_execute(self, code, silent, store_history=True,
                    user_experssions=None, allow_stdin=False):
         """Execute user code. Must be overridden by subclasses.
         """
         raise NotImplementedError
 
     def complete_request(self, stream, ident, parent):
         content = parent['content']
         code = content['code']
         cursor_pos = content['cursor_pos']
         
         matches = self.do_complete(code, cursor_pos)
         matches = json_clean(matches)
         completion_msg = self.session.send(stream, 'complete_reply',
                                            matches, parent, ident)
         self.log.debug("%s", completion_msg)
 
     def do_complete(self, code, cursor_pos):
         """Override in subclasses to find completions.
         """
         return {'matches' : [],
                 'cursor_end' : cursor_pos,
                 'cursor_start' : cursor_pos,
                 'metadata' : {},
                 'status' : 'ok'}
 
     def inspect_request(self, stream, ident, parent):
         content = parent['content']
         
         reply_content = self.do_inspect(content['code'], content['cursor_pos'],
                                         content.get('detail_level', 0))
         # 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 do_inspect(self, code, cursor_pos, detail_level=0):
         """Override in subclasses to allow introspection.
         """
         return {'status': 'ok', 'data':{}, 'metadata':{}, 'found':False}
 
     def history_request(self, stream, ident, parent):
         content = parent['content']
 
         reply_content = self.do_history(**content)
 
         reply_content = json_clean(reply_content)
         msg = self.session.send(stream, 'history_reply',
                                 reply_content, parent, ident)
         self.log.debug("%s", msg)
 
     def do_history(self, hist_access_type, output, raw, session=None, start=None,
                    stop=None, n=None, pattern=None, unique=False):
         """Override in subclasses to access history.
         """
         return {'history': []}
 
     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)
 
     @property
     def kernel_info(self):
         return {
             'protocol_version': release.kernel_protocol_version,
             'implementation': self.implementation,
             'implementation_version': self.implementation_version,
             'language': self.language,
             'language_version': self.language_version,
             'banner': self.banner,
         }
 
     def kernel_info_request(self, stream, ident, parent):
         msg = self.session.send(stream, 'kernel_info_reply',
                                 self.kernel_info, parent, ident)
         self.log.debug("%s", msg)
 
     def shutdown_request(self, stream, ident, parent):
         content = self.do_shutdown(parent['content']['restart'])
         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)
 
     def do_shutdown(self, restart):
         """Override in subclasses to do things when the frontend shuts down the
         kernel.
         """
         return {'status': 'ok', 'restart': restart}
     
     def is_complete_request(self, stream, ident, parent):
         content = parent['content']
         code = content['code']
         
         reply_content = self.do_is_complete(code)
         reply_content = json_clean(reply_content)
         reply_msg = self.session.send(stream, 'is_complete_reply',
                                            reply_content, parent, ident)
         self.log.debug("%s", reply_msg)
 
     def do_is_complete(self, code):
         """Override in subclasses to find completions.
         """
-        return {'complete' : True,
+        return {'status' : 'unknown',
                 }
 
     #---------------------------------------------------------------------------
     # 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
 
         md = self._make_metadata(parent['metadata'])
 
         reply_content, result_buf = self.do_apply(content, bufs, msg_id, md)
 
         # put 'ok'/'error' status in header, for scheduler introspection:
         md['status'] = reply_content['status']
 
         # flush i/o
         sys.stdout.flush()
         sys.stderr.flush()
         
         self.session.send(stream, u'apply_reply', reply_content,
                     parent=parent, ident=ident,buffers=result_buf, metadata=md)
 
     def do_apply(self, content, bufs, msg_id, reply_metadata):
         """Override in subclasses to support the IPython parallel framework.
         """
         raise NotImplementedError
 
     #---------------------------------------------------------------------------
     # 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."""
         content = self.do_clear()
         self.session.send(stream, 'clear_reply', ident=idents, parent=parent,
                 content = content)
 
     def do_clear(self):
         """Override in subclasses to clear the namespace
         
         This is only required for IPython.parallel.
         """
         raise NotImplementedError
 
     #---------------------------------------------------------------------------
     # Protected interface
     #---------------------------------------------------------------------------
 
     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 ]
 

docs/source/development/messaging.rst

@@ -1,1095 +1,1111 b''
 .. _messaging:
 
 ======================
  Messaging in IPython
 ======================
 
 
 Versioning
 ==========
 
 The IPython message specification is versioned independently of IPython.
 The current version of the specification is 5.1.
 
 
 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',
          },
 
       # 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
 
     ``version`` key added to the header.
 
 .. _wire_protocol:
 
 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
 
     ``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
 
     ``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.
 
 .. _msging_inspection:
 
 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
 
     ``object_info_request`` renamed to ``inspect_request``.
 
 .. 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
 
     ``object_info_reply`` renamed to ``inspect_reply``.
 
 .. versionchanged:: 5.0
 
     Reply is changed from structured data to a mime bundle,  allowing formatting decisions to be made by the kernel.
 
 .. _msging_completion:
 
 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
 
     ``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
 
     - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``.
     - ``metadata`` is added for extended information.
 
 .. _msging_history:
 
 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,
     }
 
 .. _msging_is_complete:
 
 Code completeness
 -----------------
 
 .. versionadded:: 5.1
 
 When the user enters a line in a console style interface, the console must
 decide whether to immediately execute the current code, or whether to show a
 continuation prompt for further input. For instance, in Python ``a = 5`` would
 be executed immediately, while ``for i in range(5):`` would expect further input.
 
+There are four possible replies:
+
+- *complete* code is ready to be executed
+- *incomplete* code should prompt for another line
+- *invalid* code will typically be sent for execution, so that the user sees the
+  error soonest.
+- *unknown* - if the kernel is not able to determine this. The frontend should
+  also handle the kernel not replying promptly. It may default to sending the
+  code for execution, or it may implement simple fallback heuristics for whether
+  to execute the code (e.g. execute after a blank line).
+
 Frontends may have ways to override this, forcing the code to be sent for
-execution or forcing a continuation prompt. If the kernel does not reply promptly,
-the frontend will probably default to sending the code to be executed.
+execution or forcing a continuation prompt.
 
 Message type: ``is_complete_request``::
 
     content = {
         # The code entered so far as a multiline string
         'code' : str,
     }
 
-Message type: ``complete_reply``::
+Message type: ``is_complete_reply``::
 
     content = {
-        # True if the code is ready to execute, False if not
-        'complete' : bool,
+        # One of 'complete', 'incomplete', 'invalid', 'unknown'
+        'status' : str,
+        
+        # If status is 'incomplete', indent should contain the characters to use
+        # to indent the next line. This is only a hint: frontends may ignore it
+        # and use their own autoindentation rules. For other statuses, this
+        # field does not exist.
+        'indent': str,
     }
 
 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.
     }
 
 .. _msging_kernel_info:
 
 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
 
     Versions changed from lists of integers to strings.
     
 .. versionchanged:: 5.0
 
     ``ipython_version`` is removed.
 
 .. versionchanged:: 5.0
 
     ``implementation``, ``implementation_version``, and ``banner`` keys are added.
 
 .. _msging_shutdown:
 
 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
 
     `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
 
     ``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
 
     ``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 handle a message, 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')
     }
 
 .. versionchanged:: 5.0
 
     Busy and idle messages should be sent before/after handling every message,
     not just execution.
 
 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
 
     ``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.
 
 .. _kernel_heartbeat:
 
 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