Merge pull request #3381 from minrk/retina

enable 2x (retina) display

IPython/core/display.py

@@ -1,635 +1,689 b''
 # -*- coding: utf-8 -*-
 """Top-level display functions for displaying object in different formats.
 
 Authors:
 
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #       Copyright (C) 2013 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 __future__ import print_function
 
 import os
+import struct
 
 from IPython.utils.py3compat import string_types
 
 from .displaypub import publish_display_data
 
 #-----------------------------------------------------------------------------
 # utility functions
 #-----------------------------------------------------------------------------
 
 def _safe_exists(path):
     """Check path, but don't let exceptions raise"""
     try:
         return os.path.exists(path)
     except Exception:
         return False
 
 def _merge(d1, d2):
     """Like update, but merges sub-dicts instead of clobbering at the top level.
 
     Updates d1 in-place
     """
 
     if not isinstance(d2, dict) or not isinstance(d1, dict):
         return d2
     for key, value in d2.items():
         d1[key] = _merge(d1.get(key), value)
     return d1
 
 def _display_mimetype(mimetype, objs, raw=False, metadata=None):
     """internal implementation of all display_foo methods
 
     Parameters
     ----------
     mimetype : str
         The mimetype to be published (e.g. 'image/png')
     objs : tuple of objects
         The Python objects to display, or if raw=True raw text data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     if metadata:
         metadata = {mimetype: metadata}
     if raw:
         # turn list of pngdata into list of { 'image/png': pngdata }
         objs = [ {mimetype: obj} for obj in objs ]
     display(*objs, raw=raw, metadata=metadata, include=[mimetype])
 
 #-----------------------------------------------------------------------------
 # Main functions
 #-----------------------------------------------------------------------------
 
 def display(*objs, **kwargs):
     """Display a Python object in all frontends.
 
     By default all representations will be computed and sent to the frontends.
     Frontends can decide which representation is used and how.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display.
     raw : bool, optional
         Are the objects to be displayed already mimetype-keyed dicts of raw display data,
         or Python objects that need to be formatted before display? [default: False]
     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 strings (MIME types) to exclude in the format
         data dict. If this is set all format types will be computed,
         except for those included in this argument.
     metadata : dict, optional
         A dictionary of metadata to associate with the output.
         mime-type keys in this dictionary will be associated with the individual
         representation formats, if they exist.
     """
     raw = kwargs.get('raw', False)
     include = kwargs.get('include')
     exclude = kwargs.get('exclude')
     metadata = kwargs.get('metadata')
 
     from IPython.core.interactiveshell import InteractiveShell
 
     if raw:
         for obj in objs:
             publish_display_data('display', obj, metadata)
     else:
         format = InteractiveShell.instance().display_formatter.format
         for obj in objs:
             format_dict, md_dict = format(obj, include=include, exclude=exclude)
             if metadata:
                 # kwarg-specified metadata gets precedence
                 _merge(md_dict, metadata)
             publish_display_data('display', format_dict, md_dict)
 
 
 def display_pretty(*objs, **kwargs):
     """Display the pretty (default) representation of an object.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw text data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/plain', objs, **kwargs)
 
 
 def display_html(*objs, **kwargs):
     """Display the HTML representation of an object.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw HTML data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/html', objs, **kwargs)
 
 
 def display_svg(*objs, **kwargs):
     """Display the SVG representation of an object.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw svg data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/svg+xml', objs, **kwargs)
 
 
 def display_png(*objs, **kwargs):
     """Display the PNG representation of an object.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw png data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/png', objs, **kwargs)
 
 
 def display_jpeg(*objs, **kwargs):
     """Display the JPEG representation of an object.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw JPEG data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/jpeg', objs, **kwargs)
 
 
 def display_latex(*objs, **kwargs):
     """Display the LaTeX representation of an object.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw latex data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/latex', objs, **kwargs)
 
 
 def display_json(*objs, **kwargs):
     """Display the JSON representation of an object.
 
     Note that not many frontends support displaying JSON.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw json data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/json', objs, **kwargs)
 
 
 def display_javascript(*objs, **kwargs):
     """Display the Javascript representation of an object.
 
     Parameters
     ----------
     objs : tuple of objects
         The Python objects to display, or if raw=True raw javascript data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/javascript', objs, **kwargs)
 
 #-----------------------------------------------------------------------------
 # Smart classes
 #-----------------------------------------------------------------------------
 
 
 class DisplayObject(object):
     """An object that wraps data to be displayed."""
 
     _read_flags = 'r'
 
     def __init__(self, data=None, url=None, filename=None):
         """Create a display object given raw data.
 
         When this object is returned by an expression or passed to the
         display function, it will result in the data being displayed
         in the frontend. The MIME type of the data should match the
         subclasses used, so the Png subclass should be used for 'image/png'
         data. If the data is a URL, the data will first be downloaded
         and then displayed. If
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw data or a URL or file to load the data from
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         """
         if data is not None and isinstance(data, string_types):
             if data.startswith('http') and url is None:
                 url = data
                 filename = None
                 data = None
             elif _safe_exists(data) and filename is None:
                 url = None
                 filename = data
                 data = None
 
         self.data = data
         self.url = url
         self.filename = None if filename is None else unicode(filename)
 
         self.reload()
 
     def reload(self):
         """Reload the raw data from file or URL."""
         if self.filename is not None:
             with open(self.filename, self._read_flags) as f:
                 self.data = f.read()
         elif self.url is not None:
             try:
                 import urllib2
                 response = urllib2.urlopen(self.url)
                 self.data = response.read()
                 # extract encoding from header, if there is one:
                 encoding = None
                 for sub in response.headers['content-type'].split(';'):
                     sub = sub.strip()
                     if sub.startswith('charset'):
                         encoding = sub.split('=')[-1].strip()
                         break
                 # decode data, if an encoding was specified
                 if encoding:
                     self.data = self.data.decode(encoding, 'replace')
             except:
                 self.data = None
 
 class Pretty(DisplayObject):
 
     def _repr_pretty_(self):
         return self.data
 
 
 class HTML(DisplayObject):
 
     def _repr_html_(self):
         return self.data
 
     def __html__(self):
         """
         This method exists to inform other HTML-using modules (e.g. Markupsafe,
         htmltag, etc) that this object is HTML and does not need things like
         special characters (<>&) escaped.
         """
         return self._repr_html_()
 
 
 class Math(DisplayObject):
 
     def _repr_latex_(self):
         s = self.data.strip('$')
         return "$$%s$$" % s
 
 
 class Latex(DisplayObject):
 
     def _repr_latex_(self):
         return self.data
 
 
 class SVG(DisplayObject):
 
     # wrap data in a property, which extracts the <svg> tag, discarding
     # document headers
     _data = None
 
     @property
     def data(self):
         return self._data
 
     @data.setter
     def data(self, svg):
         if svg is None:
             self._data = None
             return
         # parse into dom object
         from xml.dom import minidom
         x = minidom.parseString(svg)
         # get svg tag (should be 1)
         found_svg = x.getElementsByTagName('svg')
         if found_svg:
             svg = found_svg[0].toxml()
         else:
             # fallback on the input, trust the user
             # but this is probably an error.
             pass
         self._data = svg
 
     def _repr_svg_(self):
         return self.data
 
 
 class JSON(DisplayObject):
 
     def _repr_json_(self):
         return self.data
 
 css_t = """$("head").append($("<link/>").attr({
   rel:  "stylesheet",
   type: "text/css",
   href: "%s"
 }));
 """
 
 lib_t1 = """$.getScript("%s", function () {
 """
 lib_t2 = """});
 """
 
 class Javascript(DisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, lib=None, css=None):
         """Create a Javascript display object given raw data.
 
         When this object is returned by an expression or passed to the
         display function, it will result in the data being displayed
         in the frontend. If the data is a URL, the data will first be
         downloaded and then displayed.
 
         In the Notebook, the containing element will be available as `element`,
         and jQuery will be available.  The output area starts hidden, so if
         the js appends content to `element` that should be visible, then
         it must call `container.show()` to unhide the area.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The Javascript source code or a URL to download it from.
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         lib : list or str
             A sequence of Javascript library URLs to load asynchronously before
             running the source code. The full URLs of the libraries should
             be given. A single Javascript library URL can also be given as a
             string.
         css: : list or str
             A sequence of css files to load before running the source code.
             The full URLs of the css files should be given. A single css URL
             can also be given as a string.
         """
         if isinstance(lib, basestring):
             lib = [lib]
         elif lib is None:
             lib = []
         if isinstance(css, basestring):
             css = [css]
         elif css is None:
             css = []
         if not isinstance(lib, (list,tuple)):
             raise TypeError('expected sequence, got: %r' % lib)
         if not isinstance(css, (list,tuple)):
             raise TypeError('expected sequence, got: %r' % css)
         self.lib = lib
         self.css = css
         super(Javascript, self).__init__(data=data, url=url, filename=filename)
 
     def _repr_javascript_(self):
         r = ''
         for c in self.css:
             r += css_t % c
         for l in self.lib:
             r += lib_t1 % l
         r += self.data
         r += lib_t2*len(self.lib)
         return r
 
 # constants for identifying png/jpeg data
 _PNG = b'\x89PNG\r\n\x1a\n'
 _JPEG = b'\xff\xd8'
 
+def _pngxy(data):
+    """read the (width, height) from a PNG header"""
+    ihdr = data.index(b'IHDR')
+    # next 8 bytes are width/height
+    w4h4 = data[ihdr+4:ihdr+12]
+    return struct.unpack('>ii', w4h4)
+
+def _jpegxy(data):
+    """read the (width, height) from a JPEG header"""
+    # adapted from http://www.64lines.com/jpeg-width-height
+    
+    idx = 4
+    while True:
+        block_size = struct.unpack('>H', data[idx:idx+2])[0]
+        idx = idx + block_size
+        if data[idx:idx+2] == b'\xFF\xC0':
+            # found Start of Frame
+            iSOF = idx
+            break
+        else:
+            # read another block
+            idx += 2
+
+    h, w = struct.unpack('>HH', data[iSOF+5:iSOF+9])
+    return w, h
+
 class Image(DisplayObject):
 
     _read_flags = 'rb'
     _FMT_JPEG = u'jpeg'
     _FMT_PNG = u'png'
     _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG]
 
-    def __init__(self, data=None, url=None, filename=None, format=u'png', embed=None, width=None, height=None):
+    def __init__(self, data=None, url=None, filename=None, format=u'png', embed=None, width=None, height=None, retina=False):
         """Create a display an PNG/JPEG image given raw data.
 
         When this object is returned by an expression or passed to the
         display function, it will result in the image being displayed
         in the frontend.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw image data or a URL or filename to load the data from.
             This always results in embedded image data.
         url : unicode
             A URL to download the data from. If you specify `url=`,
             the image data will not be embedded unless you also specify `embed=True`.
         filename : unicode
             Path to a local file to load the data from.
             Images from a file are always embedded.
         format : unicode
             The format of the image data (png/jpeg/jpg). If a filename or URL is given
             for format will be inferred from the filename extension.
         embed : bool
             Should the image data be embedded using a data URI (True) or be
             loaded using an <img> tag. Set this to True if you want the image
             to be viewable later with no internet connection in the notebook.
 
             Default is `True`, unless the keyword argument `url` is set, then
             default value is `False`.
 
             Note that QtConsole is not able to display images if `embed` is set to `False`
         width : int
             Width to which to constrain the image in html
         height : int
             Height to which to constrain the image in html
