Final work on display system.

* getfigs added to replicate figure finding of pastefig. This
  function is auto-loaded in pylad mode.
* display* functions now take *args to allow the display of
  multiple objects.
* Updated %guiref magic to reflect display system.

IPython/core/display.py

@@ -21,7 +21,7 b' Authors:'
 # Main functions
 #-----------------------------------------------------------------------------
 
-def display(obj, include=None, exclude=None):
+def display(*objs, **kwargs):
     """Display a Python object in all frontends.
 
     By default all representations will be computed and sent to the frontends.
@@ -29,8 +29,8 b' def display(obj, include=None, exclude=None):'
 
     Parameters
     ----------
-    obj : object
-        The Python object to display.
+    objs : tuple of objects
+        The Python objects to display.
     include : list or tuple, optional
         A list of format type strings (MIME types) to include in the
         format data dict. If this is set *only* the format types included
@@ -40,79 +40,83 b' def display(obj, include=None, exclude=None):'
         data dict. If this is set all format types will be computed,
         except for those included in this argument.
     """
+    include = kwargs.get('include')
+    exclude = kwargs.get('exclude')
+    
     from IPython.core.interactiveshell import InteractiveShell
     inst = InteractiveShell.instance()
     format = inst.display_formatter.format
     publish = inst.display_pub.publish
 
-    format_dict = format(obj, include=include, exclude=exclude)
-    publish('IPython.core.display.display', format_dict)
+    for obj in objs:
+        format_dict = format(obj, include=include, exclude=exclude)
+        publish('IPython.core.display.display', format_dict)
 
 
-def display_pretty(obj):
+def display_pretty(*objs):
     """Display the pretty (default) representation of an object.
 
     Parameters
     ----------
-    obj : object
-        The Python object to display.
+    objs : tuple of objects
+        The Python objects to display.
     """
-    display(obj, include=['text/plain'])
+    display(*objs, include=['text/plain'])
 
 
-def display_html(obj):
+def display_html(*objs):
     """Display the HTML representation of an object.
 
     Parameters
     ----------
-    obj : object
-        The Python object to display.
+    objs : tuple of objects
+        The Python objects to display.
         """
-    display(obj, include=['text/plain','text/html'])
+    display(*objs, include=['text/plain','text/html'])
 
 
-def display_svg(obj):
+def display_svg(*objs):
     """Display the SVG representation of an object.
 
     Parameters
     ----------
-    obj : object
-        The Python object to display.
+    objs : tuple of objects
+        The Python objects to display.
     """
-    display(obj, include=['text/plain','image/svg+xml'])
+    display(*objs, include=['text/plain','image/svg+xml'])
 
 
-def display_png(obj):
+def display_png(*objs):
     """Display the PNG representation of an object.
 
     Parameters
     ----------
-    obj : object
-        The Python object to display.
+    objs : tuple of objects
+        The Python objects to display.
     """
-    display(obj, include=['text/plain','image/png'])
+    display(*objs, include=['text/plain','image/png'])
 
 
-def display_latex(obj):
+def display_latex(*objs):
     """Display the LaTeX representation of an object.
 
     Parameters
     ----------
-    obj : object
-        The Python object to display.
+    objs : tuple of objects
+        The Python objects to display.
     """
-    display(obj, include=['text/plain','text/latex'])
+    display(*objs, include=['text/plain','text/latex'])
 
 
-def display_json(obj):
+def display_json(*objs):
     """Display the JSON representation of an object.
 
     Parameters
     ----------
-    obj : object
-        The Python object to display.
+    objs : tuple of objects
+        The Python objects to display.
     """
-    display(obj, include=['text/plain','application/json'])
+    display(*objs, include=['text/plain','application/json'])
 
 
 

IPython/core/displayhook.py

@@ -212,8 +212,7 b' class DisplayHook(Configurable):'
             all return values of this should always include the "text/plain"
             MIME type representation of the object.
         """
-        format_dict = self.shell.display_formatter.format(result)
-        return format_dict
+        return self.shell.display_formatter.format(result)
 
     def write_format_data(self, format_dict):
         """Write the format data dict to the frontend.

IPython/core/formatters.py

@@ -179,10 +179,11 b' class BaseFormatter(Configurable):'
        to find print method: :attr:`singleton_printers`, :attr:`type_printers`
        and :attr:`deferred_printers`.
 
