Merge pull request matplotlib#907 from mspacek/default_filetype

replace cairo.format with savefig.format in rcParams

Author: mdboom

CHANGELOG

@@ -2,6 +2,10 @@
 
 2012-06-02 Add new Axes method and pyplot function, hist2d. - PO
 
+2012-05-31 Remove support for 'cairo.<format>' style of backend specification.
+           Deprecate 'cairo.format' and 'savefig.extension' rcParams and
+           replace with 'savefig.format'. - Martin Spacek
+
 2012-05-29 pcolormesh now obeys the passed in "edgecolor" kwarg.
            To support this, the "shading" argument to pcolormesh now only
            takes "flat" or "gouraud".  To achieve the old "faceted" behavior,

doc/api/api_changes.rst

@@ -14,6 +14,10 @@ For new features that were added to matplotlib, please see
 Changes in 1.2.x
 ================
 
+* The new rc parameter ``savefig.format`` replaces ``cairo.format`` and
+  ``savefig.extension``, and sets the default file format used by
+  :meth:`matplotlib.figure.Figure.savefig`.
+
 * In :meth:`~matplotlib.pyplot.pie` and :meth:`~matplotlib.Axes.pie`, one can
   now set the radius of the pie; setting the *radius* to 'None' (the default
   value), will result in a pie with a radius of 1 as before.
@@ -237,7 +241,7 @@ Changes for 0.98.x
         labelsep           labelspacing
         handlelen          handlelength
         handlestextsep     handletextpad
-        axespad	           borderaxespad
+        axespad            borderaxespad
         ================   ================
 
 
@@ -405,51 +409,51 @@ Old method                                                   New method
 ------------------------------------------------------------ ------------------------------------------------------------
 :meth:`Bbox.height`                                          :attr:`transforms.Bbox.height`
 ------------------------------------------------------------ ------------------------------------------------------------
-`Bbox.intervalx().get_bounds()`	                             :attr:`transforms.Bbox.intervalx`
+`Bbox.intervalx().get_bounds()`                              :attr:`transforms.Bbox.intervalx`
 `Bbox.intervalx().set_bounds()`                              [:attr:`Bbox.intervalx` is now a property.]
 ------------------------------------------------------------ ------------------------------------------------------------
-`Bbox.intervaly().get_bounds()` 	                     :attr:`transforms.Bbox.intervaly`
+`Bbox.intervaly().get_bounds()`                              :attr:`transforms.Bbox.intervaly`
 `Bbox.intervaly().set_bounds()`                              [:attr:`Bbox.intervaly` is now a property.]
 ------------------------------------------------------------ ------------------------------------------------------------
-:meth:`Bbox.xmin`		                             :attr:`transforms.Bbox.x0` or
+:meth:`Bbox.xmin`                                            :attr:`transforms.Bbox.x0` or
                                                              :attr:`transforms.Bbox.xmin` [1]_
 ------------------------------------------------------------ ------------------------------------------------------------
-:meth:`Bbox.ymin`		                             :attr:`transforms.Bbox.y0` or
+:meth:`Bbox.ymin`                                            :attr:`transforms.Bbox.y0` or
                                                              :attr:`transforms.Bbox.ymin` [1]_
 ------------------------------------------------------------ ------------------------------------------------------------
-:meth:`Bbox.xmax`		                             :attr:`transforms.Bbox.x1` or
+:meth:`Bbox.xmax`                                            :attr:`transforms.Bbox.x1` or
                                                              :attr:`transforms.Bbox.xmax` [1]_
 ------------------------------------------------------------ ------------------------------------------------------------
-:meth:`Bbox.ymax`		                             :attr:`transforms.Bbox.y1` or
+:meth:`Bbox.ymax`                                            :attr:`transforms.Bbox.y1` or
                                                              :attr:`transforms.Bbox.ymax` [1]_
 ------------------------------------------------------------ ------------------------------------------------------------
-`Bbox.overlaps(bboxes)`		                             `Bbox.count_overlaps(bboxes)`
+`Bbox.overlaps(bboxes)`                                      `Bbox.count_overlaps(bboxes)`
 ------------------------------------------------------------ ------------------------------------------------------------
-`bbox_all(bboxes)`	                                     `Bbox.union(bboxes)`
+`bbox_all(bboxes)`                                           `Bbox.union(bboxes)`
                                                              [:meth:`transforms.Bbox.union` is a staticmethod.]
 ------------------------------------------------------------ ------------------------------------------------------------
