Merge pull request matplotlib#26469 from anntzer/dppke

Deprecate PdfPages(keep_empty=True).

Author: ksunden

doc/api/next_api_changes/deprecations/26469-AL.rst

@@ -0,0 +1,13 @@
+``PdfPages(keep_empty=True)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A zero-page pdf is not valid, thus passing ``keep_empty=True`` to
+`.backend_pdf.PdfPages` and `.backend_pgf.PdfPages`, and the ``keep_empty``
+attribute of these classes, are deprecated.  Currently, these classes default
+to keeping empty outputs, but that behavior is deprecated too.  Explicitly
+passing ``keep_empty=False`` remains supported for now to help transition to
+the new behavior.
+
+Furthermore, `.backend_pdf.PdfPages` no longer immediately creates the target
+file upon instantiation, but only when the first figure is saved.  To fully
+control file creation, directly pass an opened file object as argument
+(``with open(path, "wb") as file, PdfPages(file) as pdf: ...``).

lib/matplotlib/backends/backend_pdf.py

@@ -2669,18 +2669,19 @@ class PdfPages:
     In reality `PdfPages` is a thin wrapper around `PdfFile`, in order to avoid
     confusion when using `~.pyplot.savefig` and forgetting the format argument.
     """
-    __slots__ = ('_file', 'keep_empty')
 
-    def __init__(self, filename, keep_empty=True, metadata=None):
+    _UNSET = object()
+
+    def __init__(self, filename, keep_empty=_UNSET, metadata=None):
         """
         Create a new PdfPages object.
 
         Parameters
         ----------
         filename : str or path-like or file-like
-            Plots using `PdfPages.savefig` will be written to a file at this
-            location. The file is opened at once and any older file with the
-            same name is overwritten.
+            Plots using `PdfPages.savefig` will be written to a file at this location.
+            The file is opened when a figure is saved for the first time (overwriting
+            any older file with the same name).
 
         keep_empty : bool, optional
             If set to False, then empty pdf files will be deleted automatically
