allow formatters to publish metadata

formatters can now return either data or (data, metadata)

the resulting published dict has both content.data keyed by mime-types,a
and content.metadata keyed by mime-types.

metadata keys are not necessarily defined, and are generally undefined when they would have no content.

This fits fully within the existing message spec.

IPython/core/display.py

@@ -73,8 +73,8 def display(*objs, **kwargs):
     publish = inst.display_pub.publish
 
     for obj in objs:
-        format_dict = format(obj, include=include, exclude=exclude)
-        publish('IPython.core.display.display', format_dict)
+        format_dict, md_dict = format(obj, include=include, exclude=exclude)
+        publish('IPython.core.display.display', format_dict, md_dict)
 
 
 def display_pretty(*objs, **kwargs):

IPython/core/displayhook.py

@@ -153,7 +153,7 class DisplayHook(Configurable):
         """
         return self.shell.display_formatter.format(result)
 
-    def write_format_data(self, format_dict):
+    def write_format_data(self, format_dict, md_dict=None):
         """Write the format data dict to the frontend.
 
         This default version of this method simply writes the plain text
@@ -239,8 +239,8 class DisplayHook(Configurable):
         if result is not None and not self.quiet():
             self.start_displayhook()
             self.write_output_prompt()
-            format_dict = self.compute_format_data(result)
-            self.write_format_data(format_dict)
+            format_dict, md_dict = self.compute_format_data(result)
+            self.write_format_data(format_dict, md_dict)
             self.update_user_ns(result)
             self.log_output(format_dict)
             self.finish_displayhook()

IPython/core/formatters.py

@@ -135,20 +135,31 class DisplayFormatter(Configurable):
             that format.
         """
         format_dict = {}
+        md_dict = {}
 
         for format_type, formatter in self.formatters.items():
             if include and format_type not in include:
                 continue
             if exclude and format_type in exclude:
                 continue
+            
+            md = None
             try:
                 data = formatter(obj)
             except:
                 # FIXME: log the exception
                 raise
+            
+            # formatters can return raw data or (data, metadata)
+            if isinstance(data, tuple) and len(data) == 2:
+                data, md = data
+            
             if data is not None:
                 format_dict[format_type] = data
-        return format_dict
+            if md is not None:
+                md_dict[format_type] = md
+            
+        return format_dict, md_dict
 
     @property
     def format_types(self):

IPython/kernel/zmq/displayhook.py

@@ -52,8 +52,9 class ZMQShellDisplayHook(DisplayHook):
         """Write the output prompt."""
         self.msg['content']['execution_count'] = self.prompt_count
 
-    def write_format_data(self, format_dict):
+    def write_format_data(self, format_dict, md_dict=None):
         self.msg['content']['data'] = encode_images(format_dict)
+        self.msg['content']['metadata'] = md_dict
 
     def finish_displayhook(self):
         """Finish up all displayhook activities."""