-`lbwh_to_bbox(l, b, w, h)`		                     `Bbox.from_bounds(x0, y0, w, h)`
+`lbwh_to_bbox(l, b, w, h)`                                   `Bbox.from_bounds(x0, y0, w, h)`
                                                              [:meth:`transforms.Bbox.from_bounds` is a staticmethod.]
 ------------------------------------------------------------ ------------------------------------------------------------
 `inverse_transform_bbox(trans, bbox)`                        `Bbox.inverse_transformed(trans)`
 ------------------------------------------------------------ ------------------------------------------------------------
-`Interval.contains_open(v)`		                     `interval_contains_open(tuple, v)`
+`Interval.contains_open(v)`                                  `interval_contains_open(tuple, v)`
 ------------------------------------------------------------ ------------------------------------------------------------
-`Interval.contains(v)`		                             `interval_contains(tuple, v)`
+`Interval.contains(v)`                                       `interval_contains(tuple, v)`
 ------------------------------------------------------------ ------------------------------------------------------------
-`identity_transform()`		                             :class:`matplotlib.transforms.IdentityTransform`
+`identity_transform()`                                       :class:`matplotlib.transforms.IdentityTransform`
 ------------------------------------------------------------ ------------------------------------------------------------
 `blend_xy_sep_transform(xtrans, ytrans)`                     `blended_transform_factory(xtrans, ytrans)`
 ------------------------------------------------------------ ------------------------------------------------------------
-`scale_transform(xs, ys)`			             `Affine2D().scale(xs[, ys])`
+`scale_transform(xs, ys)`                                    `Affine2D().scale(xs[, ys])`
 ------------------------------------------------------------ ------------------------------------------------------------
-`get_bbox_transform(boxin, boxout)` 	                     `BboxTransform(boxin, boxout)` or
-      				 		             `BboxTransformFrom(boxin)` or
-						             `BboxTransformTo(boxout)`
+`get_bbox_transform(boxin, boxout)`                          `BboxTransform(boxin, boxout)` or
+                                                             `BboxTransformFrom(boxin)` or
+                                                             `BboxTransformTo(boxout)`
 ------------------------------------------------------------ ------------------------------------------------------------
-`Transform.seq_xy_tup(points)`        		             `Transform.transform(points)`
+`Transform.seq_xy_tup(points)`                               `Transform.transform(points)`
 ------------------------------------------------------------ ------------------------------------------------------------
-`Transform.inverse_xy_tup(points)`		             `Transform.inverted().transform(points)`
+`Transform.inverse_xy_tup(points)`                           `Transform.inverted().transform(points)`
 ============================================================ ============================================================
 
 .. [1] The :class:`~matplotlib.transforms.Bbox` is bound by the points
@@ -492,7 +496,7 @@ The :class:`Polar` class has moved to :mod:`matplotlib.projections.polar`.
 ============================================================ ============================================================
 Old method                                                   New method
 ============================================================ ============================================================
-`Artist.set_clip_path(path)`		                     `Artist.set_clip_path(path, transform)` [5]_
+`Artist.set_clip_path(path)`                                 `Artist.set_clip_path(path, transform)` [5]_
 ============================================================ ============================================================
 
 .. [5] :meth:`matplotlib.artist.Artist.set_clip_path` now accepts a
@@ -519,7 +523,7 @@ Old method                                                   New method
 ============================================================ ============================================================
 Old method                                                   New method
 ============================================================ ============================================================
-`ColorConvertor.to_rgba_list(c)`		             `ColorConvertor.to_rgba_array(c)`
+`ColorConvertor.to_rgba_list(c)`                             `ColorConvertor.to_rgba_array(c)`
                                                              [:meth:`matplotlib.colors.ColorConvertor.to_rgba_array`
                                                              returns an Nx4 Numpy array of RGBA color quadruples.]
 ============================================================ ============================================================
@@ -530,7 +534,7 @@ Old method                                                   New method
 ============================================================ ============================================================
 Old method                                                   New method
 ============================================================ ============================================================
-`Contour._segments`				             :meth:`matplotlib.contour.Contour.get_paths`` [Returns a
+`Contour._segments`                                          :meth:`matplotlib.contour.Contour.get_paths`` [Returns a
                                                              list of :class:`matplotlib.path.Path` instances.]
 ============================================================ ============================================================
 
@@ -540,7 +544,7 @@ Old method                                                   New method
 ============================================================ ============================================================
 Old method                                                   New method
 ============================================================ ============================================================