-    Users should use these dictionarie to register functions that will be used
-    to compute the format data for their objects (if those objects don't have
-    the special print methods). The easiest way of using these dictionaries
-    is through the :meth:`for_type` and :meth:`for_type_by_name` methods.
+    Users should use these dictionaries to register functions that will be
+    used to compute the format data for their objects (if those objects don't
+    have the special print methods). The easiest way of using these
+    dictionaries is through the :meth:`for_type` and :meth:`for_type_by_name`
+    methods.
 
     If no function/callable is found to compute the format data, ``None`` is
     returned and this format type is not used.
@@ -243,7 +244,7 b' class BaseFormatter(Configurable):'
     def for_type(self, typ, func):
         """Add a format function for a given type.
 
-        Parameteres
+        Parameters
         -----------
         typ : class
             The class of the object that will be formatted using `func`.

IPython/core/usage.py

@@ -441,6 +441,31 b' We have provided as magics ``%less`` to page files (aliased to ``%more``),'
 most common commands you'd want to call in your subshell and that would cause
 problems if invoked via ``!cmd``, but you need to be aware of this limitation.
 
+Display
+=======
+
+The IPython console can now display objects in a variety of formats, including
+HTML, PNG and SVG. This is accomplished using the display functions in
+``IPython.core.display``::
+
+    In [4]: from IPython.core.display import display, display_html
+
+    In [5]: from IPython.core.display import display_png, display_svg
+
+Python objects can simply be passed to these functions and the appropriate
+representations will be displayed in the console as long as the objects know
+how to compute those representations. The easiest way of teaching objects how
+to format themselves in various representations is to define special methods
+such as: ``__html``, ``__svg__`` and ``__png__``. IPython's display formatters
+can also be given custom formatter functions for various types::
+
+    In [6]: ip = get_ipython()
+
+    In [7]: html_formatter = ip.display_formatter.formatters['text/html']
+
+    In [8]: html_formatter.for_type(Foo, foo_to_html)
+
+For further details, see ``IPython.core.formatters``.
 
 Inline matplotlib graphics
 ==========================
@@ -448,10 +473,14 b' Inline matplotlib graphics'
 The IPython console is capable of displaying matplotlib figures inline, in SVG
 format.  If started with the ``--pylab inline`` flag, then all figures are
 rendered inline automatically.  If started with ``--pylab`` or ``--pylab <your
-backend>``, then a GUI backend will be used, but the ``pastefig()`` function is
-added to the global and ``plt`` namespaces.  You can paste any figure that is
-currently open in a window with this function; type ``pastefig?`` for
-additional details."""
+backend>``, then a GUI backend will be used, but IPython's ``display()`` and
+``getfigs()`` functions can be used to view plots inline::
+
+    In [9]: display(*getfigs())    # display all figures inline
+
+    In[10]: display(*getfigs(1,2)) # display figures 1 and 2 inline
+"""
+
 
 quick_guide = """\
 ?         -> Introduction and overview of IPython's features.

IPython/lib/pylabtools.py

@@ -36,6 +36,33 b" backends = {'tk': 'TkAgg',"
 # Matplotlib utilities
 #-----------------------------------------------------------------------------
 
+
+def getfigs(*fig_nums):
+    """Get a list of matplotlib figures by figure numbers.
+
+    If no arguments are given, all available figures are returned.  If the
+    argument list contains references to invalid figures, a warning is printed
+    but the function continues pasting further figures.
+
+    Parameters
+    ----------
+    figs : tuple
+        A tuple of ints giving the figure numbers of the figures to return.
+    """
+    from matplotlib._pylab_helpers import Gcf
+    if not fig_nums:
+        fig_managers = Gcf.get_all_fig_managers()
+        return [fm.canvas.figure for fm in fig_managers]
+    else:
+        figs = []
+        for num in fig_nums:
+            f = Gcf.figs.get(num)
+            if f is None:
+                print('Warning: figure %s not available.' % num)
+            figs.append(f.canvas.figure)
+        return figs
+
+
 def figsize(sizex, sizey):
     """Set the default figure size to be [sizex, sizey].
 
@@ -209,6 +236,8 b' def import_pylab(user_ns, backend, import_all=True, shell=None):'
         shell.user_ns_hidden['display'] = display
         user_ns['display_svg'] = display_svg
         shell.user_ns_hidden['display_svg'] = display_svg
+        user_ns['getfigs'] = getfigs
+        shell.user_ns_hidden['getfigs'] = getfigs
 
     if import_all:
         s = ("from matplotlib.pylab import *\n"