Merge pull request #5110 from minrk/bbox_inches

add InlineBackend.print_figure_kwargs

docs/source/whatsnew/pr/print-figure-kwargs.rst

@@ -0,0 +1,3
+* added ``InlineBackend.print_figure_kwargs`` to allow passing keyword arguments
+  to matplotlib's ``Canvas.print_figure``. This can be used to change the value of
+  ``bbox_inches``, which is 'tight' by default, or set the quality of JPEG figures.

IPython/core/display.py

@@ -1,772 +1,778
 # -*- 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, cast_bytes_py2, cast_unicode,
                                      unicode_type)
 from IPython.testing.skipdoctest import skip_doctest
 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 not raw:
         format = InteractiveShell.instance().display_formatter.format
 
     for obj in objs:
 
         # If _ipython_display_ is defined, use that to display this object.
         display_method = getattr(obj, '_ipython_display_', None)
         if display_method is not None:
             try:
                 display_method(**kwargs)
             except NotImplementedError:
                 pass
             else:
                 continue
         if raw:
             publish_display_data('display', obj, metadata)
         else:
             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)
 
 
 def display_pdf(*objs, **kwargs):
     """Display the PDF 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/pdf', 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_type(filename)
 
         self.reload()
         self._check_data()
     
     def _check_data(self):
         """Override in subclasses if there's something to check."""
         pass
 
     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:
                 try:
                     from urllib.request import urlopen  # Py3
                 except ImportError:
                     from urllib2 import urlopen
                 response = 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 TextDisplayObject(DisplayObject):
     """Validate that display data is text"""
     def _check_data(self):
         if self.data is not None and not isinstance(self.data, string_types):
             raise TypeError("%s expects text, not %r" % (self.__class__.__name__, self.data))
 
 class Pretty(TextDisplayObject):
 
     def _repr_pretty_(self):
         return self.data
 
 
 class HTML(TextDisplayObject):
 
     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(TextDisplayObject):
 
     def _repr_latex_(self):
         s = self.data.strip('$')
         return "$$%s$$" % s
 
 
 class Latex(TextDisplayObject):
 
     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
         svg = cast_bytes_py2(svg)
         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
         svg = cast_unicode(svg)
         self._data = svg
 
     def _repr_svg_(self):
         return self.data
 
 
 class JSON(TextDisplayObject):
 
     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(TextDisplayObject):
 
     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, string_types):
             lib = [lib]
         elif lib is None:
             lib = []
         if isinstance(css, string_types):
             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, retina=False):
         """Create a PNG/JPEG image object given raw data.
 
         When this object is returned by an input cell 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_type(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_type(s.split('.')[-1].lower())
 
 
 def clear_output(wait=False):
     """Clear the output of the current cell receiving output.
 
     Parameters
     ----------
     wait : bool [default: false]
         Wait to clear the output until new output is available to replace it."""
     from IPython.core.interactiveshell import InteractiveShell
     if InteractiveShell.initialized():
         InteractiveShell.instance().display_pub.clear_output(wait)
     else:
         from IPython.utils import io
         print('\033[2K\r', file=io.stdout, end='')
         io.stdout.flush()
         print('\033[2K\r', file=io.stderr, end='')
         io.stderr.flush()
 
 
 @skip_doctest
 def set_matplotlib_formats(*formats, **kwargs):
     """Select figure formats for the inline backend. Optionally pass quality for JPEG.
 
     For example, this enables PNG and JPEG output with a JPEG quality of 90%::
 
         In [1]: set_matplotlib_formats('png', 'jpeg', quality=90)
 
     To set this in your config files use the following::
     
-        c.InlineBackend.figure_formats = {'pdf', 'png', 'svg'}
-        c.InlineBackend.quality = 90
+        c.InlineBackend.figure_formats = {'png', 'jpeg'}
+        c.InlineBackend.print_figure_kwargs.update({'quality' : 90})
 
     Parameters
     ----------
