Remove 3.8 deprecations in backends

Author: QuLogic

doc/api/next_api_changes/removals/28874-ES.rst

@@ -1,3 +1,66 @@
+Auto-closing of figures when switching backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allowable backend switches (i.e. those that do not swap a GUI event loop with another
+one) will not close existing figures. If necessary, call ``plt.close("all")`` before
+switching.
+
+
+``FigureCanvasBase.switch_backends``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... has been removed with no replacement.
+
+
+Accessing ``event.guiEvent`` after event handlers return
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... is no longer supported, and ``event.guiEvent`` will be set to None once the event
+handlers return. For some GUI toolkits, it is unsafe to use the event, though you may
+separately stash the object at your own risk.
+
+
+``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, is no
+longer allowed, and empty PDF files will not be created.
+
+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: ...``).
+
+
+``backend_ps.psDefs``
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``psDefs`` module-level variable in ``backend_ps`` has been removed with no
+replacement.
+
+
+Automatic papersize selection in PostScript
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting :rc:`ps.papersize` to ``'auto'`` or passing ``papersize='auto'`` to
+`.Figure.savefig` is no longer supported. Either pass an explicit paper type name, or
+omit this parameter to use the default from the rcParam.
+
+
+``RendererAgg.tostring_rgb`` and ``FigureCanvasAgg.tostring_rgb``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... have been remove with no direct replacement. Consider using ``buffer_rgba`` instead,
+which should cover most use cases.
+
+
+``NavigationToolbar2QT.message`` has been removed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... with no replacement.
+
+
 ``axes_grid1`` API changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

lib/matplotlib/backend_bases.py

@@ -1178,26 +1178,12 @@ class Event:
     def __init__(self, name, canvas, guiEvent=None):
         self.name = name
         self.canvas = canvas
-        self._guiEvent = guiEvent
-        self._guiEvent_deleted = False
+        self.guiEvent = guiEvent
 
     def _process(self):
         """Process this event on ``self.canvas``, then unset ``guiEvent``."""
         self.canvas.callbacks.process(self.name, self)
-        self._guiEvent_deleted = True
-
-    @property
-    def guiEvent(self):
-        # After deprecation elapses: remove _guiEvent_deleted; make guiEvent a plain
-        # attribute set to None by _process.
-        if self._guiEvent_deleted:
-            _api.warn_deprecated(
-                "3.8", message="Accessing guiEvent outside of the original GUI event "
-                "handler is unsafe and deprecated since %(since)s; in the future, the "
-                "attribute will be set to None after quitting the event handler.  You "
-                "may separately record the value of the guiEvent attribute at your own "
-                "risk.")
-        return self._guiEvent
+        self.guiEvent = None
 
 
 class DrawEvent(Event):