+        retina : bool
+            Automatically set the width and height to half of the measured
+            width and height.
+            This only works for embedded images because it reads the width/height
+            from image data.
+            For non-embedded images, you can just set the desired display width
+            and height directly.
 
         Examples
         --------
         # embedded image data, works in qtconsole and notebook
         # when passed positionally, the first arg can be any of raw image data,
         # a URL, or a filename from which to load image data.
         # The result is always embedding image data for inline images.
         Image('http://www.google.fr/images/srpr/logo3w.png')
         Image('/path/to/image.jpg')
         Image(b'RAW_PNG_DATA...')
 
         # Specifying Image(url=...) does not embed the image data,
         # it only generates `<img>` tag with a link to the source.
         # This will not work in the qtconsole or offline.
         Image(url='http://www.google.fr/images/srpr/logo3w.png')
 
         """
         if filename is not None:
             ext = self._find_ext(filename)
         elif url is not None:
             ext = self._find_ext(url)
         elif data is None:
             raise ValueError("No image data found. Expecting filename, url, or data.")
         elif isinstance(data, string_types) and (
             data.startswith('http') or _safe_exists(data)
         ):
             ext = self._find_ext(data)
         else:
             ext = None
 
         if ext is not None:
             format = ext.lower()
             if ext == u'jpg' or ext == u'jpeg':
                 format = self._FMT_JPEG
             if ext == u'png':
                 format = self._FMT_PNG
         elif isinstance(data, bytes) and format == 'png':
             # infer image type from image data header,
             # only if format might not have been specified.
             if data[:2] == _JPEG:
                 format = 'jpeg'
 
         self.format = unicode(format).lower()
         self.embed = embed if embed is not None else (url is None)
 
         if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
             raise ValueError("Cannot embed the '%s' image format" % (self.format))
         self.width = width
         self.height = height
+        self.retina = retina
         super(Image, self).__init__(data=data, url=url, filename=filename)
 
+        if retina:
+            self._retina_shape()
+    
+    def _retina_shape(self):
+        """load pixel-doubled width and height from image data"""
+        if not self.embed:
+            return
+        if self.format == 'png':
+            w, h = _pngxy(self.data)
+        elif self.format == 'jpeg':
+            w, h = _jpegxy(self.data)
+        else:
+            # retina only supports png
+            return
+        self.width = w // 2
+        self.height = h // 2
+
     def reload(self):
         """Reload the raw data from file or URL."""
         if self.embed:
             super(Image,self).reload()
+            if self.retina:
+                self._retina_shape()
 
     def _repr_html_(self):
         if not self.embed:
             width = height = ''
             if self.width:
                 width = ' width="%d"' % self.width
             if self.height:
                 height = ' height="%d"' % self.height
             return u'<img src="%s"%s%s/>' % (self.url, width, height)
 
     def _data_and_metadata(self):
         """shortcut for returning metadata with shape information, if defined"""
         md = {}
         if self.width:
             md['width'] = self.width
         if self.height:
             md['height'] = self.height
         if md:
             return self.data, md
         else:
             return self.data
 
     def _repr_png_(self):
         if self.embed and self.format == u'png':
             return self._data_and_metadata()
 
     def _repr_jpeg_(self):
         if self.embed and (self.format == u'jpeg' or self.format == u'jpg'):
             return self._data_and_metadata()
 
     def _find_ext(self, s):
         return unicode(s.split('.')[-1].lower())
 
 
 def clear_output(stdout=True, stderr=True, other=True):
     """Clear the output of the current cell receiving output.
 
     Optionally, each of stdout/stderr or other non-stream data (e.g. anything
     produced by display()) can be excluded from the clear event.
 
     By default, everything is cleared.
 
     Parameters
     ----------
     stdout : bool [default: True]
         Whether to clear stdout.
     stderr : bool [default: True]
         Whether to clear stderr.
     other : bool [default: True]
         Whether to clear everything else that is not stdout/stderr
         (e.g. figures,images,HTML, any result of display()).
     """
     from IPython.core.interactiveshell import InteractiveShell
     if InteractiveShell.initialized():
         InteractiveShell.instance().display_pub.clear_output(
             stdout=stdout, stderr=stderr, other=other,
         )
     else:
         from IPython.utils import io
         if stdout:
             print('\033[2K\r', file=io.stdout, end='')
             io.stdout.flush()
         if stderr:
             print('\033[2K\r', file=io.stderr, end='')
             io.stderr.flush()
 

IPython/core/pylabtools.py

@@ -1,370 +1,385 b''
 # -*- coding: utf-8 -*-
 """Pylab (matplotlib) support utilities.
 
 Authors
 -------
 
 * Fernando Perez.
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
-#  Copyright (C) 2009-2011  The IPython Development Team
+#  Copyright (C) 2009  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
 #-----------------------------------------------------------------------------
 
 import sys
 from io import BytesIO
 
