Misc updates the display system.

* PNG base64 encoding is now done at the ZMQ level, not in the
  display formatter itself.
* All formatters are documented as to the exact nature of their
  return value. PNGs are not base64 encoded, LaTeX must include
  $/$$, Javascript should not have the <script> tags, etc.
* Updated the Circle display example in docs/examples/core.
* Renamed the sympy printing extension to sympyprinting.py.

IPython/core/formatters.py

@@ -1,576 +1,593 b''
 # -*- coding: utf-8 -*-
 """Display formatters.
 
 
 Authors:
 
 * Robert Kern
 * Brian Granger
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2010, IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Stdlib imports
 import abc
 import sys
 # We must use StringIO, as cStringIO doesn't handle unicode properly.
 from StringIO import StringIO
 
 # Our own imports
 from IPython.config.configurable import Configurable
 from IPython.lib import pretty
 from IPython.utils.traitlets import Bool, Dict, Int, Str, CStr
 
 
 #-----------------------------------------------------------------------------
 # The main DisplayFormatter class
 #-----------------------------------------------------------------------------
 
 
 class DisplayFormatter(Configurable):
 
     # When set to true only the default plain text formatter will be used.
     plain_text_only = Bool(False, config=True)
 
     # A dict of formatter whose keys are format types (MIME types) and whose
     # values are subclasses of BaseFormatter.
     formatters = Dict(config=True)
     def _formatters_default(self):
         """Activate the default formatters."""
         formatter_classes = [
             PlainTextFormatter,
             HTMLFormatter,
             SVGFormatter,
             PNGFormatter,
             LatexFormatter,
             JSONFormatter,
             JavascriptFormatter
         ]
         d = {}
         for cls in formatter_classes:
             f = cls(config=self.config)
             d[f.format_type] = f
         return d
 
     def format(self, obj, include=None, exclude=None):
         """Return a format data dict for an object.
 
         By default all format types will be computed.
 
         The following MIME types are currently implemented:
 
         * text/plain
         * text/html
         * text/latex
         * application/json
         * image/png
         * immage/svg+xml
 
         Parameters
         ----------
         obj : object
             The Python object whose format data will be computed.
         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
             in this list will be computed.
         exclude : list or tuple, optional
             A list of format type string (MIME types) to exclue in the format
             data dict. If this is set all format types will be computed,
             except for those included in this argument.
 
         Returns
         -------
         format_dict : dict
             A dictionary of key/value pairs, one or each format that was
             generated for the object. The keys are the format types, which
             will usually be MIME type strings and the values and JSON'able
             data structure containing the raw data for the representation in
             that format.
         """
         format_dict = {}
 
         # If plain text only is active
         if self.plain_text_only:
             formatter = self.formatters['text/plain']
             try:
                 data = formatter(obj)
             except:
                 # FIXME: log the exception
                 raise
             if data is not None:
                 format_dict['text/plain'] = data
             return format_dict
 
         for format_type, formatter in self.formatters.items():
             if include is not None:
                 if format_type not in include:
                     continue
             if exclude is not None:
                 if format_type in exclude:
                     continue
             try:
                 data = formatter(obj)
             except:
                 # FIXME: log the exception
                 raise
             if data is not None:
                 format_dict[format_type] = data
         return format_dict
 
     @property
     def format_types(self):
         """Return the format types (MIME types) of the active formatters."""
         return self.formatters.keys()
 
 
 #-----------------------------------------------------------------------------
 # Formatters for specific format types (text, html, svg, etc.)
 #-----------------------------------------------------------------------------
 
 
 class FormatterABC(object):
     """ Abstract base class for Formatters.
 
     A formatter is a callable class that is responsible for computing the
     raw format data for a particular format type (MIME type). For example,
     an HTML formatter would have a format type of `text/html` and would return
     the HTML representation of the object when called.
     """
     __metaclass__ = abc.ABCMeta
 
     # The format type of the data returned, usually a MIME type.
     format_type = 'text/plain'
 
     # Is the formatter enabled...
     enabled = True
 
     @abc.abstractmethod
     def __call__(self, obj):
         """Return a JSON'able representation of the object.
 
         If the object cannot be formatted by this formatter, then return None
         """
         try:
             return repr(obj)
         except TypeError:
             return None
 
 
 class BaseFormatter(Configurable):
     """A base formatter class that is configurable.
 
     This formatter should usually be used as the base class of all formatters.
     It is a traited :class:`Configurable` class and includes an extensible
     API for users to determine how their objects are formatted. The following
     logic is used to find a function to format an given object.
 
     1. The object is introspected to see if it has a method with the name
        :attr:`print_method`. If is does, that object is passed to that method
        for formatting.
     2. If no print method is found, three internal dictionaries are consulted
        to find print method: :attr:`singleton_printers`, :attr:`type_printers`
        and :attr:`deferred_printers`.
 
     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.
     """
 
     format_type = Str('text/plain')
 
     enabled = Bool(True, config=True)
 
     print_method = Str('__repr__')
 
     # The singleton printers.
     # Maps the IDs of the builtin singleton objects to the format functions.
     singleton_printers = Dict(config=True)
     def _singleton_printers_default(self):
         return {}
 
     # The type-specific printers.
     # Map type objects to the format functions.
     type_printers = Dict(config=True)
     def _type_printers_default(self):
         return {}
 
     # The deferred-import type-specific printers.
     # Map (modulename, classname) pairs to the format functions.
     deferred_printers = Dict(config=True)
     def _deferred_printers_default(self):
         return {}
 
     def __call__(self, obj):
         """Compute the format for an object."""
         if self.enabled:
             obj_id = id(obj)
             try:
                 obj_class = getattr(obj, '__class__', None) or type(obj)
                 # First try to find registered singleton printers for the type.
                 try:
                     printer = self.singleton_printers[obj_id]
                 except (TypeError, KeyError):
                     pass
                 else:
                     return printer(obj)
                 # Next look for type_printers.
                 for cls in pretty._get_mro(obj_class):
                     if cls in self.type_printers:
                         return self.type_printers[cls](obj)
                     else:
                         printer = self._in_deferred_types(cls)
                         if printer is not None:
                             return printer(obj)
                 # Finally look for special method names.
                 if hasattr(obj_class, self.print_method):
                     printer = getattr(obj_class, self.print_method)
                     return printer(obj)
                 return None
             except Exception:
                 pass
         else:
             return None
 
     def for_type(self, typ, func):
         """Add a format function for a given type.
 
         Parameters
         -----------
         typ : class
             The class of the object that will be formatted using `func`.
         func : callable
             The callable that will be called to compute the format data. The
             call signature of this function is simple, it must take the
             object to be formatted and return the raw data for the given
             format. Subclasses may use a different call signature for the
             `func` argument.
         """
         oldfunc = self.type_printers.get(typ, None)
         if func is not None:
             # To support easy restoration of old printers, we need to ignore
             # Nones.
             self.type_printers[typ] = func
         return oldfunc
 
     def for_type_by_name(self, type_module, type_name, func):
         """Add a format function for a type specified by the full dotted
         module and name of the type, rather than the type of the object.
 
         Parameters
         ----------
         type_module : str
             The full dotted name of the module the type is defined in, like
             ``numpy``.
         type_name : str
             The name of the type (the class name), like ``dtype``
         func : callable
             The callable that will be called to compute the format data. The
             call signature of this function is simple, it must take the
             object to be formatted and return the raw data for the given
             format. Subclasses may use a different call signature for the
             `func` argument.
         """
         key = (type_module, type_name)
         oldfunc = self.deferred_printers.get(key, None)
         if func is not None:
             # To support easy restoration of old printers, we need to ignore
             # Nones.
             self.deferred_printers[key] = func
         return oldfunc
 
     def _in_deferred_types(self, cls):
         """
         Check if the given class is specified in the deferred type registry.
 
         Returns the printer from the registry if it exists, and None if the
         class is not in the registry. Successful matches will be moved to the
         regular type registry for future use.
         """
         mod = getattr(cls, '__module__', None)
         name = getattr(cls, '__name__', None)
         key = (mod, name)
         printer = None
         if key in self.deferred_printers:
             # Move the printer over to the regular registry.
             printer = self.deferred_printers.pop(key)
             self.type_printers[cls] = printer
         return printer
 
 
 class PlainTextFormatter(BaseFormatter):
     """The default pretty-printer.
 
     This uses :mod:`IPython.external.pretty` to compute the format data of
     the object. If the object cannot be pretty printed, :func:`repr` is used.
     See the documentation of :mod:`IPython.external.pretty` for details on
     how to write pretty printers.  Here is a simple example::
 
         def dtype_pprinter(obj, p, cycle):
             if cycle:
                 return p.text('dtype(...)')
             if hasattr(obj, 'fields'):
                 if obj.fields is None:
                     p.text(repr(obj))
                 else:
                     p.begin_group(7, 'dtype([')
                     for i, field in enumerate(obj.descr):
                         if i > 0:
                             p.text(',')
                             p.breakable()
                         p.pretty(field)
                     p.end_group(7, '])')
     """
 
     # The format type of data returned.
     format_type = Str('text/plain')
 
     # This subclass ignores this attribute as it always need to return
     # something.
     enabled = Bool(True, config=False)
 
     # Look for a _repr_pretty_ methods to use for pretty printing.
     print_method = Str('_repr_pretty_')
 
     # Whether to pretty-print or not.
     pprint = Bool(True, config=True)
 
     # Whether to be verbose or not.
     verbose = Bool(False, config=True)
 
     # The maximum width.
     max_width = Int(79, config=True)
 
     # The newline character.
     newline = Str('\n', config=True)
     
     # format-string for pprinting floats
     float_format = Str('%r')
     # setter for float precision, either int or direct format-string
     float_precision = CStr('', config=True)
     
     def _float_precision_changed(self, name, old, new):
         """float_precision changed, set float_format accordingly.
         
         float_precision can be set by int or str.
         This will set float_format, after interpreting input.
         If numpy has been imported, numpy print precision will also be set.
         
         integer `n` sets format to '%.nf', otherwise, format set directly.
         
         An empty string returns to defaults (repr for float, 8 for numpy).
         
         This parameter can be set via the '%precision' magic.
         """
         
         if '%' in new:
             # got explicit format string
             fmt = new
             try:
                 fmt%3.14159
             except Exception:
                 raise ValueError("Precision must be int or format string, not %r"%new)
         elif new:
             # otherwise, should be an int
             try:
                 i = int(new)
                 assert i >= 0
             except ValueError:
                 raise ValueError("Precision must be int or format string, not %r"%new)
             except AssertionError:
                 raise ValueError("int precision must be non-negative, not %r"%i)
             
             fmt = '%%.%if'%i
             if 'numpy' in sys.modules:
                 # set numpy precision if it has been imported
                 import numpy
                 numpy.set_printoptions(precision=i)
         else:
             # default back to repr
             fmt = '%r'
             if 'numpy' in sys.modules:
                 import numpy
                 # numpy default is 8
                 numpy.set_printoptions(precision=8)
         self.float_format = fmt
 
     # Use the default pretty printers from IPython.external.pretty.
     def _singleton_printers_default(self):
         return pretty._singleton_pprinters.copy()
 
     def _type_printers_default(self):
         d = pretty._type_pprinters.copy()
         d[float] = lambda obj,p,cycle: p.text(self.float_format%obj)
         return d
 
     def _deferred_printers_default(self):
         return pretty._deferred_type_pprinters.copy()
 
     #### FormatterABC interface ####
 
     def __call__(self, obj):
         """Compute the pretty representation of the object."""
         if not self.pprint:
             try:
                 return repr(obj)
             except TypeError:
                 return ''
         else:
             # This uses use StringIO, as cStringIO doesn't handle unicode.
             stream = StringIO()
             printer = pretty.RepresentationPrinter(stream, self.verbose,
                 self.max_width, self.newline,
                 singleton_pprinters=self.singleton_printers,
                 type_pprinters=self.type_printers,
                 deferred_pprinters=self.deferred_printers)
             printer.pretty(obj)
             printer.flush()
             return stream.getvalue()
 
 
 class HTMLFormatter(BaseFormatter):
     """An HTML formatter.
 
     To define the callables that compute the HTML representation of your
     objects, define a :meth:`_repr_html_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
+
+    The return value of this formatter should be a valid HTML snippet that
+    could be injected into an existing DOM. It should *not* include the 
+    ```<html>`` or ```<body>`` tags.
     """
     format_type = Str('text/html')
 
     print_method = Str('_repr_html_')
 
 
 class SVGFormatter(BaseFormatter):
     """An SVG formatter.
 
     To define the callables that compute the SVG representation of your
     objects, define a :meth:`_repr_svg_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