@@ -2696,34 +2697,50 @@ def __init__(self, filename, keep_empty=True, metadata=None):
             'Trapped'. Values have been predefined for 'Creator', 'Producer'
             and 'CreationDate'. They can be removed by setting them to `None`.
         """
-        self._file = PdfFile(filename, metadata=metadata)
-        self.keep_empty = keep_empty
+        self._filename = filename
+        self._metadata = metadata
+        self._file = None
+        if keep_empty and keep_empty is not self._UNSET:
+            _api.warn_deprecated("3.8", message=(
+                "Keeping empty pdf files is deprecated since %(since)s and support "
+                "will be removed %(removal)s."))
+        self._keep_empty = keep_empty
+
+    keep_empty = _api.deprecate_privatize_attribute("3.8")
 
     def __enter__(self):
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.close()
 
+    def _ensure_file(self):
+        if self._file is None:
+            self._file = PdfFile(self._filename, metadata=self._metadata)  # init.
+        return self._file
+
     def close(self):
         """
         Finalize this object, making the underlying file a complete
         PDF file.
         """
-        self._file.finalize()
-        self._file.close()
-        if (self.get_pagecount() == 0 and not self.keep_empty and
-                not self._file.passed_in_file_object):
-            os.remove(self._file.fh.name)
-        self._file = None
+        if self._file is not None:
+            self._file.finalize()
+            self._file.close()
+            self._file = None
+        elif self._keep_empty:  # True *or* UNSET.
+            _api.warn_deprecated("3.8", message=(
+                "Keeping empty pdf files is deprecated since %(since)s and support "
+                "will be removed %(removal)s."))
+            PdfFile(self._filename, metadata=self._metadata)  # touch the file.
 
     def infodict(self):
         """
         Return a modifiable information dictionary object
         (see PDF reference section 10.2.1 'Document Information
         Dictionary').
         """
-        return self._file.infoDict
+        return self._ensure_file().infoDict
 
     def savefig(self, figure=None, **kwargs):
         """
@@ -2750,7 +2767,7 @@ def savefig(self, figure=None, **kwargs):
 
     def get_pagecount(self):
         """Return the current number of pages in the multipage pdf file."""
-        return len(self._file.pageList)
+        return len(self._ensure_file().pageList)
 
     def attach_note(self, text, positionRect=[-100, -100, 0, 0]):
         """
@@ -2759,7 +2776,7 @@ def attach_note(self, text, positionRect=[-100, -100, 0, 0]):
         page. It is outside the page per default to make sure it is
         invisible on printouts.
         """
-        self._file.newTextnote(text, positionRect)
+        self._ensure_file().newTextnote(text, positionRect)
 
 
 class FigureCanvasPdf(FigureCanvasBase):
@@ -2778,7 +2795,7 @@ def print_pdf(self, filename, *,
         self.figure.dpi = 72  # there are 72 pdf points to an inch
         width, height = self.figure.get_size_inches()
         if isinstance(filename, PdfPages):
-            file = filename._file
+            file = filename._ensure_file()
         else:
             file = PdfFile(filename, metadata=metadata)
         try:

lib/matplotlib/backends/backend_pgf.py

@@ -14,7 +14,7 @@
 from PIL import Image
 
 import matplotlib as mpl
-from matplotlib import cbook, font_manager as fm
+from matplotlib import _api, cbook, font_manager as fm
 from matplotlib.backend_bases import (
     _Backend, FigureCanvasBase, FigureManagerBase, RendererBase
 )
@@ -874,16 +874,10 @@ class PdfPages:
     ...     # When no figure is specified the current figure is saved
     ...     pdf.savefig()
     """
-    __slots__ = (
-        '_output_name',
-        'keep_empty',
-        '_n_figures',
-        '_file',
-        '_info_dict',
-        '_metadata',
-    )
 
-    def __init__(self, filename, *, keep_empty=True, metadata=None):
+    _UNSET = object()
+
+    def __init__(self, filename, *, keep_empty=_UNSET, metadata=None):
         """
         Create a new PdfPages object.
 
@@ -912,11 +906,17 @@ def __init__(self, filename, *, keep_empty=True, metadata=None):
         """
         self._output_name = filename
         self._n_figures = 0
-        self.keep_empty = keep_empty
+        if keep_empty and keep_empty is not self._UNSET:
+            _api.warn_deprecated("3.8", message=(
+                "Keeping empty pdf files is deprecated since %(since)s and support "
+                "will be removed %(removal)s."))
+        self._keep_empty = keep_empty
         self._metadata = (metadata or {}).copy()
         self._info_dict = _create_pdf_info_dict('pgf', self._metadata)
         self._file = BytesIO()
 
+    keep_empty = _api.deprecate_privatize_attribute("3.8")
+
     def _write_header(self, width_inches, height_inches):
         pdfinfo = ','.join(
             _metadata_to_str(k, v) for k, v in self._info_dict.items())
@@ -946,7 +946,10 @@ def close(self):
         self._file.write(rb'\end{document}\n')
         if self._n_figures > 0:
             self._run_latex()
-        elif self.keep_empty:
+        elif self._keep_empty:
+            _api.warn_deprecated("3.8", message=(
+                "Keeping empty pdf files is deprecated since %(since)s and support "
+                "will be removed %(removal)s."))
             open(self._output_name, 'wb').close()
         self._file.close()
 

lib/matplotlib/tests/test_backend_pdf.py

@@ -3,7 +3,6 @@
 import io
 import os
 from pathlib import Path
-from tempfile import NamedTemporaryFile
 
 import numpy as np
 import pytest
@@ -81,35 +80,44 @@ def test_multipage_properfinalize():
     assert len(s) < 40000
 
 
-def test_multipage_keep_empty():
+def test_multipage_keep_empty(tmp_path):
+    os.chdir(tmp_path)
+
     # test empty pdf files
-    # test that an empty pdf is left behind with keep_empty=True (default)
-    with NamedTemporaryFile(delete=False) as tmp:
-        with PdfPages(tmp) as pdf:
-            filename = pdf._file.fh.name
-        assert os.path.exists(filename)
-    os.remove(filename)
-    # test if an empty pdf is deleting itself afterwards with keep_empty=False
-    with PdfPages(filename, keep_empty=False) as pdf:
+
+    # an empty pdf is left behind with keep_empty unset
+    with pytest.warns(mpl.MatplotlibDeprecationWarning), PdfPages("a.pdf") as pdf:
+        pass
+    assert os.path.exists("a.pdf")
+
+    # an empty pdf is left behind with keep_empty=True
+    with pytest.warns(mpl.MatplotlibDeprecationWarning), \
+            PdfPages("b.pdf", keep_empty=True) as pdf:
         pass
-    assert not os.path.exists(filename)
+    assert os.path.exists("b.pdf")
+
+    # an empty pdf deletes itself afterwards with keep_empty=False
+    with PdfPages("c.pdf", keep_empty=False) as pdf:
+        pass
+    assert not os.path.exists("c.pdf")
+
     # test pdf files with content, they should never be deleted
-    fig, ax = plt.subplots()
-    ax.plot([1, 2, 3])
-    # test that a non-empty pdf is left behind with keep_empty=True (default)
-    with NamedTemporaryFile(delete=False) as tmp:
-        with PdfPages(tmp) as pdf:
-            filename = pdf._file.fh.name
-            pdf.savefig()
-        assert os.path.exists(filename)
-    os.remove(filename)
-    # test that a non-empty pdf is left behind with keep_empty=False
-    with NamedTemporaryFile(delete=False) as tmp:
-        with PdfPages(tmp, keep_empty=False) as pdf:
-            filename = pdf._file.fh.name
-            pdf.savefig()
-        assert os.path.exists(filename)
-    os.remove(filename)
+
+    # a non-empty pdf is left behind with keep_empty unset
+    with PdfPages("d.pdf") as pdf:
+        pdf.savefig(plt.figure())
+    assert os.path.exists("d.pdf")
+
+    # a non-empty pdf is left behind with keep_empty=True
+    with pytest.warns(mpl.MatplotlibDeprecationWarning), \
+            PdfPages("e.pdf", keep_empty=True) as pdf:
+        pdf.savefig(plt.figure())
+    assert os.path.exists("e.pdf")
+
+    # a non-empty pdf is left behind with keep_empty=False
+    with PdfPages("f.pdf", keep_empty=False) as pdf:
+        pdf.savefig(plt.figure())
+    assert os.path.exists("f.pdf")
 
 
 def test_composite_image():

lib/matplotlib/tests/test_backend_pgf.py

@@ -286,6 +286,47 @@ def test_pdf_pages_metadata_check(monkeypatch, system):
     }
 
 
+@needs_pgf_xelatex
+def test_multipage_keep_empty(tmp_path):
+    os.chdir(tmp_path)
+
+    # test empty pdf files
+
+    # an empty pdf is left behind with keep_empty unset
+    with pytest.warns(mpl.MatplotlibDeprecationWarning), PdfPages("a.pdf") as pdf:
+        pass
+    assert os.path.exists("a.pdf")
+
+    # an empty pdf is left behind with keep_empty=True
+    with pytest.warns(mpl.MatplotlibDeprecationWarning), \
+            PdfPages("b.pdf", keep_empty=True) as pdf:
+        pass
+    assert os.path.exists("b.pdf")
+
+    # an empty pdf deletes itself afterwards with keep_empty=False
+    with PdfPages("c.pdf", keep_empty=False) as pdf:
+        pass
+    assert not os.path.exists("c.pdf")
+
+    # test pdf files with content, they should never be deleted
+
+    # a non-empty pdf is left behind with keep_empty unset
+    with PdfPages("d.pdf") as pdf:
+        pdf.savefig(plt.figure())
+    assert os.path.exists("d.pdf")
+
+    # a non-empty pdf is left behind with keep_empty=True
+    with pytest.warns(mpl.MatplotlibDeprecationWarning), \
+            PdfPages("e.pdf", keep_empty=True) as pdf:
+        pdf.savefig(plt.figure())
+    assert os.path.exists("e.pdf")
+
+    # a non-empty pdf is left behind with keep_empty=False
+    with PdfPages("f.pdf", keep_empty=False) as pdf:
+        pdf.savefig(plt.figure())
+    assert os.path.exists("f.pdf")
+
+
 @needs_pgf_xelatex
 def test_tex_restart_after_error():
     fig = plt.figure()