+from IPython.core.display import _pngxy
 from IPython.utils.decorators import flag_calls
 
 # If user specifies a GUI, that dictates the backend, otherwise we read the
 # user's mpl default from the mpl rc structure
 backends = {'tk': 'TkAgg',
             'gtk': 'GTKAgg',
             'wx': 'WXAgg',
             'qt': 'Qt4Agg', # qt3 not supported
             'qt4': 'Qt4Agg',
             'osx': 'MacOSX',
             'inline' : 'module://IPython.kernel.zmq.pylab.backend_inline'}
 
 # We also need a reverse backends2guis mapping that will properly choose which
 # GUI support to activate based on the desired matplotlib backend.  For the
 # most part it's just a reverse of the above dict, but we also need to add a
 # few others that map to the same GUI manually:
 backend2gui = dict(zip(backends.values(), backends.keys()))
 # In the reverse mapping, there are a few extra valid matplotlib backends that
 # map to the same GUI support
 backend2gui['GTK'] = backend2gui['GTKCairo'] = 'gtk'
 backend2gui['WX'] = 'wx'
 backend2gui['CocoaAgg'] = 'osx'
 
 #-----------------------------------------------------------------------------
 # 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)
             else:
                 figs.append(f.canvas.figure)
         return figs
 
 
 def figsize(sizex, sizey):
     """Set the default figure size to be [sizex, sizey].
 
     This is just an easy to remember, convenience wrapper that sets::
 
       matplotlib.rcParams['figure.figsize'] = [sizex, sizey]
     """
     import matplotlib
     matplotlib.rcParams['figure.figsize'] = [sizex, sizey]
 
 
 def print_figure(fig, fmt='png'):
     """Convert a figure to svg or png for inline display."""
+    from matplotlib import rcParams
     # When there's an empty figure, we shouldn't return anything, otherwise we
     # get big blank areas in the qt console.
     if not fig.axes and not fig.lines:
         return
 
     fc = fig.get_facecolor()
     ec = fig.get_edgecolor()
     bytes_io = BytesIO()
+    dpi = rcParams['savefig.dpi']
+    if fmt == 'retina':
+        dpi = dpi * 2
+        fmt = 'png'
     fig.canvas.print_figure(bytes_io, format=fmt, bbox_inches='tight',
-                            facecolor=fc, edgecolor=ec)
+                            facecolor=fc, edgecolor=ec, dpi=dpi)
     data = bytes_io.getvalue()
     return data
 
