Create a PdfFile wrapper named PdfPages to act as the target of savefig

to avoid saving figures in png format onto the file-like PdfPages object.

svn path=/trunk/matplotlib/; revision=6739

Author: jkseppan

CHANGELOG

@@ -1,3 +1,6 @@
+2009-01-06 Change user-visible multipage pdf object to PdfPages to
+           avoid accidents with the file-like PdfFile. - JKS
+
 2009-01-05 Fix a bug in pdf usetex: allow using non-embedded fonts. - JKS
 
 2009-01-05 optional use of preview.sty in usetex mode. - JJL

doc/api/api_changes.rst

@@ -6,6 +6,10 @@ This chapter is a log of changes to matplotlib that affect the
 outward-facing API.  If updating matplotlib breaks your scripts, this
 list may help describe what changes may be necessary in your code.
 
+* You can now print several figures to one pdf file. See the docstrings
+  of the class :class:`matplotlib.backends.backend_pdf.PdfPages` for
+  more information.
+
 * Removed configobj_ and `enthought.traits`_ packages, which are only
   required by the experimental traited config and are somewhat out of
   date. If needed, install them independently.

examples/pylab_examples/multipage_pdf.py

@@ -1,29 +1,33 @@
+# This is a demo of creating a pdf file with several pages.
+
 import numpy as np
 import matplotlib
-from matplotlib.backends.backend_pdf import PdfFile
+from matplotlib.backends.backend_pdf import PdfPages
 from pylab import *
 
-pdf = PdfFile('multipage_pdf.pdf')
+# Create the PdfPages object to which we will save the pages:
+pdf = PdfPages('multipage_pdf.pdf')
 
 figure(figsize=(3,3))
 plot(range(7), [3,1,4,1,5,9,2], 'r-o')
 title('Page One')
-savefig(pdf, format='pdf')
+savefig(pdf, format='pdf') # note the format='pdf' argument!
 close()
 
 rc('text', usetex=True)
 figure(figsize=(8,6))
 x = np.arange(0,5,0.1)
 plot(x, np.sin(x), 'b-')
 title('Page Two')
-savefig(pdf, format='pdf')
+pdf.savefig() # here's another way - or you could do pdf.savefig(1)
 close()
 
 rc('text', usetex=False)
-figure(figsize=(4,5))
+fig=figure(figsize=(4,5))
 plot(x, x*x, 'ko')
 title('Page Three')
-savefig(pdf, format='pdf')
+pdf.savefig(fig) # or you can pass a Figure object to pdf.savefig
 close()
 
+# Remember to close the object - otherwise the file will not be usable
 pdf.close()

lib/matplotlib/backends/backend_pdf.py

@@ -1882,6 +1882,63 @@ def new_figure_manager(num, *args, **kwargs):
     manager = FigureManagerPdf(canvas, num)
     return manager
 
+class PdfPages(object):
+    """
+    A multi-page PDF file.
+
+    Use like this:
+
+      # Initialize:
+      pdf_pages = PdfPages('foo.pdf')
+
+      # As many times as you like, create a figure fig, then either:
+      fig.savefig(pdf_pages, format='pdf') # note the format argument!
+      # or:
+      pdf_pages.savefig(fig)
+
+      # Once you are done, remember to close the object:
+      pdf_pages.close()
+
+    (In reality PdfPages is a thin wrapper around PdfFile, in order to
+    avoid confusion when using savefig and forgetting the format
+    argument.)
+    """
+    __slots__ = ('_file',)
+
+    def __init__(self, filename):
+        """
+        Create a new PdfPages object that will be written to the file
+        named *filename*. The file is opened at once and any older
+        file with the same name is overwritten.
+        """
+        self._file = PdfFile(filename)
+
+    def close(self):
+        """
+        Finalize this object, making the underlying file a complete
+        PDF file.
+        """
+        self._file.close()
+        self._file = None
+
+    def savefig(self, figure=None, **kwargs):
+        """
+        Save the Figure instance *figure* to this file as a new page.
+        If *figure* is a number, the figure instance is looked up by
+        number, and if *figure* is None, the active figure is saved.
+        Any other keyword arguments are passed to Figure.savefig.
+        """
+        if isinstance(figure, Figure):
+            figure.savefig(self, format='pdf', **kwargs)
+        else:
+            if figure is None:
+                figureManager = Gcf.get_active()
+            else:
+                figureManager = Gcf.get_fig_manager(figure)
+            if figureManager is None:
+                raise ValueError, "No such figure: " + `figure`
+            else:
+                figureManager.canvas.figure.savefig(self, format='pdf')
 
 class FigureCanvasPdf(FigureCanvasBase):
     """
@@ -1905,19 +1962,19 @@ def print_pdf(self, filename, **kwargs):
         image_dpi = kwargs.get('dpi', 72) # dpi to use for images
         self.figure.set_dpi(72)           # there are 72 pdf points to an inch
         width, height = self.figure.get_size_inches()
-        if isinstance(filename, PdfFile):
-            file = filename
+        if isinstance(filename, PdfPages):
+            file = filename._file
         else:
             file = PdfFile(filename)
         file.newPage(width, height)
         renderer = MixedModeRenderer(
             width, height, 72, RendererPdf(file, image_dpi))
         self.figure.draw(renderer)
         renderer.finalize()
-        if file != filename:    # we opened the file
-            file.close()
-        else:                   # multipage file; just finish off the page
+        if isinstance(filename, PdfPages): # finish off this page
             file.endStream()
+        else:            # we opened the file above; now finish it off
+            file.close()
 
 class FigureManagerPdf(FigureManagerBase):
     pass