+
+    The return value of this formatter should be valid SVG enclosed in
+    ```<svg>``` tags, that could be injected into an existing DOM. It should
+    *not* include the ```<html>`` or ```<body>`` tags.
     """
     format_type = Str('image/svg+xml')
 
     print_method = Str('_repr_svg_')
 
 
 class PNGFormatter(BaseFormatter):
     """A PNG formatter.
 
     To define the callables that compute the PNG representation of your
     objects, define a :meth:`_repr_png_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
-    The raw data should be the base64 encoded raw png data.
+    The return value of this formatter should be raw PNG data, *not*
+    base64 encoded.
     """
     format_type = Str('image/png')
 
     print_method = Str('_repr_png_')
 
 
 class LatexFormatter(BaseFormatter):
     """A LaTeX formatter.
 
     To define the callables that compute the LaTeX representation of your
     objects, define a :meth:`_repr_latex_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
+
+    The return value of this formatter should be a valid LaTeX equation,
+    enclosed in either ```$``` or ```$$```.
     """
     format_type = Str('text/latex')
 
     print_method = Str('_repr_latex_')
 
 
 class JSONFormatter(BaseFormatter):
     """A JSON string formatter.
 
     To define the callables that compute the JSON string representation of
     your objects, define a :meth:`_repr_json_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
+
+    The return value of this formatter should be a valid JSON string.
     """
     format_type = Str('application/json')
 
     print_method = Str('_repr_json_')
 
 
 class JavascriptFormatter(BaseFormatter):
     """A Javascript formatter.
 
     To define the callables that compute the Javascript representation of
     your objects, define a :meth:`_repr_javascript_` method or use the 
     :meth:`for_type` or :meth:`for_type_by_name` methods to register functions
     that handle this.
+
+    The return value of this formatter should be valid Javascript code and
+    should *not* be enclosed in ```<script>``` tags.
     """
     format_type = Str('application/javascript')
 
     print_method = Str('_repr_javascript_')
 
 FormatterABC.register(BaseFormatter)
 FormatterABC.register(PlainTextFormatter)
 FormatterABC.register(HTMLFormatter)
 FormatterABC.register(SVGFormatter)
 FormatterABC.register(PNGFormatter)
 FormatterABC.register(LatexFormatter)
 FormatterABC.register(JSONFormatter)
 FormatterABC.register(JavascriptFormatter)
 
 
 def format_display_data(obj, include=None, exclude=None):
     """Return a format data dict for an object.
 
     By default all format types will be computed.
 
     The following MIME types are currently implemented:
 
     * text/plain
     * text/html
     * text/latex
     * application/json
     * image/png
     * immage/svg+xml
 
     Parameters
     ----------
     obj : object
         The Python object whose format data will be computed.
 
     Returns
     -------
     format_dict : dict
         A dictionary of key/value pairs, one or each format that was
         generated for the object. The keys are the format types, which
         will usually be MIME type strings and the values and JSON'able
         data structure containing the raw data for the representation in
         that format.
     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
         in this list will be computed.
     exclude : list or tuple, optional
         A list of format type string (MIME types) to exclue in the format
         data dict. If this is set all format types will be computed,
         except for those included in this argument.
     """
     from IPython.core.interactiveshell import InteractiveShell
 
     InteractiveShell.instance().display_formatter.format(
         obj,
         include,
         exclude
     )

IPython/extensions/sympyprinting.py

@@ -1,70 +1,70 b''
 """A print function that pretty prints sympy Basic objects.
 
 Authors:
 * Brian Granger
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-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
 #-----------------------------------------------------------------------------
 
 from IPython.lib.latextools import latex_to_png
 from IPython.testing import decorators as dec
 # use @dec.skipif_not_sympy to skip tests requiring sympy
 
 try:
     from sympy import pretty, latex
 except ImportError:
     pass
 
 
 #-----------------------------------------------------------------------------
 # Definitions of magic functions for use with IPython
 #-----------------------------------------------------------------------------
 
 def print_basic_unicode(o, p, cycle):
     """A function to pretty print sympy Basic objects."""
     if cycle:
         return p.text('Basic(...)')
     out = pretty(o, use_unicode=True)
     if '\n' in out:
         p.text(u'\n')
     p.text(out)
 
 
 def print_png(o):
     """A function to display sympy expression using LaTex -> PNG."""
     s = latex(o, mode='inline')
     # mathtext does not understand certain latex flags, so we try to replace
     # them with suitable subs.
     s = s.replace('\\operatorname','')
     s = s.replace('\\overline', '\\bar')
-    png = latex_to_png(s, encode=True)
+    png = latex_to_png(s)
     return png
 
 _loaded = False
 
 def load_ipython_extension(ip):
     """Load the extension in IPython."""
     global _loaded
     if not _loaded:
         plaintext_formatter = ip.display_formatter.formatters['text/plain']
         plaintext_formatter.for_type_by_name(
             'sympy.core.basic', 'Basic', print_basic_unicode
         )
         plaintext_formatter.for_type_by_name(
             'sympy.matrices.matrices', 'Matrix', print_basic_unicode
         )
 
         png_formatter = ip.display_formatter.formatters['image/png']
         png_formatter.for_type_by_name(
             'sympy.core.basic', 'Basic', print_png
         )
         _loaded = True
 

IPython/lib/latextools.py

@@ -1,62 +1,62 b''
 # -*- coding: utf-8 -*-
 """Tools for handling LaTeX.
 
 Authors:
 
 * Brian Granger
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2010, IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from StringIO import StringIO
 from base64 import encodestring
 
 #-----------------------------------------------------------------------------
 # Tools
 #-----------------------------------------------------------------------------
 
 
-def latex_to_png(s, encode=True):
+def latex_to_png(s, encode=False):
     """Render a LaTeX string to PNG using matplotlib.mathtext.
 
     Parameters
     ----------
     s : str
         The raw string containing valid inline LaTeX.
     encode : bool, optional
         Should the PNG data bebase64 encoded to make it JSON'able.
     """
     from matplotlib import mathtext
     
     mt = mathtext.MathTextParser('bitmap')
     f = StringIO()
     mt.to_png(f, s, fontsize=12)
     bin_data = f.getvalue()
     if encode:
         bin_data = encodestring(bin_data)
     return bin_data
 
 _data_uri_template_png = """<img src="data:image/png;base64,%s" alt=%s />"""
 
 def latex_to_html(s, alt='image'):
     """Render LaTeX to HTML with embedded PNG data using data URIs.
 
     Parameters
     ----------
     s : str
         The raw string containing valid inline LateX.
     alt : str
         The alt text to use for the HTML.
     """
     base64_data = latex_to_png(s, encode=True)
     return _data_uri_template_png  % (base64_data, alt)
 

IPython/zmq/zmqshell.py

@@ -1,588 +1,592 b''
 """A ZMQ-based subclass of InteractiveShell.
 
 This code is meant to ease the refactoring of the base InteractiveShell into
 something with a cleaner architecture for 2-process use, without actually
 breaking InteractiveShell itself.  So we're doing something a bit ugly, where
 we subclass and override what we want to fix.  Once this is working well, we
 can go back to the base class and refactor the code for a cleaner inheritance
 implementation that doesn't rely on so much monkeypatching.
 
 But this lets us maintain a fully working IPython as we develop the new
 machinery.  This should thus be thought of as scaffolding.
 """
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 # Stdlib
+from base64 import encodestring
 import inspect
 import os
 
 # Our own
 from IPython.core.interactiveshell import (
     InteractiveShell, InteractiveShellABC
 )
 from IPython.core import page
 from IPython.core.autocall import ZMQExitAutocall
 from IPython.core.displayhook import DisplayHook
 from IPython.core.displaypub import DisplayPublisher
 from IPython.core.macro import Macro
 from IPython.core.payloadpage import install_payload_page
 from IPython.utils import io
 from IPython.utils.path import get_py_filename
 from IPython.utils.traitlets import Instance, Type, Dict
 from IPython.utils.warn import warn
 from IPython.zmq.session import extract_header
 from session import Session
 
 #-----------------------------------------------------------------------------
 # Globals and side-effects
 #-----------------------------------------------------------------------------
 
 # Install the payload version of page.
 install_payload_page()
 
 #-----------------------------------------------------------------------------
 # Functions and classes
 #-----------------------------------------------------------------------------
 
 class ZMQDisplayHook(DisplayHook):
     """A displayhook subclass that publishes data using ZeroMQ."""
 
     session = Instance(Session)
     pub_socket = Instance('zmq.Socket')
     parent_header = Dict({})
 
     def set_parent(self, parent):
         """Set the parent for outbound messages."""
         self.parent_header = extract_header(parent)
 
     def start_displayhook(self):
         self.msg = self.session.msg(u'pyout', {}, parent=self.parent_header)
 
     def write_output_prompt(self):
         """Write the output prompt."""
         if self.do_full_cache:
             self.msg['content']['execution_count'] = self.prompt_count
 
     def write_format_data(self, format_dict):
+        pngdata = format_dict.get('image/png')
+        if pngdata is not None:
+            format_dict['image/png'] = encodestring(pngdata)
         self.msg['content']['data'] = format_dict
 
     def finish_displayhook(self):
         """Finish up all displayhook activities."""
         self.session.send(self.pub_socket, self.msg)
         self.msg = None
 
 
 class ZMQDisplayPublisher(DisplayPublisher):
     """A display publisher that publishes data using a ZeroMQ PUB socket."""
 
     session = Instance(Session)
     pub_socket = Instance('zmq.Socket')
     parent_header = Dict({})
 
     def set_parent(self, parent):
         """Set the parent for outbound messages."""
         self.parent_header = extract_header(parent)
 
     def publish(self, source, data, metadata=None):
         if metadata is None:
             metadata = {}
         self._validate_data(source, data, metadata)
         content = {}
         content['source'] = source
         content['data'] = data
         content['metadata'] = metadata
         self.session.send(
             self.pub_socket, u'display_data', content,
             parent=self.parent_header
         )
 
 
 class ZMQInteractiveShell(InteractiveShell):
     """A subclass of InteractiveShell for ZMQ."""
 
     displayhook_class = Type(ZMQDisplayHook)
     display_pub_class = Type(ZMQDisplayPublisher)
     
     exiter = Instance(ZMQExitAutocall)
     def _exiter_default(self):
         return ZMQExitAutocall(self)
 
     keepkernel_on_exit = None
 
     def init_environment(self):
         """Configure the user's environment.
 
         """
         env = os.environ
         # These two ensure 'ls' produces nice coloring on BSD-derived systems
         env['TERM'] = 'xterm-color'
         env['CLICOLOR'] = '1'
         # Since normal pagers don't work at all (over pexpect we don't have
         # single-key control of the subprocess), try to disable paging in
         # subprocesses as much as possible.
         env['PAGER'] = 'cat'
         env['GIT_PAGER'] = 'cat'
 
     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.displayhook.prompt1.auto_rewrite() + cmd
         payload = dict(
             source='IPython.zmq.zmqshell.ZMQInteractiveShell.auto_rewrite_input',
             transformed_input=new,
             )
         self.payload_manager.write_payload(payload)
         
     def ask_exit(self):
         """Engage the exit actions."""
         payload = dict(
             source='IPython.zmq.zmqshell.ZMQInteractiveShell.ask_exit',
             exit=True,
             keepkernel=self.keepkernel_on_exit,
             )
         self.payload_manager.write_payload(payload)
 
     def _showtraceback(self, etype, evalue, stb):
 
         exc_content = {
             u'traceback' : stb,
             u'ename' : unicode(etype.__name__),
             u'evalue' : unicode(evalue)
         }
 
         dh = self.displayhook
         # Send exception info over pub socket for other clients than the caller
         # to pick up
         exc_msg = dh.session.send(dh.pub_socket, u'pyerr', exc_content, dh.parent_header)
 
         # FIXME - Hack: store exception info in shell object.  Right now, the
         # caller is reading this info after the fact, we need to fix this logic
         # to remove this hack.  Even uglier, we need to store the error status
         # here, because in the main loop, the logic that sets it is being
         # skipped because runlines swallows the exceptions.
         exc_content[u'status'] = u'error'
         self._reply_content = exc_content
         # /FIXME
         
         return exc_content
 
     #------------------------------------------------------------------------
     # Magic overrides
     #------------------------------------------------------------------------
     # Once the base class stops inheriting from magic, this code needs to be
     # 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.
 
     def magic_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_plain_text_only',disp_formatter.plain_text_only)
         save_dstore('xmode', shell.InteractiveTB.mode)
         
         if mode == False:
             # turn on
             ptformatter.pprint = False
             disp_formatter.plain_text_only = True
             shell.magic_xmode('Plain')
         else:
             # turn off
             ptformatter.pprint = dstore.rc_pprint
             disp_formatter.plain_text_only = dstore.rc_plain_text_only
             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='IPython.zmq.zmqshell.ZMQInteractiveShell.magic_doctest_mode',
             mode=dstore.mode)
         self.payload_manager.write_payload(payload)
 
     def magic_edit(self,parameter_s='',last_call=['','']):
         """Bring up an editor and execute the resulting code.
 
         Usage:
           %edit [options] [args]
 
         %edit runs IPython's editor hook.  The default version of this hook is
         set to call the __IPYTHON__.rc.editor command.  This is read from your
         environment variable $EDITOR.  If this isn't found, it will default to
         vi under Linux/Unix and to notepad under Windows.  See the end of this
         docstring for how to change the editor hook.
 
         You can also set the value of this editor via the command line option
         '-editor' or in your ipythonrc file. This is useful if you wish to use
         specifically for IPython an editor different from your typical default
         (and for Windows users who typically don't set environment variables).
 
         This command allows you to conveniently edit multi-line code right in
         your IPython session.
         
         If called without arguments, %edit opens up an empty editor with a
         temporary file and will execute the contents of this file when you
         close it (don't forget to save it!).
 
 
         Options:
 
         -n <number>: open the editor at a specified line number.  By default,
         the IPython editor hook uses the unix syntax 'editor +N filename', but
         you can configure this by providing your own modified hook if your
         favorite editor supports line-number specifications with a different
         syntax.
         
         -p: this will call the editor with the same data as the previous time
         it was used, regardless of how long ago (in your current session) it
         was.
 
         -r: use 'raw' input.  This option only applies to input taken from the
         user's history.  By default, the 'processed' history is used, so that
         magics are loaded in their transformed version to valid Python.  If
         this option is given, the raw input as typed as the command line is
         used instead.  When you exit the editor, it will be executed by
         IPython's own processor.
         
         -x: do not execute the edited code immediately upon exit. This is
         mainly useful if you are editing programs which need to be called with
         command line arguments, which you can then do using %run.
 
 
         Arguments:
 
         If arguments are given, the following possibilites exist:
 
         - The arguments are numbers or pairs of colon-separated numbers (like
         1 4:8 9). These are interpreted as lines of previous input to be
         loaded into the editor. The syntax is the same of the %macro command.
 
         - If the argument doesn't start with a number, it is evaluated as a
         variable and its contents loaded into the editor. You can thus edit
         any string which contains python code (including the result of
         previous edits).
 
         - If the argument is the name of an object (other than a string),
         IPython will try to locate the file where it was defined and open the
         editor at the point where it is defined. You can use `%edit function`
         to load an editor exactly at the point where 'function' is defined,
         edit it and have the file be executed automatically.
 
         If the object is a macro (see %macro for details), this opens up your
         specified editor with a temporary file containing the macro's data.
         Upon exit, the macro is reloaded with the contents of the file.
 
         Note: opening at an exact line is only supported under Unix, and some
         editors (like kedit and gedit up to Gnome 2.8) do not understand the
         '+NUMBER' parameter necessary for this feature. Good editors like
         (X)Emacs, vi, jed, pico and joe all do.
 
         - If the argument is not found as a variable, IPython will look for a
         file with that name (adding .py if necessary) and load it into the
         editor. It will execute its contents with execfile() when you exit,
         loading any code in the file into your interactive namespace.
 
         After executing your code, %edit will return as output the code you
         typed in the editor (except when it was an existing file). This way
         you can reload the code in further invocations of %edit as a variable,
         via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
         the output.
 
         Note that %edit is also available through the alias %ed.
 
         This is an example of creating a simple function inside the editor and
         then modifying it. First, start up the editor:
 
         In [1]: ed
         Editing... done. Executing edited code...
         Out[1]: 'def foo():n    print "foo() was defined in an editing session"n'
 
         We can then call the function foo():
         
         In [2]: foo()
         foo() was defined in an editing session
 
         Now we edit foo.  IPython automatically loads the editor with the
         (temporary) file where foo() was previously defined:
         
         In [3]: ed foo
         Editing... done. Executing edited code...
 
         And if we call foo() again we get the modified version:
         
         In [4]: foo()
         foo() has now been changed!
 
         Here is an example of how to edit a code snippet successive
         times. First we call the editor:
 
         In [5]: ed
         Editing... done. Executing edited code...
         hello
         Out[5]: "print 'hello'n"
 
         Now we call it again with the previous output (stored in _):
 
         In [6]: ed _
         Editing... done. Executing edited code...
         hello world
         Out[6]: "print 'hello world'n"
 
         Now we call it with the output #8 (stored in _8, also as Out[8]):
 
         In [7]: ed _8
         Editing... done. Executing edited code...
         hello again
         Out[7]: "print 'hello again'n"
 
 
         Changing the default editor hook:
 
         If you wish to write your own editor hook, you can put it in a
         configuration file which you load at startup time.  The default hook
         is defined in the IPython.core.hooks module, and you can use that as a
         starting example for further modifications.  That file also has
         general instructions on how to set a new hook for use once you've
         defined it."""
         
         # FIXME: This function has become a convoluted mess.  It needs a
         # ground-up rewrite with clean, simple logic.
 
         def make_filename(arg):
             "Make a filename from the given args"
             try:
                 filename = get_py_filename(arg)
             except IOError:
                 if args.endswith('.py'):
                     filename = arg
                 else:
                     filename = None
             return filename
 
         # custom exceptions
         class DataIsObject(Exception): pass
 
         opts,args = self.parse_options(parameter_s,'prn:')
         # Set a few locals from the options for convenience:
         opts_p = opts.has_key('p')
         opts_r = opts.has_key('r')
         
         # Default line number value
         lineno = opts.get('n',None)
         if lineno is not None:
             try:
                 lineno = int(lineno)
             except:
                 warn("The -n argument must be an integer.")
                 return
 
         if opts_p:
             args = '_%s' % last_call[0]
             if not self.shell.user_ns.has_key(args):
                 args = last_call[1]
             
         # use last_call to remember the state of the previous call, but don't
         # let it be clobbered by successive '-p' calls.
         try:
             last_call[0] = self.shell.displayhook.prompt_count
             if not opts_p:
                 last_call[1] = parameter_s
         except:
             pass
 
         # by default this is done with temp files, except when the given
         # arg is a filename
         use_temp = True
 
         data = ''
         if args[0].isdigit():
             # Mode where user specifies ranges of lines, like in %macro.
             # This means that you can't edit files whose names begin with
             # numbers this way. Tough.
             ranges = args.split()
             data = ''.join(self.extract_input_slices(ranges,opts_r))
         elif args.endswith('.py'):
             filename = make_filename(args)
             use_temp = False
         elif args:
             try:
                 # Load the parameter given as a variable. If not a string,
                 # process it as an object instead (below)
 
                 #print '*** args',args,'type',type(args)  # dbg
                 data = eval(args, self.shell.user_ns)
                 if not isinstance(data, basestring):
                     raise DataIsObject
 
             except (NameError,SyntaxError):
                 # given argument is not a variable, try as a filename
                 filename = make_filename(args)
                 if filename is None:
                     warn("Argument given (%s) can't be found as a variable "
                          "or as a filename." % args)
                     return
                 use_temp = False
                 
             except DataIsObject:
                 # macros have a special edit function
                 if isinstance(data, Macro):
                     self._edit_macro(args,data)
                     return
                                 
                 # For objects, try to edit the file where they are defined
                 try:
                     filename = inspect.getabsfile(data)
                     if 'fakemodule' in filename.lower() and inspect.isclass(data):                     
                         # class created by %edit? Try to find source
                         # by looking for method definitions instead, the
                         # __module__ in those classes is FakeModule.
                         attrs = [getattr(data, aname) for aname in dir(data)]
                         for attr in attrs:
                             if not inspect.ismethod(attr):
                                 continue
                             filename = inspect.getabsfile(attr)
                             if filename and 'fakemodule' not in filename.lower():
                                 # change the attribute to be the edit target instead
                                 data = attr 
                                 break
                     
                     datafile = 1
                 except TypeError:
                     filename = make_filename(args)
                     datafile = 1
                     warn('Could not find file where `%s` is defined.\n'
                          'Opening a file named `%s`' % (args,filename))
                 # Now, make sure we can actually read the source (if it was in
                 # a temp file it's gone by now).
                 if datafile:
                     try:
                         if lineno is None:
                             lineno = inspect.getsourcelines(data)[1]
                     except IOError:
                         filename = make_filename(args)
                         if filename is None:
                             warn('The file `%s` where `%s` was defined cannot '
                                  'be read.' % (filename,data))
                             return
                 use_temp = False
 
         if use_temp:
             filename = self.shell.mktempfile(data)
             print('IPython will make a temporary file named:', filename)
 
         # Make sure we send to the client an absolute path, in case the working
         # directory of client and kernel don't match
         filename = os.path.abspath(filename)
 
         payload = {
             'source' : 'IPython.zmq.zmqshell.ZMQInteractiveShell.edit_magic',
             'filename' : filename,
             'line_number' : lineno
         }
         self.payload_manager.write_payload(payload)
 
     def magic_gui(self, *args, **kwargs):
         raise NotImplementedError(
             'GUI support must be enabled in command line options.')
 
     def magic_pylab(self, *args, **kwargs):
         raise NotImplementedError(
             'pylab support must be enabled in command line options.')
 
     # A few magics that are adapted to the specifics of using pexpect and a
     # remote terminal
 
     def magic_clear(self, arg_s):
         """Clear the terminal."""
         if os.name == 'posix':
             self.shell.system("clear")
         else:
             self.shell.system("cls")
 
     if os.name == 'nt':
         # This is the usual name in windows
         magic_cls = magic_clear
 
     # Terminal pagers won't work over pexpect, but we do have our own pager
     
     def magic_less(self, arg_s):
         """Show a file through the pager.
 
         Files ending in .py are syntax-highlighted."""
         cont = open(arg_s).read()
         if arg_s.endswith('.py'):
             cont = self.shell.pycolorize(cont)
         page.page(cont)
 
     magic_more = magic_less
 
     # Man calls a pager, so we also need to redefine it
     if os.name == 'posix':
         def magic_man(self, arg_s):
             """Find the man page for the given command and display in pager."""
             page.page(self.shell.getoutput('man %s | col -b' % arg_s,
                                            split=False))
 
     # FIXME: this is specific to the GUI, so we should let the gui app load
     # magics at startup that are only for the gui.  Once the gui app has proper
     # profile and configuration management, we can have it initialize a kernel
     # with a special config file that provides these.
     def magic_guiref(self, arg_s):
         """Show a basic reference about the GUI console."""
         from IPython.core.usage import gui_reference
         page.page(gui_reference, auto_html=True)
     
     def set_next_input(self, text):
         """Send the specified text to the frontend to be presented at the next
         input cell."""
         payload = dict(
             source='IPython.zmq.zmqshell.ZMQInteractiveShell.set_next_input', 
             text=text
         )
         self.payload_manager.write_payload(payload)
 
 InteractiveShellABC.register(ZMQInteractiveShell)

docs/examples/core/display.py

@@ -1,24 +1,27 b''
 """Code that shows off the IPython display logic.
 """
 
+from IPython.lib.latextools import latex_to_png
 from IPython.core.display import (
     display, display_pretty, display_html,
-    display_svg, display_json
+    display_svg, display_json, display_png
 )
 
 class Circle(object):
 
     def __init__(self, radius):
         self.radius = radius
 
     def _repr_pretty_(self, p, cycle):
         p.text(u"\u25CB")
 
     def _repr_html_(self):
         return "<h1>Cirle: radius=%s</h1>" % self.radius
 
     def _repr_svg_(self):
         return """<svg>
 <circle cx="100" cy="50" r="40" stroke="black" stroke-width="2" fill="red"/>
 </svg>"""
 
+    def _repr_png_(self):
+        return latex_to_png('$\circle$')