+def retina_figure(fig):
+    """format a figure as a pixel-doubled (retina) PNG"""
+    pngdata = print_figure(fig, fmt='retina')
+    w, h = _pngxy(pngdata)
+    metadata = dict(width=w//2, height=h//2)
+    return pngdata, metadata
 
 # We need a little factory function here to create the closure where
 # safe_execfile can live.
 def mpl_runner(safe_execfile):
     """Factory to return a matplotlib-enabled runner for %run.
 
     Parameters
     ----------
     safe_execfile : function
       This must be a function with the same interface as the
       :meth:`safe_execfile` method of IPython.
 
     Returns
     -------
     A function suitable for use as the ``runner`` argument of the %run magic
     function.
     """
     
     def mpl_execfile(fname,*where,**kw):
         """matplotlib-aware wrapper around safe_execfile.
 
         Its interface is identical to that of the :func:`execfile` builtin.
 
         This is ultimately a call to execfile(), but wrapped in safeties to
         properly handle interactive rendering."""
 
         import matplotlib
         import matplotlib.pylab as pylab
 
         #print '*** Matplotlib runner ***' # dbg
         # turn off rendering until end of script
         is_interactive = matplotlib.rcParams['interactive']
         matplotlib.interactive(False)
         safe_execfile(fname,*where,**kw)
         matplotlib.interactive(is_interactive)
         # make rendering call now, if the user tried to do it
         if pylab.draw_if_interactive.called:
             pylab.draw()
             pylab.draw_if_interactive.called = False
 
     return mpl_execfile
 
 
 def select_figure_format(shell, fmt):
-    """Select figure format for inline backend, either 'png' or 'svg'.
+    """Select figure format for inline backend, can be 'png', 'retina', or 'svg'.
 
     Using this method ensures only one figure format is active at a time.
     """
     from matplotlib.figure import Figure
     from IPython.kernel.zmq.pylab import backend_inline
 
     svg_formatter = shell.display_formatter.formatters['image/svg+xml']
     png_formatter = shell.display_formatter.formatters['image/png']
 
     if fmt=='png':
         svg_formatter.type_printers.pop(Figure, None)
         png_formatter.for_type(Figure, lambda fig: print_figure(fig, 'png'))
+    elif fmt in ('png2x', 'retina'):
+        svg_formatter.type_printers.pop(Figure, None)
+        png_formatter.for_type(Figure, retina_figure)
     elif fmt=='svg':
         png_formatter.type_printers.pop(Figure, None)
         svg_formatter.for_type(Figure, lambda fig: print_figure(fig, 'svg'))
     else:
-        raise ValueError("supported formats are: 'png', 'svg', not %r"%fmt)
+        raise ValueError("supported formats are: 'png', 'retina', 'svg', not %r" % fmt)
 
     # set the format to be used in the backend()
     backend_inline._figure_format = fmt
 
 #-----------------------------------------------------------------------------
 # Code for initializing matplotlib and importing pylab
 #-----------------------------------------------------------------------------
 
 
 def find_gui_and_backend(gui=None, gui_select=None):
     """Given a gui string return the gui and mpl backend.
 
     Parameters
     ----------
     gui : str
         Can be one of ('tk','gtk','wx','qt','qt4','inline').
     gui_select : str
         Can be one of ('tk','gtk','wx','qt','qt4','inline').
         This is any gui already selected by the shell.
 
     Returns
     -------
     A tuple of (gui, backend) where backend is one of ('TkAgg','GTKAgg',
     'WXAgg','Qt4Agg','module://IPython.kernel.zmq.pylab.backend_inline').
     """
 
     import matplotlib
 
     if gui and gui != 'auto':
         # select backend based on requested gui
         backend = backends[gui]
     else:
         backend = matplotlib.rcParams['backend']
         # In this case, we need to find what the appropriate gui selection call
         # should be for IPython, so we can activate inputhook accordingly
         gui = backend2gui.get(backend, None)
 
         # If we have already had a gui active, we need it and inline are the
         # ones allowed.
         if gui_select and gui != gui_select:
             gui = gui_select
             backend = backends[gui]
 
     return gui, backend
 
 
 def activate_matplotlib(backend):
     """Activate the given backend and set interactive to True."""
 
     import matplotlib
     matplotlib.interactive(True)
 
     # Matplotlib had a bug where even switch_backend could not force
     # the rcParam to update. This needs to be set *before* the module
     # magic of switch_backend().
     matplotlib.rcParams['backend'] = backend
 
     import matplotlib.pyplot
     matplotlib.pyplot.switch_backend(backend)
 
     # This must be imported last in the matplotlib series, after
     # backend/interactivity choices have been made
     import matplotlib.pylab as pylab
 
     pylab.show._needmain = False
     # We need to detect at runtime whether show() is called by the user.
     # For this, we wrap it into a decorator which adds a 'called' flag.
     pylab.draw_if_interactive = flag_calls(pylab.draw_if_interactive)
 
 
 def import_pylab(user_ns, import_all=True):
     """Import the standard pylab symbols into user_ns."""
 
     # Import numpy as np/pyplot as plt are conventions we're trying to
     # somewhat standardize on.  Making them available to users by default
     # will greatly help this.
     s = ("import numpy\n"
           "import matplotlib\n"
           "from matplotlib import pylab, mlab, pyplot\n"
           "np = numpy\n"
           "plt = pyplot\n"
           )
     exec s in user_ns
 
     if import_all:
         s = ("from matplotlib.pylab import *\n"
              "from numpy import *\n")
         exec s in user_ns
 
 
 def configure_inline_support(shell, backend, user_ns=None):
     """Configure an IPython shell object for matplotlib use.
 
     Parameters
     ----------
     shell : InteractiveShell instance
 
     backend : matplotlib backend
 
     user_ns : dict
       A namespace where all configured variables will be placed.  If not given,
       the `user_ns` attribute of the shell object is used.
     """
     # If using our svg payload backend, register the post-execution
     # function that will pick up the results for display.  This can only be
     # done with access to the real shell object.
 
     # Note: if we can't load the inline backend, then there's no point
     # continuing (such as in terminal-only shells in environments without
     # zeromq available).
     try:
         from IPython.kernel.zmq.pylab.backend_inline import InlineBackend
     except ImportError:
         return
     from matplotlib import pyplot
 
     user_ns = shell.user_ns if user_ns is None else user_ns
     
     cfg = InlineBackend.instance(config=shell.config)
     cfg.shell = shell
     if cfg not in shell.configurables:
         shell.configurables.append(cfg)
 
     if backend == backends['inline']:
         from IPython.kernel.zmq.pylab.backend_inline import flush_figures
         shell.register_post_execute(flush_figures)
 
         # Save rcParams that will be overwrittern
         shell._saved_rcParams = dict()
         for k in cfg.rc:
             shell._saved_rcParams[k] = pyplot.rcParams[k]
         # load inline_rc
         pyplot.rcParams.update(cfg.rc)
         # Add 'figsize' to pyplot and to the user's namespace
         user_ns['figsize'] = pyplot.figsize = figsize
     else:
         from IPython.kernel.zmq.pylab.backend_inline import flush_figures
         if flush_figures in shell._post_execute:
             shell._post_execute.pop(flush_figures)
         if hasattr(shell, '_saved_rcParams'):
             pyplot.rcParams.update(shell._saved_rcParams)
             del shell._saved_rcParams
 
     # Setup the default figure format
     fmt = cfg.figure_format
     select_figure_format(shell, fmt)
 
     # The old pastefig function has been replaced by display
     from IPython.core.display import display
     # Add display and getfigs to the user's namespace
     user_ns['display'] = display
     user_ns['getfigs'] = getfigs
 
 
 def pylab_activate(user_ns, gui=None, import_all=True, shell=None, welcome_message=False):
     """Activate pylab mode in the user's namespace.
 
     Loads and initializes numpy, matplotlib and friends for interactive use.
 
     Parameters
     ----------
     user_ns : dict
       Namespace where the imports will occur.
 
     gui : optional, string
       A valid gui name following the conventions of the %gui magic.
 
     import_all : optional, boolean
       If true, an 'import *' is done from numpy and pylab.
 
     welcome_message : optional, boolean
       If true, print a welcome message about pylab, which includes the backend
       being used.
 
     Returns
     -------
     The actual gui used (if not given as input, it was obtained from matplotlib
     itself, and will be needed next to configure IPython's gui integration.
     """
     pylab_gui_select = shell.pylab_gui_select if shell is not None else None
     # Try to find the appropriate gui and backend for the settings
     gui, backend = find_gui_and_backend(gui, pylab_gui_select)
     if shell is not None and gui != 'inline':
         # If we have our first gui selection, store it
         if pylab_gui_select is None:
             shell.pylab_gui_select = gui
         # Otherwise if they are different
         elif gui != pylab_gui_select:
             print ('Warning: Cannot change to a different GUI toolkit: %s.'
                     ' Using %s instead.' % (gui, pylab_gui_select))
             gui, backend = find_gui_and_backend(pylab_gui_select)
     activate_matplotlib(backend)
     import_pylab(user_ns, import_all)
     if shell is not None:
         configure_inline_support(shell, backend, user_ns)
     if welcome_message:
         print """
 Welcome to pylab, a matplotlib-based Python environment [backend: %s].
 For more information, type 'help(pylab)'.""" % backend
         # flush stdout, just to be safe
         sys.stdout.flush()
 
     return gui

IPython/core/tests/test_display.py

@@ -1,38 +1,56 b''
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010-2011 The IPython Development Team.
 #
 #  Distributed under the terms of the BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 import os
 
 import nose.tools as nt
 
 from IPython.core import display
 from IPython.utils import path as ipath
 
 def test_image_size():
     """Simple test for display.Image(args, width=x,height=y)"""
     thisurl = 'http://www.google.fr/images/srpr/logo3w.png'
     img = display.Image(url=thisurl, width=200, height=200)
     nt.assert_equal(u'<img src="%s" width="200" height="200"/>' % (thisurl), img._repr_html_())
     img = display.Image(url=thisurl, width=200)
     nt.assert_equal(u'<img src="%s" width="200"/>' % (thisurl), img._repr_html_())
     img = display.Image(url=thisurl)
     nt.assert_equal(u'<img src="%s"/>' % (thisurl), img._repr_html_())
 
+def test_retina_png():
+    here = os.path.dirname(__file__)
+    img = display.Image(os.path.join(here, "2x2.png"), retina=True)
+    nt.assert_equal(img.height, 1)
+    nt.assert_equal(img.width, 1)
+    data, md = img._repr_png_()
+    nt.assert_equal(md['width'], 1)
+    nt.assert_equal(md['height'], 1)
+
+def test_retina_jpeg():
+    here = os.path.dirname(__file__)
+    img = display.Image(os.path.join(here, "2x2.jpg"), retina=True)
+    nt.assert_equal(img.height, 1)
+    nt.assert_equal(img.width, 1)
+    data, md = img._repr_jpeg_()
+    nt.assert_equal(md['width'], 1)
+    nt.assert_equal(md['height'], 1)
+
 def test_image_filename_defaults():
     '''test format constraint, and validity of jpeg and png'''
     tpath = ipath.get_ipython_package_dir()
     nt.assert_raises(ValueError, display.Image, filename=os.path.join(tpath, 'testing/tests/badformat.gif'),
                      embed=True)
     nt.assert_raises(ValueError, display.Image)
     nt.assert_raises(ValueError, display.Image, data='this is not an image', format='badformat', embed=True)
     imgfile = os.path.join(tpath, 'html/static/base/images/ipynblogo.png')
     img = display.Image(filename=imgfile)
     nt.assert_equal('png', img.format)
     nt.assert_is_not_none(img._repr_png_())
     img = display.Image(filename=os.path.join(tpath, 'testing/tests/logo.jpg'), embed=False)
     nt.assert_equal('jpeg', img.format)
     nt.assert_is_none(img._repr_jpeg_())

IPython/kernel/zmq/pylab/backend_inline.py

@@ -1,215 +1,215 b''
 """Produce SVG versions of active plots for display by the rich Qt frontend.
 """
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 # Standard library imports
 import sys
 
 # Third-party imports
 import matplotlib
 from matplotlib.backends.backend_agg import new_figure_manager, FigureCanvasAgg
 from matplotlib._pylab_helpers import Gcf
 
 # Local imports.
 from IPython.config.configurable import SingletonConfigurable
 from IPython.core.display import display
 from IPython.core.displaypub import publish_display_data
 from IPython.core.pylabtools import print_figure, select_figure_format
-from IPython.utils.traitlets import Dict, Instance, CaselessStrEnum, CBool
+from IPython.utils.traitlets import Dict, Instance, CaselessStrEnum, Bool
 from IPython.utils.warn import warn
 
 #-----------------------------------------------------------------------------
 # Configurable for inline backend options
 #-----------------------------------------------------------------------------
 # inherit from InlineBackendConfig for deprecation purposes
 class InlineBackendConfig(SingletonConfigurable):
     pass
 
 class InlineBackend(InlineBackendConfig):
     """An object to store configuration of the inline backend."""
 
     def _config_changed(self, name, old, new):
         # warn on change of renamed config section
         if new.InlineBackendConfig != old.InlineBackendConfig:
             warn("InlineBackendConfig has been renamed to InlineBackend")
         super(InlineBackend, self)._config_changed(name, old, new)
 
     # The typical default figure size is too large for inline use,
     # so we shrink the figure size to 6x4, and tweak fonts to
     # make that fit.
     rc = Dict({'figure.figsize': (6.0,4.0),
         # play nicely with white background in the Qt and notebook frontend
         'figure.facecolor': 'white',
         'figure.edgecolor': 'white',
         # 12pt labels get cutoff on 6x4 logplots, so use 10pt.
         'font.size': 10,
         # 72 dpi matches SVG/qtconsole
         # this only affects PNG export, as SVG has no dpi setting
         'savefig.dpi': 72,
         # 10pt still needs a little more room on the xlabel:
         'figure.subplot.bottom' : .125
         }, config=True,
         help="""Subset of matplotlib rcParams that should be different for the
         inline backend."""
     )
 
-    figure_format = CaselessStrEnum(['svg', 'png'], default_value='png', config=True,
+    figure_format = CaselessStrEnum(['svg', 'png', 'retina'], default_value='png', config=True,
         help="The image format for figures with the inline backend.")
 
     def _figure_format_changed(self, name, old, new):
         if self.shell is None:
             return
         else:
             select_figure_format(self.shell, new)
     
-    close_figures = CBool(True, config=True,
+    close_figures = Bool(True, config=True,
         help="""Close all figures at the end of each cell.
         
         When True, ensures that each cell starts with no active figures, but it
         also means that one must keep track of references in order to edit or
         redraw figures in subsequent cells. This mode is ideal for the notebook,
         where residual plots from other cells might be surprising.
         
         When False, one must call figure() to create new figures. This means
         that gcf() and getfigs() can reference figures created in other cells,
         and the active figure can continue to be edited with pylab/pyplot
         methods that reference the current active figure. This mode facilitates
         iterative editing of figures, and behaves most consistently with
         other matplotlib backends, but figure barriers between cells must
         be explicit.
         """)
 
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
 
 
 #-----------------------------------------------------------------------------
 # Functions
 #-----------------------------------------------------------------------------
 
 def show(close=None):
     """Show all figures as SVG/PNG payloads sent to the IPython clients.
 
     Parameters
     ----------
     close : bool, optional
       If true, a ``plt.close('all')`` call is automatically issued after
       sending all the figures. If this is set, the figures will entirely
       removed from the internal list of figures.
     """
     if close is None:
         close = InlineBackend.instance().close_figures
     try:
         for figure_manager in Gcf.get_all_fig_managers():
             display(figure_manager.canvas.figure)
     finally:
         show._to_draw = []
         if close:
             matplotlib.pyplot.close('all')
 
 
 
 # This flag will be reset by draw_if_interactive when called
 show._draw_called = False
 # list of figures to draw when flush_figures is called
 show._to_draw = []
 
 
 def draw_if_interactive():
     """
     Is called after every pylab drawing command
     """
     # signal that the current active figure should be sent at the end of
     # execution.  Also sets the _draw_called flag, signaling that there will be
     # something to send.  At the end of the code execution, a separate call to
     # flush_figures() will act upon these values
 
     fig = Gcf.get_active().canvas.figure
 
     # Hack: matplotlib FigureManager objects in interacive backends (at least
     # in some of them) monkeypatch the figure object and add a .show() method
     # to it.  This applies the same monkeypatch in order to support user code
     # that might expect `.show()` to be part of the official API of figure
     # objects.
     # For further reference:
     # https://github.com/ipython/ipython/issues/1612
     # https://github.com/matplotlib/matplotlib/issues/835
     
     if not hasattr(fig, 'show'):
         # Queue up `fig` for display
         fig.show = lambda *a: display(fig)
 
     # If matplotlib was manually set to non-interactive mode, this function
     # should be a no-op (otherwise we'll generate duplicate plots, since a user
     # who set ioff() manually expects to make separate draw/show calls).
     if not matplotlib.is_interactive():
         return
 
     # ensure current figure will be drawn, and each subsequent call
     # of draw_if_interactive() moves the active figure to ensure it is
     # drawn last
     try:
         show._to_draw.remove(fig)
     except ValueError:
         # ensure it only appears in the draw list once
         pass
     # Queue up the figure for drawing in next show() call
     show._to_draw.append(fig)
     show._draw_called = True
 
 
 def flush_figures():
     """Send all figures that changed
 
     This is meant to be called automatically and will call show() if, during
     prior code execution, there had been any calls to draw_if_interactive.
     
     This function is meant to be used as a post_execute callback in IPython,
     so user-caused errors are handled with showtraceback() instead of being
     allowed to raise.  If this function is not called from within IPython,
     then these exceptions will raise.
     """
     if not show._draw_called:
         return
     
     if InlineBackend.instance().close_figures:
         # ignore the tracking, just draw and close all figures
         try:
             return show(True)
         except Exception as e:
             # safely show traceback if in IPython, else raise
             try:
                 get_ipython
             except NameError:
                 raise e
             else:
                 get_ipython().showtraceback()
                 return
     try:
         # exclude any figures that were closed:
         active = set([fm.canvas.figure for fm in Gcf.get_all_fig_managers()])
         for fig in [ fig for fig in show._to_draw if fig in active ]:
             try:
                 display(fig)
             except Exception as e:
                 # safely show traceback if in IPython, else raise
                 try:
                     get_ipython
                 except NameError:
                     raise e
                 else:
                     get_ipython().showtraceback()
                     break
     finally:
         # clear flags for next round
         show._to_draw = []
         show._draw_called = False
 
 
 # Changes to matplotlib in version 1.2 requires a mpl backend to supply a default
 # figurecanvas. This is set here to a Agg canvas
 # See https://github.com/matplotlib/matplotlib/pull/1125
 FigureCanvas = FigureCanvasAgg
 

setupbase.py

@@ -1,468 +1,469 b''
 # encoding: utf-8
 """
 This module defines the things that are used in setup.py for building IPython
 
 This includes:
 
     * The basic arguments to setup
     * Functions for finding things like packages, package data, etc.
     * A function for checking dependencies.
 """
 from __future__ import print_function
 
 #-------------------------------------------------------------------------------
 #  Copyright (C) 2008  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
 #-------------------------------------------------------------------------------
 import os
 import sys
 
 try:
     from configparser import ConfigParser
 except:
     from ConfigParser import ConfigParser
 from distutils.command.build_py import build_py
 from distutils.cmd import Command
 from glob import glob
 
 from setupext import install_data_ext
 
 #-------------------------------------------------------------------------------
 # Useful globals and utility functions
 #-------------------------------------------------------------------------------
 
 # A few handy globals
 isfile = os.path.isfile
 pjoin = os.path.join
 repo_root = os.path.dirname(os.path.abspath(__file__))
 
 def oscmd(s):
     print(">", s)
     os.system(s)
 
 # Py3 compatibility hacks, without assuming IPython itself is installed with
 # the full py3compat machinery.
 
 try:
     execfile
 except NameError:
     def execfile(fname, globs, locs=None):
         locs = locs or globs
         exec(compile(open(fname).read(), fname, "exec"), globs, locs)
 
 # A little utility we'll need below, since glob() does NOT allow you to do
 # exclusion on multiple endings!
 def file_doesnt_endwith(test,endings):
     """Return true if test is a file and its name does NOT end with any
     of the strings listed in endings."""
     if not isfile(test):
         return False
     for e in endings:
         if test.endswith(e):
             return False
     return True
 
 #---------------------------------------------------------------------------
 # Basic project information
 #---------------------------------------------------------------------------
 
 # release.py contains version, authors, license, url, keywords, etc.
 execfile(pjoin(repo_root, 'IPython','core','release.py'), globals())
 
 # Create a dict with the basic information
 # This dict is eventually passed to setup after additional keys are added.
 setup_args = dict(
       name             = name,
       version          = version,
       description      = description,
       long_description = long_description,
       author           = author,
       author_email     = author_email,
       url              = url,
       download_url     = download_url,
       license          = license,
       platforms        = platforms,
       keywords         = keywords,
       classifiers      = classifiers,
       cmdclass         = {'install_data': install_data_ext},
       )
 
 
 #---------------------------------------------------------------------------
 # Find packages
 #---------------------------------------------------------------------------
 
 def find_packages():
     """
     Find all of IPython's packages.
     """
     excludes = ['deathrow', 'quarantine']
     packages = []
     for dir,subdirs,files in os.walk('IPython'):
         package = dir.replace(os.path.sep, '.')
         if any(package.startswith('IPython.'+exc) for exc in excludes):
             # package is to be excluded (e.g. deathrow)
             continue
         if '__init__.py' not in files:
             # not a package
             continue
         packages.append(package)
     return packages
 
 #---------------------------------------------------------------------------
 # Find package data
 #---------------------------------------------------------------------------
 
 def find_package_data():
     """
     Find IPython's package_data.
     """
     # This is not enough for these things to appear in an sdist.
     # We need to muck with the MANIFEST to get this to work
     
     # exclude static things that we don't ship (e.g. mathjax)
     excludes = ['mathjax']
     
     # add 'static/' prefix to exclusions, and tuplify for use in startswith
     excludes = tuple([os.path.join('static', ex) for ex in excludes])
     
     # walk notebook resources:
     cwd = os.getcwd()
     os.chdir(os.path.join('IPython', 'html'))
     static_walk = list(os.walk('static'))
     os.chdir(cwd)
     static_data = []
     for parent, dirs, files in static_walk:
         if parent.startswith(excludes):
             continue
         for f in files:
             static_data.append(os.path.join(parent, f))
 
     package_data = {
         'IPython.config.profile' : ['README*', '*/*.py'],
+        'IPython.core.tests' : ['*.png', '*.jpg'],
         'IPython.testing' : ['*.txt'],
         'IPython.testing.plugin' : ['*.txt'],
         'IPython.html' : ['templates/*'] + static_data,
         'IPython.qt.console' : ['resources/icon/*.svg'],
     }
     return package_data
 
 
 #---------------------------------------------------------------------------
 # Find data files
 #---------------------------------------------------------------------------
 
 def make_dir_struct(tag,base,out_base):
     """Make the directory structure of all files below a starting dir.
 
     This is just a convenience routine to help build a nested directory
     hierarchy because distutils is too stupid to do this by itself.
 
     XXX - this needs a proper docstring!
     """
 
     # we'll use these a lot below
     lbase = len(base)
     pathsep = os.path.sep
     lpathsep = len(pathsep)
 
     out = []
     for (dirpath,dirnames,filenames) in os.walk(base):
         # we need to strip out the dirpath from the base to map it to the
         # output (installation) path.  This requires possibly stripping the
         # path separator, because otherwise pjoin will not work correctly
         # (pjoin('foo/','/bar') returns '/bar').
 
         dp_eff = dirpath[lbase:]
         if dp_eff.startswith(pathsep):
             dp_eff = dp_eff[lpathsep:]
         # The output path must be anchored at the out_base marker
         out_path = pjoin(out_base,dp_eff)
         # Now we can generate the final filenames. Since os.walk only produces
         # filenames, we must join back with the dirpath to get full valid file
         # paths:
         pfiles = [pjoin(dirpath,f) for f in filenames]
         # Finally, generate the entry we need, which is a pari of (output
         # path, files) for use as a data_files parameter in install_data.
         out.append((out_path, pfiles))
 
     return out
 
 
 def find_data_files():
     """
     Find IPython's data_files.
 
     Most of these are docs.
     """
 
     docdirbase  = pjoin('share', 'doc', 'ipython')
     manpagebase = pjoin('share', 'man', 'man1')
 
     # Simple file lists can be made by hand
     manpages = [f for f in glob(pjoin('docs','man','*.1.gz')) if isfile(f)]
     if not manpages:
         # When running from a source tree, the manpages aren't gzipped
         manpages = [f for f in glob(pjoin('docs','man','*.1')) if isfile(f)]
 
     igridhelpfiles = [f for f in glob(pjoin('IPython','extensions','igrid_help.*')) if isfile(f)]
 
     # For nested structures, use the utility above
     example_files = make_dir_struct(
         'data',
         pjoin('docs','examples'),
         pjoin(docdirbase,'examples')
     )
     manual_files = make_dir_struct(
         'data',
         pjoin('docs','html'),
         pjoin(docdirbase,'manual')
     )
 
     # And assemble the entire output list
     data_files = [ (manpagebase, manpages),
                    (pjoin(docdirbase, 'extensions'), igridhelpfiles),
                    ] + manual_files + example_files
 
     return data_files
 
 
 def make_man_update_target(manpage):
     """Return a target_update-compliant tuple for the given manpage.
 
     Parameters
     ----------
     manpage : string
       Name of the manpage, must include the section number (trailing number).
 
     Example
     -------
 
     >>> make_man_update_target('ipython.1') #doctest: +NORMALIZE_WHITESPACE
     ('docs/man/ipython.1.gz',
      ['docs/man/ipython.1'],
      'cd docs/man && gzip -9c ipython.1 > ipython.1.gz')
     """
     man_dir = pjoin('docs', 'man')
     manpage_gz = manpage + '.gz'
     manpath = pjoin(man_dir, manpage)
     manpath_gz = pjoin(man_dir, manpage_gz)
     gz_cmd = ( "cd %(man_dir)s && gzip -9c %(manpage)s > %(manpage_gz)s" %
                locals() )
     return (manpath_gz, [manpath], gz_cmd)
 
 # The two functions below are copied from IPython.utils.path, so we don't need
 # to import IPython during setup, which fails on Python 3.
 
 def target_outdated(target,deps):
     """Determine whether a target is out of date.
 
     target_outdated(target,deps) -> 1/0
 
     deps: list of filenames which MUST exist.
     target: single filename which may or may not exist.
 
     If target doesn't exist or is older than any file listed in deps, return
     true, otherwise return false.
     """
     try:
         target_time = os.path.getmtime(target)
     except os.error:
         return 1
     for dep in deps:
         dep_time = os.path.getmtime(dep)
         if dep_time > target_time:
             #print "For target",target,"Dep failed:",dep # dbg
             #print "times (dep,tar):",dep_time,target_time # dbg
             return 1
     return 0
 
 
 def target_update(target,deps,cmd):
     """Update a target with a given command given a list of dependencies.
 
     target_update(target,deps,cmd) -> runs cmd if target is outdated.
 
     This is just a wrapper around target_outdated() which calls the given
     command if target is outdated."""
 
     if target_outdated(target,deps):
         os.system(cmd)
 
 #---------------------------------------------------------------------------
 # Find scripts
 #---------------------------------------------------------------------------
 
 def find_scripts(entry_points=False, suffix=''):
     """Find IPython's scripts.
 
     if entry_points is True:
         return setuptools entry_point-style definitions
     else:
         return file paths of plain scripts [default]
 
     suffix is appended to script names if entry_points is True, so that the
     Python 3 scripts get named "ipython3" etc.
     """
     if entry_points:
         console_scripts = [s % suffix for s in [
             'ipython%s = IPython.terminal.ipapp:launch_new_instance',
             'pycolor%s = IPython.utils.PyColorize:main',
             'ipcontroller%s = IPython.parallel.apps.ipcontrollerapp:launch_new_instance',
             'ipengine%s = IPython.parallel.apps.ipengineapp:launch_new_instance',
             'iplogger%s = IPython.parallel.apps.iploggerapp:launch_new_instance',
             'ipcluster%s = IPython.parallel.apps.ipclusterapp:launch_new_instance',
             'iptest%s = IPython.testing.iptest:main',
             'irunner%s = IPython.lib.irunner:main'
         ]]
         gui_scripts = []
         scripts = dict(console_scripts=console_scripts, gui_scripts=gui_scripts)
     else:
         parallel_scripts = pjoin('IPython','parallel','scripts')
         main_scripts = pjoin('IPython','scripts')
         scripts = [
                    pjoin(parallel_scripts, 'ipengine'),
                    pjoin(parallel_scripts, 'ipcontroller'),
                    pjoin(parallel_scripts, 'ipcluster'),
                    pjoin(parallel_scripts, 'iplogger'),
                    pjoin(main_scripts, 'ipython'),
                    pjoin(main_scripts, 'pycolor'),
                    pjoin(main_scripts, 'irunner'),
                    pjoin(main_scripts, 'iptest')
         ]
     return scripts
 
 #---------------------------------------------------------------------------
 # Verify all dependencies
 #---------------------------------------------------------------------------
 
 def check_for_dependencies():
     """Check for IPython's dependencies.
 
     This function should NOT be called if running under setuptools!
     """
     from setupext.setupext import (
         print_line, print_raw, print_status,
         check_for_sphinx, check_for_pygments,
         check_for_nose, check_for_pexpect,
         check_for_pyzmq, check_for_readline
     )
     print_line()
     print_raw("BUILDING IPYTHON")
     print_status('python', sys.version)
     print_status('platform', sys.platform)
     if sys.platform == 'win32':
         print_status('Windows version', sys.getwindowsversion())
 
     print_raw("")
     print_raw("OPTIONAL DEPENDENCIES")
 
     check_for_sphinx()
     check_for_pygments()
     check_for_nose()
     check_for_pexpect()
     check_for_pyzmq()
     check_for_readline()
 
 #---------------------------------------------------------------------------
 # VCS related
 #---------------------------------------------------------------------------
 
 # utils.submodule has checks for submodule status
 execfile(pjoin('IPython','utils','submodule.py'), globals())
 
 class UpdateSubmodules(Command):
     """Update git submodules
     
     IPython's external javascript dependencies live in a separate repo.
     """
     description = "Update git submodules"
     user_options = []
     
     def initialize_options(self):
         pass
     
     def finalize_options(self):
         pass
     
     def run(self):
         failure = False
         try:
             self.spawn('git submodule init'.split())
             self.spawn('git submodule update --recursive'.split())
         except Exception as e:
             failure = e
             print(e)
         
         if not check_submodule_status(repo_root) == 'clean':
             print("submodules could not be checked out")
             sys.exit(1)
 
 
 def git_prebuild(pkg_dir, build_cmd=build_py):
     """Return extended build or sdist command class for recording commit
     
     records git commit in IPython.utils._sysinfo.commit
     
     for use in IPython.utils.sysinfo.sys_info() calls after installation.
     
     Also ensures that submodules exist prior to running
     """
     
     class MyBuildPy(build_cmd):
         ''' Subclass to write commit data into installation tree '''
         def run(self):
             build_cmd.run(self)
             # this one will only fire for build commands
             if hasattr(self, 'build_lib'):
                 self._record_commit(self.build_lib)
         
         def make_release_tree(self, base_dir, files):
             # this one will fire for sdist
             build_cmd.make_release_tree(self, base_dir, files)
             self._record_commit(base_dir)
         
         def _record_commit(self, base_dir):
             import subprocess
             proc = subprocess.Popen('git rev-parse --short HEAD',
                                     stdout=subprocess.PIPE,
                                     stderr=subprocess.PIPE,
                                     shell=True)
             repo_commit, _ = proc.communicate()
             repo_commit = repo_commit.strip().decode("ascii")
             
             out_pth = pjoin(base_dir, pkg_dir, 'utils', '_sysinfo.py')
             if os.path.isfile(out_pth) and not repo_commit:
                 # nothing to write, don't clobber
                 return
             
             print("writing git commit '%s' to %s" % (repo_commit, out_pth))
             
             # remove to avoid overwriting original via hard link
             try:
                 os.remove(out_pth)
             except (IOError, OSError):
                 pass
             with open(out_pth, 'w') as out_file:
                 out_file.writelines([
                     '# GENERATED BY setup.py\n',
                     'commit = "%s"\n' % repo_commit,
                 ])
     return require_submodules(MyBuildPy)
 
 
 def require_submodules(command):
     """decorator for instructing a command to check for submodules before running"""
     class DecoratedCommand(command):
         def run(self):
             if not check_submodule_status(repo_root) == 'clean':
                 print("submodules missing! Run `setup.py submodule` and try again")
                 sys.exit(1)
             command.run(self)
     return DecoratedCommand