-    *formats : list, tuple
-        One or a set of figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
-    quality : int
-        A percentage for the quality of JPEG figures. Defaults to 90.
+    *formats : strs
+        One or more figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
+    **kwargs :
+        Keyword args will be relayed to ``figure.canvas.print_figure``.
     """
     from IPython.core.interactiveshell import InteractiveShell
     from IPython.core.pylabtools import select_figure_formats
+    from IPython.kernel.zmq.pylab.config import InlineBackend
+    # build kwargs, starting with InlineBackend config
+    kw = {}
+    cfg = InlineBackend.instance()
+    kw.update(cfg.print_figure_kwargs)
+    kw.update(**kwargs)
     shell = InteractiveShell.instance()
-    select_figure_formats(shell, formats, quality=90)
+    select_figure_formats(shell, formats, **kw)
 
 @skip_doctest
-def set_matplotlib_close(close):
+def set_matplotlib_close(close=True):
     """Set whether the inline backend closes all figures automatically or not.
     
     By default, the inline backend used in the IPython Notebook will close all
     matplotlib figures automatically after each cell is run. This means that
     plots in different cells won't interfere. Sometimes, you may want to make
     a plot in one cell and then refine it in later cells. This can be accomplished
     by::
     
         In [1]: set_matplotlib_close(False)
     
     To set this in your config files use the following::
     
         c.InlineBackend.close_figures = False
     
     Parameters
     ----------
     close : bool
         Should all matplotlib figures be automatically closed after each cell is
         run?
     """
-    from IPython.kernel.zmq.pylab.backend_inline import InlineBackend
-    ilbe = InlineBackend.instance()
-    ilbe.close_figures = close
+    from IPython.kernel.zmq.pylab.config import InlineBackend
+    cfg = InlineBackend.instance()
+    cfg.close_figures = close
 

IPython/core/pylabtools.py

@@ -1,358 +1,374
 # -*- coding: utf-8 -*-
 """Pylab (matplotlib) support utilities.
 
 Authors
 -------
 
 * Fernando Perez.
 * Brian Granger
 """
 from __future__ import print_function
 
 #-----------------------------------------------------------------------------
 #  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
 from IPython.utils import py3compat
 
 # 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',
             'gtk3': 'GTK3Agg',
             '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()))
 # Our tests expect backend2gui to just return 'qt'
 backend2gui['Qt4Agg'] = 'qt'
 # 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['GTK3Cairo'] = 'gtk3'
 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', quality=90):
-    """Convert a figure to svg, png or jpg for inline display.
-    Quality is only relevant for jpg.
+def print_figure(fig, fmt='png', bbox_inches='tight', **kwargs):
+    """Print a figure to an image, and return the resulting bytes
+    
+    Any keyword args are passed to fig.canvas.print_figure,
+    such as ``quality`` or ``bbox_inches``.
     """
     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, dpi=dpi, quality=quality)
-    data = bytes_io.getvalue()
-    return data
     
-def retina_figure(fig):
+    # build keyword args
+    kw = dict(
+        format=fmt,
+        fc=fig.get_facecolor(),
+        ec=fig.get_edgecolor(),
+        dpi=dpi,
+        bbox_inches=bbox_inches,
+    )
+    # **kwargs get higher priority
+    kw.update(kwargs)
+    
+    bytes_io = BytesIO()
+    fig.canvas.print_figure(bytes_io, **kw)
+    return bytes_io.getvalue()
+    
+def retina_figure(fig, **kwargs):
     """format a figure as a pixel-doubled (retina) PNG"""
-    pngdata = print_figure(fig, fmt='retina')
+    pngdata = print_figure(fig, fmt='retina', **kwargs)
     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_formats(shell, formats, quality=90):
+def select_figure_formats(shell, formats, **kwargs):
     """Select figure formats for the inline backend.
 
     Parameters
     ==========
     shell : InteractiveShell
         The main IPython instance.
-    formats : list
+    formats : str or set
         One or a set of figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
-    quality : int
-        A percentage for the quality of JPEG figures.
+    **kwargs : any
+        Extra keyword arguments to be passed to fig.canvas.print_figure.
     """
     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']
     jpg_formatter = shell.display_formatter.formatters['image/jpeg']
     pdf_formatter = shell.display_formatter.formatters['application/pdf']
 
     if isinstance(formats, py3compat.string_types):
         formats = {formats}