-`Figure.dpi.get()` / `Figure.dpi.set()`	                     :attr:`matplotlib.figure.Figure.dpi` *(a property)*
+`Figure.dpi.get()` / `Figure.dpi.set()`                      :attr:`matplotlib.figure.Figure.dpi` *(a property)*
 ============================================================ ============================================================
 
 :mod:`matplotlib.patches`

doc/pyplots/matplotlibrc

@@ -59,10 +59,10 @@ backend      : Agg
 # circles.  See
 # http://matplotlib.sourceforge.net/matplotlib.patches.html for more
 # information on patch properties
-#patch.linewidth   	: 1.0     # edge width in points
-#patch.facecolor  	: blue
-#patch.edgecolor  	: black
-#patch.antialiased 	: True    # render patches in antialised (no jaggies)
+#patch.linewidth    : 1.0     # edge width in points
+#patch.facecolor    : blue
+#patch.edgecolor    : black
+#patch.antialiased  : True    # render patches in antialised (no jaggies)
 
 ### FONT
 #
@@ -152,11 +152,11 @@ backend      : Agg
 #text.markup         : 'plain'  # Affects how text, such as titles and labels, are
                                 # interpreted by default.
                                 # 'plain': As plain, unformatted text
-				# 'tex': As TeX-like text.  Text between $'s will be
-				# formatted as a TeX math expression.
-				# This setting has no effect when text.usetex is True.
-				# In that case, all text will be sent to TeX for
-				# processing.
+                                # 'tex': As TeX-like text.  Text between $'s will be
+                                # formatted as a TeX math expression.
+                                # This setting has no effect when text.usetex is True.
+                                # In that case, all text will be sent to TeX for
+                                # processing.
 
 # The following settings allow you to select the fonts in math mode.
 # They map from a TeX font name to a fontconfig font pattern.
@@ -170,8 +170,8 @@ backend      : Agg
 #mathtext.fontset : cm # Should be 'cm' (Computer Modern), 'stix',
                        # 'stixsans' or 'custom'
 #mathtext.fallback_to_cm : True  # When True, use symbols from the Computer Modern
-			         # fonts when a symbol can not be found in one of
-				 # the custom math fonts.
+                                 # fonts when a symbol can not be found in one of
+                                 # the custom math fonts.
 
 ### AXES
 # default face and edge color, default tick sizes,
@@ -266,8 +266,7 @@ figure.figsize   : 6, 4    # figure size in inches
 #savefig.dpi       : 100      # figure dots per inch
 #savefig.facecolor : white    # figure facecolor when saving
 #savefig.edgecolor : white    # figure edgecolor when saving
-
-#cairo.format      : png      # png, ps, pdf, svg
+#savefig.format    : png      # png, ps, pdf, svg
 
 # tk backend params
 #tk.window_focus   : False    # Maintain shell focus for TkAgg

examples/tests/backend_driver.py

@@ -9,11 +9,10 @@
 switch, which takes a comma-separated list, or as separate arguments,
 e.g.
 
-    python backend_driver.py agg ps cairo.png cairo.ps
+    python backend_driver.py agg ps
 
-would test the agg and ps backends, and the cairo backend with output
-to png and ps files. If no arguments are given, a default list of
-backends will be tested.
+would test the agg and ps backends. If no arguments are given, a
+default list of backends will be tested.
 
 Interspersed with the backend arguments can be switches for the Python
 interpreter executing the tests. If entering such arguments causes an
@@ -27,7 +26,6 @@
 from matplotlib.cbook import Bunch, dedent
 
 all_backends = list(rcsetup.all_backends)  # to leave the original list alone
