From 668ed7c878d22edcdffe31478dd016a33f95c9eb 2010-10-29 23:22:53
From: Robert Kern <robert.kern@gmail.com>
Date: 2010-10-29 23:22:53
Subject: [PATCH] ENH: Extend the DisplayHook.compute_result_repr() and write_result_repr() methods to produce and consume the lists of extra formats. Use this capability in the ZMQ shell. Document the extension to the messaging format.

---

diff --git a/IPython/core/displayhook.py b/IPython/core/displayhook.py
index cca5b92..764f19f 100644
--- a/IPython/core/displayhook.py
+++ b/IPython/core/displayhook.py
@@ -208,9 +208,19 @@ class DisplayHook(Configurable):
                 # But avoid extraneous empty lines.
                 result_repr = '\n' + result_repr
 
-        return result_repr
+        extra_formats = []
+        for f in self.extra_formatters:
+            try:
+                data = f(result)
+            except Exception:
+                # FIXME: log the exception.
+                continue
+            if data is not None:
+                extra_formats.append((f.id, f.format, data))
+
+        return result_repr, extra_formats
 
-    def write_result_repr(self, result_repr):
+    def write_result_repr(self, result_repr, extra_formats):
         # We want to print because we want to always make sure we have a 
         # newline, even if all the prompt separators are ''. This is the
         # standard IPython behavior.
@@ -265,8 +275,8 @@ class DisplayHook(Configurable):
         if result is not None and not self.quiet():
             self.start_displayhook()
             self.write_output_prompt()
-            result_repr = self.compute_result_repr(result)
-            self.write_result_repr(result_repr)
+            result_repr, extra_formats = self.compute_result_repr(result)
+            self.write_result_repr(result_repr, extra_formats)
             self.update_user_ns(result)
             self.log_output(result)
             self.finish_displayhook()
diff --git a/IPython/zmq/zmqshell.py b/IPython/zmq/zmqshell.py
index b418ec3..51d8501 100644
--- a/IPython/zmq/zmqshell.py
+++ b/IPython/zmq/zmqshell.py
@@ -65,8 +65,9 @@ class ZMQDisplayHook(DisplayHook):
         if self.do_full_cache:
             self.msg['content']['execution_count'] = self.prompt_count
 
-    def write_result_repr(self, result_repr):
+    def write_result_repr(self, result_repr, extra_formats):
         self.msg['content']['data'] = result_repr
+        self.msg['content']['extra_formats'] = extra_formats
 
     def finish_displayhook(self):
         """Finish up all displayhook activities."""
diff --git a/docs/source/development/messaging.txt b/docs/source/development/messaging.txt
index 230880c..510f371 100644
--- a/docs/source/development/messaging.txt
+++ b/docs/source/development/messaging.txt
@@ -725,16 +725,35 @@ case, the kernel instantiates as ``sys.displayhook`` an object which has
 similar behavior, but which instead of printing to stdout, broadcasts these
 values as ``pyout`` messages for clients to display appropriately.
 
+IPython's displayhook can handle multiple simultaneous formats depending on its
+configuration. The default pretty-printed repr text is always given with the
+``data`` entry in this message. Any other formats are provided in the
+``extra_formats`` list. Frontends are free to display any or all of these
+according to its capabilities. ``extra_formats`` list contains 3-tuples of an ID
+string, a type string, and the data. The ID is unique to the formatter
+implementation that created the data. Frontends will typically ignore the ID
+unless if it has requested a particular formatter. The type string tells the
+frontend how to interpret the data. It is often, but not always a MIME type.
+Frontends should ignore types that it does not understand. The data itself is
+any JSON object and depends on the format. It is often, but not always a string.
+
 Message type: ``pyout``::
 
     content = {
-        # The data is typically the repr() of the object.
-    'data' : str,
+        # The data is typically the repr() of the object. It should be displayed
+        # as monospaced text.
+        'data' : str,
     
-    # The counter for this execution is also provided so that clients can
-    # display it, since IPython automatically creates variables called _N (for
-    # prompt N).
-    'execution_count' : int,
+        # 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,
+
+        # Any extra formats.
+        # The tuples are of the form (ID, type, data).
+        'extra_formats' : [
+           [str, str, object]
+        ]
     }
     
 Python errors