-
-    [ f.type_printers.pop(Figure, None) for f in {svg_formatter, png_formatter, jpg_formatter} ]
-
-    for fmt in formats:
-        if fmt == 'png':
-            png_formatter.for_type(Figure, lambda fig: print_figure(fig, 'png'))
-        elif fmt in ('png2x', 'retina'):
-            png_formatter.for_type(Figure, retina_figure)
-        elif fmt in ('jpg', 'jpeg'):
-            jpg_formatter.for_type(Figure, lambda fig: print_figure(fig, 'jpg', quality))
-        elif fmt == 'svg':
-            svg_formatter.for_type(Figure, lambda fig: print_figure(fig, 'svg'))
-        elif fmt == 'pdf':
-            pdf_formatter.for_type(Figure, lambda fig: print_figure(fig, 'pdf'))
-        else:
-            raise ValueError("supported formats are: 'png', 'retina', 'svg', 'jpg', 'pdf' not %r" % fmt)
+    # cast in case of list / tuple
+    formats = set(formats)
+
+    [ f.pop(Figure, None) for f in shell.display_formatter.formatters.values() ]
+    
+    supported = {'png', 'png2x', 'retina', 'jpg', 'jpeg', 'svg', 'pdf'}
+    bad = formats.difference(supported)
+    if bad:
+        bs = "%s" % ','.join([repr(f) for f in bad])
+        gs = "%s" % ','.join([repr(f) for f in supported])
+        raise ValueError("supported formats are: %s not %s" % (gs, bs))
+    
+    if 'png' in formats:
+        png_formatter.for_type(Figure, lambda fig: print_figure(fig, 'png', **kwargs))
+    if 'retina' in formats or 'png2x' in formats:
+        png_formatter.for_type(Figure, lambda fig: retina_figure(fig, **kwargs))
+    if 'jpg' in formats or 'jpeg' in formats:
+        jpg_formatter.for_type(Figure, lambda fig: print_figure(fig, 'jpg', **kwargs))
+    if 'svg' in formats:
+        svg_formatter.for_type(Figure, lambda fig: print_figure(fig, 'svg', **kwargs))
+    if 'pdf' in formats:
+        pdf_formatter.for_type(Figure, lambda fig: print_figure(fig, 'pdf', **kwargs))
 
 #-----------------------------------------------------------------------------
 # 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:
         # We need to read the backend from the original data structure, *not*
         # from mpl.rcParams, since a prior invocation of %matplotlib may have
         # overwritten that.
         # WARNING: this assumes matplotlib 1.1 or newer!!
         backend = matplotlib.rcParamsOrig['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):
     """Populate the namespace with pylab-related values.
     
     Imports matplotlib, pylab, numpy, and everything from pylab and numpy.
     
     Also imports a few names from IPython (figsize, display, getfigs)
     
     """
 
     # 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, user_ns)
     
     if import_all:
         s = ("from matplotlib.pylab import *\n"
              "from numpy import *\n")
         exec(s, user_ns)
     
     # IPython symbols to add
     user_ns['figsize'] = figsize
     from IPython.core.display import display
     # Add display and getfigs to the user's namespace
     user_ns['display'] = display
     user_ns['getfigs'] = getfigs
 
 
 def configure_inline_support(shell, backend):
     """Configure an IPython shell object for matplotlib use.
 
     Parameters
     ----------
     shell : InteractiveShell instance
 
     backend : matplotlib backend
     """
     # 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
 
     cfg = InlineBackend.instance(parent=shell)
     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)
     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
-    select_figure_formats(shell, cfg.figure_formats, cfg.quality)
+    select_figure_formats(shell, cfg.figure_formats, **cfg.print_figure_kwargs)
 

IPython/core/tests/test_display.py

@@ -1,60 +1,118
 #-----------------------------------------------------------------------------
 #  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.core.getipython import get_ipython
 from IPython.utils import path as ipath
 
