Deprecate PdfPages(keep_empty=True).

anntzer · anntzer · commit a87c18efd0f8 · 2023-08-08T10:48:53.000+02:00
... because 0-page pdfs are not valid pdf files.

Explicitly passing keep_empty=False remains supported for now to help
transitioning to the new behavior.

I also delayed file creation in backend_pdf.PdfPages as that seems
simpler than re-deleting the file at closure if needed.  I further
dropped `__slots__` as the micro-optimization of these classes seem
pointless (backend_pdf.PdfPages is wrapping a PdfFile object which is
much larger anyways).
diff --git a/doc/api/next_api_changes/deprecations/XXXXX-AL.rst b/doc/api/next_api_changes/deprecations/XXXXX-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: ...``).
diff --git a/lib/matplotlib/backends/backend_pdf.py b/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,8 +2697,16 @@ 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
@@ -2710,12 +2719,15 @@ 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):
         """
@@ -2744,6 +2756,8 @@ def savefig(self, figure=None, **kwargs):
             if manager is None:
                 raise ValueError(f"No figure {figure}")
             figure = manager.canvas.figure
+        if self._file is None:
+            self._file = PdfFile(self._filename, metadata=self._metadata)  # init.
         # Force use of pdf backend, as PdfPages is tightly coupled with it.
         with cbook._setattr_cm(figure, canvas=FigureCanvasPdf(figure)):
             figure.savefig(self, format="pdf", **kwargs)
diff --git a/lib/matplotlib/backends/backend_pgf.py b/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()
 
diff --git a/lib/matplotlib/tests/test_backend_pdf.py b/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():
diff --git a/lib/matplotlib/tests/test_backend_pgf.py b/lib/matplotlib/tests/test_backend_pgf.py
@@ -286,6 +286,46 @@ def test_pdf_pages_metadata_check(monkeypatch, system):
     }
 
 
+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()
