only show preferred usage of PdfPages in examples

matplotlib · mdboom · Sep 18, 2013 · Sep 12, 2013 · Sep 12, 2013 · Sep 18, 2013
commit 303477a4f046c2e4ca83975cf3d3b2534f11b424
diff --git a/examples/pylab_examples/multipage_pdf.py b/examples/pylab_examples/multipage_pdf.py
@@ -7,54 +7,35 @@
 from pylab import *

 # 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') # 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')
-pdf.savefig() # here's another way - or you could do pdf.savefig(1)
-close()
-
-rc('text', usetex=False)
-fig=figure(figsize=(4,5))
-plot(x, x*x, 'ko')
-title('Page Three')
-pdf.savefig(fig) # or you can pass a Figure object to pdf.savefig
-close()
-
-# We can also set the file's metadata via the PdfPages object:
-d = pdf.infodict()
-d['Title'] = 'Multipage PDF Example'
-d['Author'] = u'Jouni K. Sepp\xe4nen'
-d['Subject'] = 'How to create a multipage pdf file and set its metadata'
-d['Keywords'] = 'PdfPages multipage keywords author title subject'
-d['CreationDate'] = datetime.datetime(2009,11,13)
-d['ModDate'] = datetime.datetime.today()
-
-# Remember to close the object - otherwise the file will not be usable
-pdf.close()
-
-# Or use the with statement, the file gets properly closed at the end:
-with PdfPages('multipage_pdf2.pdf') as pdf:
-
-    figure(figsize=(3, 3))
-    plot(range(7), [3, 1, 4, 1, 5, 9, 2], 'r-o')
+# The with statement makes sure that the PdfPages object is closed properly at
+# the end of the block, even if an Exception occurs.
+with PdfPages('multipage_pdf.pdf') as pdf:
+    figure(figsize=(3,3))
+    plot(range(7), [3,1,4,1,5,9,2], 'r-o')
    title('Page One')
-    pdf.savefig()
+    pdf.savefig()  # saves the current figure into a pdf page
    close()

    rc('text', usetex=True)
-    figure(figsize=(8, 6))
-    x = np.arange(0, 5, 0.1)
+    figure(figsize=(8,6))
+    x = np.arange(0,5,0.1)
    plot(x, np.sin(x), 'b-')
    title('Page Two')
    pdf.savefig()
    close()
+
+    rc('text', usetex=False)
+    fig=figure(figsize=(4,5))
+    plot(x, x*x, 'ko')
+    title('Page Three')
+    pdf.savefig(fig) # or you can pass a Figure object to pdf.savefig
+    close()
+
+    # We can also set the file's metadata via the PdfPages object:
+    d = pdf.infodict()
+    d['Title'] = 'Multipage PDF Example'
+    d['Author'] = u'Jouni K. Sepp\xe4nen'
+    d['Subject'] = 'How to create a multipage pdf file and set its metadata'
+    d['Keywords'] = 'PdfPages multipage keywords author title subject'
+    d['CreationDate'] = datetime.datetime(2009,11,13)
+    d['ModDate'] = datetime.datetime.today()
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -2248,21 +2248,12 @@ class PdfPages(object):
    Use like this::

        # Initialize:
-        pp = PdfPages('foo.pdf')
+        with PdfPages('foo.pdf') as pdf:

-        # As many times as you like, create a figure fig, then either:
-        fig.savefig(pp, format='pdf') # note the format argument!
-        # or:
-        pp.savefig(fig)
-
-        # Once you are done, remember to close the object:
-        pp.close()
-
-    Or using the with statement::
-
-        with PdfPages('foo.pdf') as pp:
-            fig.savefig(pp, format='pdf') # note the format argument!
-            pp.savefig(fig)
+            # As many times as you like, create a figure fig and save it:
+            # When no figure is specified the current figure is saved
+            pdf.savefig(fig)
+            pdf.savefig()

    (In reality PdfPages is a thin wrapper around PdfFile, in order to
    avoid confusion when using savefig and forgetting the format