+import IPython.testing.decorators as dec
+
 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)
     from IPython.html import DEFAULT_STATIC_FILES_PATH
     # check boths paths to allow packages to test at build and install time
     imgfile = os.path.join(tpath, 'html/static/base/images/ipynblogo.png')
     if not os.path.exists(imgfile):
         imgfile = os.path.join(DEFAULT_STATIC_FILES_PATH, '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_())
+
+def _get_inline_config():
+    from IPython.kernel.zmq.pylab.config import InlineBackend
+    return InlineBackend.instance()
+    
[e-mail]_without('matplotlib')
+def test_set_matplotlib_close():
+    cfg = _get_inline_config()
+    cfg.close_figures = False
+    display.set_matplotlib_close()
+    assert cfg.close_figures
+    display.set_matplotlib_close(False)
+    assert not cfg.close_figures
+
+_fmt_mime_map = {
+    'png': 'image/png',
+    'jpeg': 'image/jpeg',
+    'pdf': 'application/pdf',
+    'retina': 'image/png',
+    'svg': 'image/svg+xml',
+}
+
[e-mail]_without('matplotlib')
+def test_set_matplotlib_formats():
+    from matplotlib.figure import Figure
+    formatters = get_ipython().display_formatter.formatters
+    for formats in [
+        ('png',),
+        ('pdf', 'svg'),
+        ('jpeg', 'retina', 'png'),
+        (),
+    ]:
+        active_mimes = {_fmt_mime_map[fmt] for fmt in formats}
+        display.set_matplotlib_formats(*formats)
+        for mime, f in formatters.items():
+            if mime in active_mimes:
+                nt.assert_in(Figure, f)
+            else:
+                nt.assert_not_in(Figure, f)
+
[e-mail]_without('matplotlib')
+def test_set_matplotlib_formats_kwargs():
+    from matplotlib.figure import Figure
+    ip = get_ipython()
+    cfg = _get_inline_config()
+    cfg.print_figure_kwargs.update(dict(foo='bar'))
+    kwargs = dict(quality=10)
+    display.set_matplotlib_formats('png', **kwargs)
+    formatter = ip.display_formatter.formatters['image/png']
+    f = formatter.lookup_by_type(Figure)
+    cell = f.__closure__[0].cell_contents
+    expected = kwargs
+    expected.update(cfg.print_figure_kwargs)
+    nt.assert_equal(cell, expected)
+

IPython/core/tests/test_pylabtools.py

@@ -1,153 +1,224
 """Tests for pylab tools module.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2011, the 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 __future__ import print_function
 
-# Stdlib imports
+import matplotlib
+matplotlib.use('Agg')
+from matplotlib.figure import Figure
 
-# Third-party imports
-import matplotlib; matplotlib.use('Agg')
 import nose.tools as nt
 
 from matplotlib import pyplot as plt
 import numpy as np
 
 # Our own imports
+from IPython.core.getipython import get_ipython
 from IPython.core.interactiveshell import InteractiveShell
+from IPython.core.display import _PNG, _JPEG
 from .. import pylabtools as pt
 
 from IPython.testing import decorators as dec
 
 #-----------------------------------------------------------------------------
 # Globals and constants
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Local utilities
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 def test_figure_to_svg():
     # simple empty-figure test
     fig = plt.figure()
     nt.assert_equal(pt.print_figure(fig, 'svg'), None)
 
     plt.close('all')
 
     # simple check for at least svg-looking output
     fig = plt.figure()
     ax = fig.add_subplot(1,1,1)
     ax.plot([1,2,3])
     plt.draw()
     svg = pt.print_figure(fig, 'svg')[:100].lower()
     nt.assert_in(b'doctype svg', svg)
 
 @dec.skip_without("PIL.Image")
 def test_figure_to_jpg():
     # simple check for at least jpg-looking output
     fig = plt.figure()
     ax = fig.add_subplot(1,1,1)
     ax.plot([1,2,3])
     plt.draw()
-    jpg = pt.print_figure(fig, 'jpg')[:100].lower()
-    assert jpg.startswith(b'\xff\xd8')
+    jpg = pt.print_figure(fig, 'jpg', quality=50)[:100].lower()
+    assert jpg.startswith(_JPEG)
 
+def test_retina_figure():
+    fig = plt.figure()
+    ax = fig.add_subplot(1,1,1)
+    ax.plot([1,2,3])
+    plt.draw()
+    png, md = pt.retina_figure(fig)
+    assert png.startswith(_PNG)
+    nt.assert_in('width', md)
+    nt.assert_in('height', md)
+
+_fmt_mime_map = {
+    'png': 'image/png',
+    'jpeg': 'image/jpeg',
+    'pdf': 'application/pdf',
+    'retina': 'image/png',
+    'svg': 'image/svg+xml',
+}
+
+def test_select_figure_formats_str():
+    ip = get_ipython()
+    for fmt, active_mime in _fmt_mime_map.items():
+        pt.select_figure_formats(ip, fmt)
+        for mime, f in ip.display_formatter.formatters.items():
+            if mime == active_mime:
+                nt.assert_in(Figure, f)
+            else:
+                nt.assert_not_in(Figure, f)
+
+def test_select_figure_formats_kwargs():
+    ip = get_ipython()
+    kwargs = dict(quality=10, bbox_inches='tight')
+    pt.select_figure_formats(ip, 'png', **kwargs)
+    formatter = ip.display_formatter.formatters['image/png']
+    f = formatter.lookup_by_type(Figure)
+    cell = f.__closure__[0].cell_contents
+    nt.assert_equal(cell, kwargs)
+    
+    # check that the formatter doesn't raise
+    fig = plt.figure()
+    ax = fig.add_subplot(1,1,1)
+    ax.plot([1,2,3])
+    plt.draw()
+    formatter.enabled = True
+    png = formatter(fig)
+    assert png.startswith(_PNG)
 
-def test_import_pylab():
+def test_select_figure_formats_set():
     ip = get_ipython()
+    for fmts in [
+        {'png', 'svg'},
+        ['png'],
+        ('jpeg', 'pdf', 'retina'),
+        {'svg'},
+    ]:
+        active_mimes = {_fmt_mime_map[fmt] for fmt in fmts}
+        pt.select_figure_formats(ip, fmts)
+        for mime, f in ip.display_formatter.formatters.items():
+            if mime in active_mimes:
+                nt.assert_in(Figure, f)
+            else:
+                nt.assert_not_in(Figure, f)
+
+def test_select_figure_formats_bad():
+    ip = get_ipython()
+    with nt.assert_raises(ValueError):
+        pt.select_figure_formats(ip, 'foo')
+    with nt.assert_raises(ValueError):
+        pt.select_figure_formats(ip, {'png', 'foo'})
+    with nt.assert_raises(ValueError):
+        pt.select_figure_formats(ip, ['retina', 'pdf', 'bar', 'bad'])
+
+def test_import_pylab():
     ns = {}
     pt.import_pylab(ns, import_all=False)
     nt.assert_true('plt' in ns)
     nt.assert_equal(ns['np'], np)
 
 class TestPylabSwitch(object):
     class Shell(InteractiveShell):
         def enable_gui(self, gui):
             pass
     
     def setup(self):
         import matplotlib
         def act_mpl(backend):
             matplotlib.rcParams['backend'] = backend
 
         # Save rcParams since they get modified
         self._saved_rcParams = matplotlib.rcParams
         self._saved_rcParamsOrig = matplotlib.rcParamsOrig
         matplotlib.rcParams = dict(backend='Qt4Agg')
         matplotlib.rcParamsOrig = dict(backend='Qt4Agg')
 
         # Mock out functions
         self._save_am = pt.activate_matplotlib
         pt.activate_matplotlib = act_mpl
         self._save_ip = pt.import_pylab
         pt.import_pylab = lambda *a,**kw:None
         self._save_cis = pt.configure_inline_support
         pt.configure_inline_support = lambda *a,**kw:None
 
     def teardown(self):
         pt.activate_matplotlib = self._save_am
         pt.import_pylab = self._save_ip
         pt.configure_inline_support = self._save_cis
         import matplotlib
         matplotlib.rcParams = self._saved_rcParams
         matplotlib.rcParamsOrig = self._saved_rcParamsOrig
 
     def test_qt(self):
         s = self.Shell()
         gui, backend = s.enable_matplotlib(None)
         nt.assert_equal(gui, 'qt')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 
         gui, backend = s.enable_matplotlib('inline')
         nt.assert_equal(gui, 'inline')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 
         gui, backend = s.enable_matplotlib('qt')
         nt.assert_equal(gui, 'qt')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 
         gui, backend = s.enable_matplotlib('inline')
         nt.assert_equal(gui, 'inline')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 
         gui, backend = s.enable_matplotlib()
         nt.assert_equal(gui, 'qt')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 
     def test_inline(self):
         s = self.Shell()
         gui, backend = s.enable_matplotlib('inline')
         nt.assert_equal(gui, 'inline')
         nt.assert_equal(s.pylab_gui_select, None)
 
         gui, backend = s.enable_matplotlib('inline')
         nt.assert_equal(gui, 'inline')
         nt.assert_equal(s.pylab_gui_select, None)
 
         gui, backend = s.enable_matplotlib('qt')
         nt.assert_equal(gui, 'qt')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 
     def test_qt_gtk(self):
         s = self.Shell()
         gui, backend = s.enable_matplotlib('qt')
         nt.assert_equal(gui, 'qt')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 
         gui, backend = s.enable_matplotlib('gtk')
         nt.assert_equal(gui, 'qt')
         nt.assert_equal(s.pylab_gui_select, 'qt')
 

IPython/kernel/zmq/pylab/config.py

@@ -1,115 +1,117
 """Configurable for configuring the IPython inline backend
 
 This module does not import anything from matplotlib.
 """
 #-----------------------------------------------------------------------------
 #       Copyright (C) 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.config.configurable import SingletonConfigurable
 from IPython.utils.traitlets import (
     Dict, Instance, CaselessStrEnum, Set, Bool, Int, TraitError, Unicode
 )
 from IPython.utils.warn import warn
 
 #-----------------------------------------------------------------------------
 # Configurable for inline backend options
 #-----------------------------------------------------------------------------
 
 def pil_available():
     """Test if PIL/Pillow is available"""
     out = False
     try:
         from PIL import Image
         out = True
     except:
         pass
     return out
 
 # 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': (1,1,1,0),
         'figure.edgecolor': (1,1,1,0),
         # 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_formats = Set({'png'}, config=True,
                           help="""A set of figure formats to enable: 'png', 
                           'retina', 'jpeg', 'svg', 'pdf'.""")
 
+    def _update_figure_formatters(self):
+        if self.shell is not None:
+            select_figure_formats(self.shell, self.figure_formats, **self.print_figure_kwargs)
+    
     def _figure_formats_changed(self, name, old, new):
         from IPython.core.pylabtools import select_figure_formats
         if 'jpg' in new or 'jpeg' in new:
             if not pil_available():
                 raise TraitError("Requires PIL/Pillow for JPG figures")
-        if self.shell is None:
-            return
-        else:
-            select_figure_formats(self.shell, new)
+        self._update_figure_formatters()
 
     figure_format = Unicode(config=True, help="""The figure format to enable (deprecated
                                          use `figure_formats` instead)""")
 
     def _figure_format_changed(self, name, old, new):
         if new:
             self.figure_formats = {new}
 
-    quality = Int(default_value=90, config=True,
-                  help="Quality of compression [10-100], currently for lossy JPEG only.")
+    print_figure_kwargs = Dict({'bbox_inches' : 'tight'}, config=True,
+        help="""Extra kwargs to be passed to fig.canvas.print_figure.
 
-    def _quality_changed(self, name, old, new):
-        if new < 10 or new > 100:
-            raise TraitError("figure JPEG quality must be in [10-100] range.")
+        Logical examples include: bbox_inches, quality (for jpeg figures), etc.
+        """
+    )
+    _print_figure_kwargs_changed = _update_figure_formatters
     
     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')
 
 

docs/source/whatsnew/development.rst

@@ -1,285 +1,283
 =====================
  Development version
 =====================
 
 This document describes in-flight development work.
 
 .. warning::
 
     Please do not edit this file by hand (doing so will likely cause merge
     conflicts for other Pull Requests). Instead, create a new file in the
     `docs/source/whatsnew/pr` folder
 
 Select Notebook Name When Renaming a Notebook
 ---------------------------------------------
 
 The default notebook name is Untitled. It's unlikely you want to keep this name
 or part of it when naming your notebook. Instead, IPython will select the text
 in the input field so the user can easily type over the name and change it.
 
 clear_output changes
 --------------------
 
 * There is no longer a 500ms delay when calling ``clear_output``.
 * The ability to clear stderr and stdout individually was removed.
 * A new ``wait`` flag that prevents ``clear_output`` from being executed until new
   output is available.  This eliminates animation flickering by allowing the
   user to double buffer the output.
 * The output div height is remembered when the ``wait=True`` flag is used.
 
 Extending Configurable Containers
 ---------------------------------
 
 Some configurable traits are containers (list, dict, set)
 Config objects now support calling ``extend``, ``update``, ``insert``, etc.
 on traits in config files, which will ultimately result in calling
 those methods on the original object.
 
 The effect being that you can now add to containers without having to copy/paste
 the initial value::
 
     c = get_config()
     c.InlineBackend.rc.update({ 'figure.figsize' : (6, 4) })
 
 Single codebase Python 3 support
 --------------------------------
 
 IPython previously supported Python 3 by running 2to3 during setup. We
 have now switched to a single codebase which runs natively on Python 2.7
 and 3.3.
 
 For notes on how to maintain this, see :doc:`/development/pycompat`.
 
 changes to hidden namespace on startup
 --------------------------------------
 
 Previously, all names declared in code run at startup
 (startup files, ``ipython -i script.py``, etc.)
 were added to the hidden namespace, which hides the names from tools like ``%whos``.
 There are two changes to this behavior:
 
 1. Scripts run on the command-line ``ipython -i script.py``now behave the same as if they were
    passed to ``%run``, so their variables are never hidden.
 2. A boolean config flag ``InteractiveShellApp.hide_initial_ns`` has been added to optionally
    disable the hidden behavior altogether. The default behavior is unchanged.
 
 Using dill to expand serialization support
 ------------------------------------------
 
 adds :func:`~IPython.utils.pickleutil.use_dill` for allowing
 dill to extend serialization support in :mod:`IPython.parallel` (closures, etc.).
 Also adds :meth:`DirectView.use_dill` convenience method for enabling dill
 locally and on all engines with one call.
 
 New IPython Console Lexer
 -------------------------
 
 The IPython console lexer has been rewritten and now supports tracebacks
 and customized input/output prompts. An entire suite of lexers is now
 available at :mod:`IPython.nbconvert.utils.lexers`. These include:
 
 IPythonLexer & IPython3Lexer
   Lexers for pure IPython (python + magic/shell commands)
 
 IPythonPartialTracebackLexer & IPythonTracebackLexer
   Supports 2.x and 3.x via the keyword `python3`. The partial traceback
   lexer reads everything but the Python code appearing in a traceback.
   The full lexer combines the partial lexer with an IPython lexer.
 
 IPythonConsoleLexer
   A lexer for IPython console sessions, with support for tracebacks.
   Supports 2.x and 3.x via the keyword `python3`.
 
 IPyLexer
   A friendly lexer which examines the first line of text and from it,
   decides whether to use an IPython lexer or an IPython console lexer.
   Supports 2.x and 3.x via the keyword `python3`.
 
 Previously, the :class:`IPythonConsoleLexer` class was available at
 :mod:`IPython.sphinxext.ipython_console_hightlight`.  It was inserted
 into Pygments' list of available lexers under the name `ipython`.  It should
 be mentioned that this name is inaccurate, since an IPython console session
 is not the same as IPython code (which itself is a superset of the Python
 language).
 
 Now, the Sphinx extension inserts two console lexers into Pygments' list of
 available lexers. Both are IPyLexer instances under the names: `ipython` and
 `ipython3`. Although the names can be confusing (as mentioned above), their
 continued use is, in part, to maintain backwards compatibility and to
 aid typical usage. If a project needs to make Pygments aware of more than just
 the IPyLexer class, then one should not make the IPyLexer class available under
 the name `ipython` and use `ipy` or some other non-conflicting value.
 
 Code blocks such as:
 
 .. code-block:: rst
 
     .. code-block:: ipython
 
         In [1]: 2**2
     Out[1]: 4
 
     will continue to work as before, but now, they will also properly highlight
 tracebacks.  For pure IPython code, the same lexer will also work:
 
 .. code-block:: rst
 
     .. code-block:: ipython
 
         x = ''.join(map(str, range(10)))
     !echo $x
 
     Since the first line of the block did not begin with a standard IPython console
 prompt, the entire block is assumed to consist of IPython code instead.
 
 DisplayFormatter changes
 ------------------------
 
 There was no official way to query or remove callbacks in the Formatter API.
 To remedy this, the following methods are added to :class:`BaseFormatter`:
 
 - ``lookup(instance)`` - return appropriate callback or a given object
 - ``lookup_by_type(type_or_str)`` - return appropriate callback for a given type or ``'mod.name'`` type string
 - ``pop(type_or_str)`` - remove a type (by type or string).
   Pass a second argument to avoid KeyError (like dict).
 
 All of the above methods raise a KeyError if no match is found.
 
 And the following methods are changed:
 
 - ``for_type(type_or_str)`` - behaves the same as before, only adding support for ``'mod.name'``
   type strings in addition to plain types. This removes the need for ``for_type_by_name()``,
   but it remains for backward compatibility.
 
 Notebook Widgets
 ----------------
 
 Available in the new `IPython.html.widgets` namespace, widgets provide an easy
 way for IPython notebook users to display GUI controls in the IPython notebook.
 IPython comes with bundle of built-in widgets and also the ability for users
 to define their own widgets.  A widget is displayed in the front-end using
 using a view.  For example, a FloatRangeWidget can be displayed using a
 FloatSliderView (which is the default if no view is specified when displaying
 the widget).  IPython also comes with a bundle of views and the ability for the
 user to define custom views.  One widget can be displayed multiple times, in on
 or more cells, using one or more views.  All views will automatically remain in
 sync with the widget which is accessible in the back-end.
 
 The widget layer provides an MVC-like architecture on top of the comm layer.
 It's useful for widgets that can be expressed via a list of properties.
 Widgets work by synchronizing IPython traitlet models in the back-end with
 backbone models in the front-end. The widget layer automatically handles
 
 * delta compression (only sending the state information that has changed)
 * wiring the message callbacks to the correct cells automatically
 * inter-view synchronization (handled by backbone)
 * message throttling (to avoid flooding the kernel)
 * parent/child relationships between views (which one can override to specify custom parent/child relationships)
 * ability to manipulate the widget view's DOM from python using CSS, $().addClass, and $().removeClass methods
 
 Signing Notebooks
 -----------------
 
 To prevent untrusted code from executing on users' behalf when notebooks open,
 we have added a signature to the notebook, stored in metadata.
 
 For more information, see :ref:`signing_notebooks`.
 
 Other changes
 -------------
 
 * `%%capture` cell magic now captures the rich display output, not just
   stdout/stderr
 
 * In notebook, Showing tooltip on tab has been disables to avoid conflict with
   completion, Shift-Tab could still be used to invoke tooltip when inside
   function signature and/or on selection.
 
 * ``object_info_request`` as been replaced by ``object_info`` for consistency in the javascript API.
   ``object_info`` as a simpler interface to register callback that is incompatible with ``object_info_request``.
 
 * Previous versions of IPython on Linux would use the XDG config directory,
   creating :file:`~/.config/ipython` by default. We have decided to go
   back to :file:`~/.ipython` for consistency among systems. IPython will
   issue a warning if it finds the XDG location, and will move it to the new
   location if there isn't already a directory there.
 
 * Equations, images and tables are now centered in Markdown cells.
 * Multiline equations are now centered in output areas; single line equations
   remain left justified.
 
 * IPython config objects can be loaded from and serialized to JSON.
   JSON config file have the same base name as their ``.py`` counterpart,
   and will be loaded with higher priority if found.
 
 * bash completion updated with support for all ipython subcommands and flags, including nbconvert
 
 * ``ipython history trim``: added ``--keep=<N>`` as an alias for the more verbose
   ``--HistoryTrim.keep=<N>``
 * new ``ipython history clear`` subcommand, which is the same as the newly supported
   ``ipython history trim --keep=0``
 
 * You can now run notebooks in an interactive session via ``%run notebook.ipynb``.
 
 * Print preview is back in the notebook menus, along with options to
   download the open notebook in various formats. This is powered by
   nbconvert.
 
 * :exc:`~IPython.nbconvert.utils.pandoc.PandocMissing` exceptions will be
   raised if Pandoc is unavailable, and warnings will be printed if the version
   found is too old. The recommended Pandoc version for use with nbconvert is
   1.12.1.
 
 * The InlineBackend.figure_format flag now supports JPEG output if PIL/Pillow is available.
-* The new ``InlineBackend.quality`` flag is a Integer in the range [10, 100] which controls
-  the quality of figures where higher values give nicer images (currently JPEG only).
 
 * Input transformers (see :doc:`/config/inputtransforms`) may now raise
   :exc:`SyntaxError` if they determine that input is invalid. The input
   transformation machinery in IPython will handle displaying the exception to
   the user and resetting state.
 
 .. DO NOT EDIT THIS LINE BEFORE RELEASE. FEATURE INSERTION POINT.
 
 Backwards incompatible changes
 ------------------------------
 
 * Python 2.6 and 3.2 are no longer supported: the minimum required
   Python versions are now 2.7 and 3.3.
 * The Transformer classes have been renamed to Preprocessor in nbconvert and
   their `call` methods for them have been renamed to `preprocess`.
 * The `call` methods of nbconvert post-processsors have been renamed to
   `postprocess`.
 
 * The module ``IPython.core.fakemodule`` has been removed.
 
 * The alias system has been reimplemented to use magic functions. There should be little
   visible difference while automagics are enabled, as they are by default, but parts of the
   :class:`~IPython.core.alias.AliasManager` API have been removed.
 
 * We fixed an issue with switching between matplotlib inline and GUI backends,
   but the fix requires matplotlib 1.1 or newer.  So from now on, we consider
   matplotlib 1.1 to be the minimally supported version for IPython. Older
   versions for the most part will work, but we make no guarantees about it.
 
 * The :command:`pycolor` command has been removed. We recommend the much more capable
   :command:`pygmentize` command from the `Pygments <http://pygments.org/>`_ project.
   If you need to keep the exact output of :command:`pycolor`, you can still use
   ``python -m IPython.utils.PyColorize foo.py``.
 
 * :mod:`IPython.lib.irunner` and its command-line entry point have been removed.
   It had fallen out of use long ago.
 
 * The ``input_prefilter`` hook has been removed, as it was never
   actually used by the code. The input transformer system offers much
   more powerful APIs to work with input code. See
   :doc:`/config/inputtransforms` for details.
 
 * :class:`IPython.core.inputsplitter.IPythonInputSplitter` no longer has a method
   ``source_raw_reset()``, but gains :meth:`~IPython.core.inputsplitter.IPythonInputSplitter.raw_reset`
   instead. Use of ``source_raw_reset`` can be replaced with::
 
       raw = isp.source_raw
       transformed = isp.source_reset()
 
 .. DO NOT EDIT THIS LINE BEFORE RELEASE. INCOMPAT INSERTION POINT.