-all_backends.extend(['cairo.png', 'cairo.ps', 'cairo.pdf', 'cairo.svg'])
 
 # actual physical directory for each dir
 dirs = dict(pylab = os.path.join('..', 'pylab_examples'),
@@ -408,8 +406,7 @@ def parse_options():
                   help=dedent('''
       Run tests only for these backends; comma-separated list of
       one or more of: agg, ps, svg, pdf, template, cairo,
-      cairo.png, cairo.ps, cairo.pdf, cairo.svg. Default is everything
-      except cairo.'''))
+      Default is everything except cairo.'''))
     op.add_option('--clean', action='store_true', dest='clean',
                   help='Remove result directories, run no tests')
     op.add_option('-c', '--coverage', action='store_true', dest='coverage',

lib/matplotlib/__init__.py

@@ -144,8 +144,7 @@ def byte2str(b): return b
 
 from matplotlib.rcsetup import (defaultParams,
                                 validate_backend,
-                                validate_toolbar,
-                                validate_cairo_format)
+                                validate_toolbar)
 
 major, minor1, minor2, s, tmp = sys.version_info
 _python24 = (major == 2 and minor1 >= 4) or major >= 3
@@ -631,7 +630,8 @@ def matplotlib_fname():
     'text.fontweight':  'font.weight',
     'text.fontsize':    'font.size',
     'tick.size' :       'tick.major.size',
-    'svg.embed_char_paths' : 'svg.fonttype'
+    'svg.embed_char_paths' : 'svg.fonttype',
+    'savefig.extension' : 'savefig.format'
     }
 
 _deprecated_ignore_map = {
@@ -909,13 +909,7 @@ def use(arg, warn=True):
     """
     Set the matplotlib backend to one of the known backends.
 
-    The argument is case-insensitive.  For the Cairo backend,
-    the argument can have an extension to indicate the type of
-    output.  Example:
-
-        use('cairo.pdf')
-
-    will specify a default of pdf output generated by Cairo.
+    The argument is case-insensitive.
 
     .. note::
 
@@ -940,13 +934,7 @@ def use(arg, warn=True):
     else:
         # Lowercase only non-module backend names (modules are case-sensitive)
         arg = arg.lower()
-        be_parts = arg.split('.')
-        name = validate_backend(be_parts[0])
-        if len(be_parts) > 1:
-            if name == 'cairo':
-                rcParams['cairo.format'] = validate_cairo_format(be_parts[1])
-            else:
-                raise ValueError('Only cairo backend has a format option')
+        name = validate_backend(arg)
     rcParams['backend'] = name
 
 def get_backend():

lib/matplotlib/backend_bases.py

@@ -1897,9 +1897,14 @@ def print_tif(self, filename_or_obj, *args, **kwargs):
         print_tiff = print_tif
 
     def get_supported_filetypes(self):
+        """Return dict of savefig file formats supported by this backend"""
         return self.filetypes
 
     def get_supported_filetypes_grouped(self):
+        """Return a dict of savefig file formats supported by this backend,
+        where the keys are a file type name, such as 'Joint Photographic
+        Experts Group', and the values are a list of filename extensions used
+        for that filetype, such as ['jpg', 'jpeg']."""
         groupings = {}
         for ext, name in self.filetypes.iteritems():
             groupings.setdefault(name, []).append(ext)
@@ -1921,10 +1926,9 @@ def _print_method(*args, **kwargs):
 
             return _print_method
 
-        if (format not in self.filetypes or
-            not hasattr(self, method_name)):
-            formats = self.filetypes.keys()
-            formats.sort()
+        formats = self.get_supported_filetypes()
+        if (format not in formats or not hasattr(self, method_name)):
+            formats = sorted(formats)
             raise ValueError(
                 'Format "%s" is not supported.\n'
                 'Supported formats: '
@@ -1964,7 +1968,6 @@ def print_figure(self, filename, dpi=None, facecolor='w', edgecolor='w',
         *format*
             when set, forcibly set the file format to save to
 
-
         *bbox_inches*
             Bbox in inches. Only the given portion of the figure is
             saved. If 'tight', try to figure out the tight bbox of
@@ -1980,6 +1983,7 @@ def print_figure(self, filename, dpi=None, facecolor='w', edgecolor='w',
 
         """
         if format is None:
+            # get format from filename, or from backend's default filetype
             if cbook.is_string_like(filename):
                 format = os.path.splitext(filename)[1][1:]
             if format is None or format == '':
@@ -2078,7 +2082,12 @@ def print_figure(self, filename, dpi=None, facecolor='w', edgecolor='w',
 
 
     def get_default_filetype(self):
-        raise NotImplementedError
+        """
+        Get the default savefig file format as specified in rcParam
+        ``savefig.format``. Returned string excludes period. Overridden
+        in backends that only support a single file type.
+        """
+        return rcParams['savefig.format']
 
     def set_window_title(self, title):
         """

lib/matplotlib/backends/backend_agg.py

@@ -463,9 +463,6 @@ def buffer_rgba(self):
                                      'debug-annoying')
         return self.renderer.buffer_rgba()
 
-    def get_default_filetype(self):
-        return 'png'
-
     def print_raw(self, filename_or_obj, *args, **kwargs):
         FigureCanvasAgg.draw(self)
         renderer = self.get_renderer()