@@ -2097,12 +2083,6 @@ def print_figure(
         if dpi == 'figure':
             dpi = getattr(self.figure, '_original_dpi', self.figure.dpi)
 
-        if kwargs.get("papertype") == 'auto':
-            # When deprecation elapses, remove backend_ps._get_papertype & its callers.
-            _api.warn_deprecated(
-                "3.8", name="papertype='auto'", addendum="Pass an explicit paper type, "
-                "'figure', or omit the *papertype* argument entirely.")
-
         # Remove the figure manager, if any, to avoid resizing the GUI widget.
         with (cbook._setattr_cm(self, manager=None),
               self._switch_canvas_and_return_print_method(format, backend)
@@ -2207,20 +2187,6 @@ def get_default_filename(self):
         default_filetype = self.get_default_filetype()
         return f'{default_basename}.{default_filetype}'
 
-    @_api.deprecated("3.8")
-    def switch_backends(self, FigureCanvasClass):
-        """
-        Instantiate an instance of FigureCanvasClass
-
-        This is used for backend switching, e.g., to instantiate a
-        FigureCanvasPS from a FigureCanvasGTK.  Note, deep copying is
-        not done, so any changes to one of the instances (e.g., setting
-        figure size or line props), will be reflected in the other
-        """
-        newCanvas = FigureCanvasClass(self.figure)
-        newCanvas._is_saving = self._is_saving
-        return newCanvas
-
     def mpl_connect(self, s, func):
         """
         Bind function *func* to event *s*.

lib/matplotlib/backend_bases.pyi

@@ -199,13 +199,11 @@ class TimerBase:
 class Event:
     name: str
     canvas: FigureCanvasBase
+    guiEvent: Any
     def __init__(
         self, name: str, canvas: FigureCanvasBase, guiEvent: Any | None = ...
     ) -> None: ...
 
-    @property
-    def guiEvent(self) -> Any: ...
-
 class DrawEvent(Event):
     renderer: RendererBase
     def __init__(
@@ -348,7 +346,6 @@ class FigureCanvasBase:
     def get_default_filetype(cls) -> str: ...
     def get_default_filename(self) -> str: ...
     _T = TypeVar("_T", bound=FigureCanvasBase)
-    def switch_backends(self, FigureCanvasClass: type[_T]) -> _T: ...
     def mpl_connect(self, s: str, func: Callable[[Event], Any]) -> int: ...
     def mpl_disconnect(self, cid: int) -> None: ...
     def new_timer(

lib/matplotlib/backends/backend_agg.py

@@ -266,10 +266,6 @@ def buffer_rgba(self):
     def tostring_argb(self):
         return np.asarray(self._renderer).take([3, 0, 1, 2], axis=2).tobytes()
 
-    @_api.deprecated("3.8", alternative="buffer_rgba")
-    def tostring_rgb(self):
-        return np.asarray(self._renderer).take([0, 1, 2], axis=2).tobytes()
-
     def clear(self):
         self._renderer.clear()
 
@@ -398,16 +394,6 @@ def get_renderer(self):
             self._lastKey = key
         return self.renderer
 
-    @_api.deprecated("3.8", alternative="buffer_rgba")
-    def tostring_rgb(self):
-        """
-        Get the image as RGB `bytes`.
-
-        `draw` must be called at least once before this function will work and
-        to update the renderer for any subsequent changes to the Figure.
-        """
-        return self.renderer.tostring_rgb()
-
     def tostring_argb(self):
         """
         Get the image as ARGB `bytes`.

lib/matplotlib/backends/backend_pdf.py

@@ -2663,9 +2663,9 @@ class PdfPages:
     confusion when using `~.pyplot.savefig` and forgetting the format argument.
     """
 
-    _UNSET = object()
-
-    def __init__(self, filename, keep_empty=_UNSET, metadata=None):
+    @_api.delete_parameter("3.10", "keep_empty",
+                           addendum="This parameter does nothing.")
+    def __init__(self, filename, keep_empty=None, metadata=None):
         """
         Create a new PdfPages object.
 
@@ -2676,10 +2676,6 @@ def __init__(self, filename, keep_empty=_UNSET, metadata=None):
             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
-            when closed.
-
         metadata : dict, optional
             Information dictionary object (see PDF reference section 10.2.1
             'Document Information Dictionary'), e.g.:
@@ -2693,13 +2689,6 @@ def __init__(self, filename, keep_empty=_UNSET, metadata=None):
         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
@@ -2721,11 +2710,6 @@ def close(self):
             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).close()  # touch the file.
 
     def infodict(self):
         """

lib/matplotlib/backends/backend_pgf.py

@@ -14,7 +14,7 @@
 from PIL import Image
 
 import matplotlib as mpl
-from matplotlib import _api, cbook, font_manager as fm
+from matplotlib import cbook, font_manager as fm
 from matplotlib.backend_bases import (
     _Backend, FigureCanvasBase, FigureManagerBase, RendererBase
 )
@@ -898,9 +898,7 @@ class PdfPages:
     ...     pdf.savefig()
     """
 
-    _UNSET = object()
-
-    def __init__(self, filename, *, keep_empty=_UNSET, metadata=None):
+    def __init__(self, filename, *, metadata=None):
         """
         Create a new PdfPages object.
 
@@ -910,10 +908,6 @@ def __init__(self, filename, *, keep_empty=_UNSET, metadata=None):
             Plots using `PdfPages.savefig` will be written to a file at this
             location. Any older file with the same name is overwritten.
 
-        keep_empty : bool, default: True
-            If set to False, then empty pdf files will be deleted automatically
-            when closed.
-
         metadata : dict, optional
             Information dictionary object (see PDF reference section 10.2.1
             'Document Information Dictionary'), e.g.:
@@ -929,17 +923,10 @@ def __init__(self, filename, *, keep_empty=_UNSET, metadata=None):
         """
         self._output_name = filename
         self._n_figures = 0
-        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())
@@ -969,11 +956,6 @@ def close(self):
         self._file.write(rb'\end{document}\n')
         if self._n_figures > 0:
             self._run_latex()
