Merge pull request #7005 from minrk/payloads-3.0

update payloads for msg spec 5

IPython/core/payloadpage.py

@@ -38,7 +38,6 b' def page(strng, start=0, screen_lines=0, pager_cmd=None):'
         source='page',
         data=data,
         start=start,
-        screen_lines=screen_lines,
         )
     shell.payload_manager.write_payload(payload)
 

IPython/kernel/zmq/zmqshell.py

@@ -102,72 +102,6 b' class KernelMagics(Magics):'
     # moved into a separate machinery as well.  For now, at least isolate here
     # the magics which this class needs to implement differently from the base
     # class, or that are unique to it.
-
-    @line_magic
-    def doctest_mode(self, parameter_s=''):
-        """Toggle doctest mode on and off.
-
-        This mode is intended to make IPython behave as much as possible like a
-        plain Python shell, from the perspective of how its prompts, exceptions
-        and output look.  This makes it easy to copy and paste parts of a
-        session into doctests.  It does so by:
-
-        - Changing the prompts to the classic ``>>>`` ones.
-        - Changing the exception reporting mode to 'Plain'.
-        - Disabling pretty-printing of output.
-
-        Note that IPython also supports the pasting of code snippets that have
-        leading '>>>' and '...' prompts in them.  This means that you can paste
-        doctests from files or docstrings (even if they have leading
-        whitespace), and the code will execute correctly.  You can then use
-        '%history -t' to see the translated history; this will give you the
-        input after removal of all the leading prompts and whitespace, which
-        can be pasted back into an editor.
-
-        With these features, you can switch into this mode easily whenever you
-        need to do testing and changes to doctests, without having to leave
-        your existing IPython session.
-        """
-
-        from IPython.utils.ipstruct import Struct
-
-        # Shorthands
-        shell = self.shell
-        disp_formatter = self.shell.display_formatter
-        ptformatter = disp_formatter.formatters['text/plain']
-        # dstore is a data store kept in the instance metadata bag to track any
-        # changes we make, so we can undo them later.
-        dstore = shell.meta.setdefault('doctest_mode', Struct())
-        save_dstore = dstore.setdefault
-
-        # save a few values we'll need to recover later
-        mode = save_dstore('mode', False)
-        save_dstore('rc_pprint', ptformatter.pprint)
-        save_dstore('rc_active_types',disp_formatter.active_types)
-        save_dstore('xmode', shell.InteractiveTB.mode)
-
-        if mode == False:
-            # turn on
-            ptformatter.pprint = False
-            disp_formatter.active_types = ['text/plain']
-            shell.magic('xmode Plain')
-        else:
-            # turn off
-            ptformatter.pprint = dstore.rc_pprint
-            disp_formatter.active_types = dstore.rc_active_types
-            shell.magic("xmode " + dstore.xmode)
-
-        # Store new mode and inform on console
-        dstore.mode = bool(1-int(mode))
-        mode_label = ['OFF','ON'][dstore.mode]
-        print('Doctest mode is:', mode_label)
-
-        # Send the payload back so that clients can modify their prompt display
-        payload = dict(
-            source='doctest_mode',
-            mode=dstore.mode)
-        shell.payload_manager.write_payload(payload)
-        
     
     _find_edit_target = CodeMagics._find_edit_target
 
@@ -473,25 +407,11 b' class ZMQInteractiveShell(InteractiveShell):'
         # And install the payload version of page.
         install_payload_page()
 
-    def auto_rewrite_input(self, cmd):
-        """Called to show the auto-rewritten input for autocall and friends.
-
-        FIXME: this payload is currently not correctly processed by the
-        frontend.
-        """
-        new = self.prompt_manager.render('rewrite') + cmd
-        payload = dict(
-            source='auto_rewrite_input',
-            transformed_input=new,
-            )
-        self.payload_manager.write_payload(payload)
-
     def ask_exit(self):
         """Engage the exit actions."""
         self.exit_now = (not self.keepkernel_on_exit)
         payload = dict(
             source='ask_exit',
-            exit=True,
             keepkernel=self.keepkernel_on_exit,
             )
         self.payload_manager.write_payload(payload)

IPython/qt/console/ipython_widget.py

@@ -103,7 +103,7 b' class IPythonWidget(FrontendWidget):'
 
     # IPythonWidget protected class variables.
     _PromptBlock = namedtuple('_PromptBlock', ['block', 'length', 'number'])
-    _payload_source_edit = 'edit_magic'
+    _payload_source_edit = 'edit'
     _payload_source_exit = 'ask_exit'
     _payload_source_next_input = 'set_next_input'
     _payload_source_page = 'page'

docs/source/development/messaging.rst

@@ -355,13 +355,11 b' Message type: ``execute_reply``::'
 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.
+      # 'payload' will be a list of payload dicts, and is optional.
+      # payloads are considered deprecated.
       # The only requirement of each payload dict is that it have a 'source' key,
-      # which is a string classifying the payload (e.g. 'pager').
+      # which is a string classifying the payload (e.g. 'page').
+      
       'payload' : list(dict),
 
       # Results for the user_expressions.
@@ -372,24 +370,6 b" When status is 'ok', the following extra fields are present::"
 
     ``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::
 
     {
@@ -411,6 +391,72 b" When status is 'error', the following extra fields are present::"
 When status is 'abort', there are for now no additional data fields.  This
 happens when the kernel was interrupted by a signal.
 
+Payloads
+********
+
+.. admonition:: Execution payloads
+
+    Payloads are considered deprecated, though their replacement is not yet implemented.
+
+Payloads are a way to trigger frontend actions from the kernel. Current payloads:
+
+**page**: display data in a pager.
+
+Pager output is used for introspection, or other displayed information that's not considered output.
+Pager payloads are generally displayed in a separate pane, that can be viewed alongside code,
+and are not included in notebook documents.
+
+.. sourcecode:: python
+
+    {
+      "source": "page",
+      # mime-bundle of data to display in the pager.
+      # Must include text/plain.
+      "data": mimebundle,
+      # line offset to start from
+      "start": int,
+    }
+
+**set_next_input**: create a new output
+
+used to create new cells in the notebook,
+or set the next input in a console interface.
+The main example being ``%load``.
+
+.. sourcecode:: python
+
+    {
+      "source": "set_next_input",
+      # the text contents of the cell to create
+      "text": "some cell content",
+    }
+
+**edit**: open a file for editing.
+
+Triggered by `%edit`. Only the QtConsole currently supports edit payloads.
+
+.. sourcecode:: python
+
+    {
+      "source": "edit",
+      "filename": "/path/to/file.py", # the file to edit
+      "line_number": int, # the line number to start with
+    }
+
+**ask_exit**: instruct the frontend to prompt the user for exit
+
+Allows the kernel to request exit, e.g. via ``%exit`` in IPython.
+Only for console frontends.
+
+.. sourcecode:: python
+
+    {
+      "source": "ask_exit",
+      # whether the kernel should be left running, only closing the client
+      "keepkernel": bool,
+    }
+
+
 .. _msging_inspection:
 
 Introspection