-        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()
 
     def _run_latex(self):

lib/matplotlib/backends/backend_ps.py

@@ -39,12 +39,6 @@
 debugPS = False
 
 
-@_api.caching_module_getattr
-class __getattr__:
-    # module-level deprecations
-    psDefs = _api.deprecated("3.8", obj_type="")(property(lambda self: _psDefs))
-
-
 papersize = {'letter': (8.5, 11),
              'legal': (8.5, 14),
              'ledger': (11, 17),
@@ -72,15 +66,6 @@ class __getattr__:
              'b10': (1.26, 1.76)}
 
 
-def _get_papertype(w, h):
-    for key, (pw, ph) in sorted(papersize.items(), reverse=True):
-        if key.startswith('l'):
-            continue
-        if w < pw and h < ph:
-            return key
-    return 'a0'
-
-
 def _nums_to_str(*args, sep=" "):
     return sep.join(f"{arg:1.3f}".rstrip("0").rstrip(".") for arg in args)
 
@@ -828,7 +813,7 @@ def _print_ps(
         if papertype is None:
             papertype = mpl.rcParams['ps.papersize']
         papertype = papertype.lower()
-        _api.check_in_list(['figure', 'auto', *papersize], papertype=papertype)
+        _api.check_in_list(['figure', *papersize], papertype=papertype)
 
         orientation = _api.check_getitem(
             _Orientation, orientation=orientation.lower())
@@ -858,9 +843,6 @@ def _print_figure(
 
         # find the appropriate papertype
         width, height = self.figure.get_size_inches()
-        if papertype == 'auto':
-            papertype = _get_papertype(*orientation.swap_if_landscape((width, height)))
-
         if is_eps or papertype == 'figure':
             paper_width, paper_height = width, height
         else:
@@ -1041,8 +1023,6 @@ def _print_figure_tex(
                 paper_width, paper_height = orientation.swap_if_landscape(
                     self.figure.get_size_inches())
             else:
-                if papertype == 'auto':
-                    papertype = _get_papertype(width, height)
                 paper_width, paper_height = papersize[papertype]
 
             psfrag_rotated = _convert_psfrags(

lib/matplotlib/backends/backend_qt.py

@@ -658,9 +658,6 @@ def set_window_title(self, title):
 
 
 class NavigationToolbar2QT(NavigationToolbar2, QtWidgets.QToolBar):
-    _message = QtCore.Signal(str)  # Remove once deprecation below elapses.
-    message = _api.deprecate_privatize_attribute("3.8")
-
     toolitems = [*NavigationToolbar2.toolitems]
     toolitems.insert(
         # Add 'customize' action after 'subplots'
@@ -783,7 +780,6 @@ def zoom(self, *args):
         self._update_buttons_checked()
 
     def set_message(self, s):
-        self._message.emit(s)
         if self.coordinates:
             self.locLabel.setText(s)
 

lib/matplotlib/pyplot.py

@@ -514,14 +514,6 @@ def draw_if_interactive() -> None:
     # See https://github.com/matplotlib/matplotlib/issues/6092
     matplotlib.backends.backend = newbackend  # type: ignore[attr-defined]
 
-    if not cbook._str_equal(old_backend, newbackend):
-        if get_fignums():
-            _api.warn_deprecated("3.8", message=(
-                "Auto-close()ing of figures upon backend switching is deprecated since "
-                "%(since)s and will be removed %(removal)s.  To suppress this warning, "
-                "explicitly call plt.close('all') first."))
-        close("all")
-
     # Make sure the repl display hook is installed in case we become interactive.
     install_repl_displayhook()