Deprecate the private FigureCanvasGTK3._renderer_init.

anntzer · anntzer · commit edcc3c3998e1 · 2020-05-21T09:06:48.000+02:00
Previously, subclasses of FigureCanvasGTK3 needed to override the
undocumented `_renderer_init` method.  Instead, just move the relevant
initialization code to the subclass' `__init__`.  (Conceptually this is
similar to the deprecation of `_init_toolbar` method on toolbars.)
diff --git a/doc/api/api_changes_3.3/deprecations.rst b/doc/api/api_changes_3.3/deprecations.rst
@@ -406,6 +406,16 @@ what the docs stated).  They are deprecated; if you write a backend
 which needs to customize such events, please directly override
 ``press_pan``/``press_zoom``/``release_pan``/``release_zoom`` instead.
 
+FigureCanvasGTK3._renderer_init
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Overriding this method to initialize renderers for GTK3 canvases is deprecated.
+Instead, the renderer should be initialized in the ``__init__`` method of the
+subclass (which should call the base-class' ``__init__`` as appropriate).  To
+keep back-compatibility with earlier versions of Matplotlib (which *required*
+``_renderer_init`` to be overridden), a fully empty implementation (``def
+_renderer_init(self): pass``) may be kept and will not trigger the deprecation
+warning.
+
 Path helpers in :mod:`.bezier`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/lib/matplotlib/backends/backend_gtk3.py b/lib/matplotlib/backends/backend_gtk3.py
@@ -176,7 +176,19 @@ def __init__(self, figure):
 
         self.set_double_buffered(True)
         self.set_can_focus(True)
-        self._renderer_init()
+
+        renderer_init = cbook._deprecate_method_override(
+            __class__._renderer_init, self, allow_empty=True, since="3.3",
+            addendum="Please initialize the renderer, if needed, in the "
+            "subclass' __init__; a fully empty _renderer_init implementation "
+            "may be kept for compatibility with earlier versions of "
+            "Matplotlib.")
+        if renderer_init:
+            renderer_init()
+
+    @cbook.deprecated("3.3", alternative="__init__")
+    def _renderer_init(self):
+        pass
 
     def destroy(self):
         #Gtk.DrawingArea.destroy(self)
diff --git a/lib/matplotlib/backends/backend_gtk3agg.py b/lib/matplotlib/backends/backend_gtk3agg.py
@@ -17,9 +17,6 @@ def __init__(self, figure):
         backend_gtk3.FigureCanvasGTK3.__init__(self, figure)
         self._bbox_queue = []
 
-    def _renderer_init(self):
-        pass
-
     def _render_figure(self, width, height):
         backend_agg.FigureCanvasAgg.draw(self)
 
diff --git a/lib/matplotlib/backends/backend_gtk3cairo.py b/lib/matplotlib/backends/backend_gtk3cairo.py
@@ -16,8 +16,8 @@ def set_context(self, ctx):
 class FigureCanvasGTK3Cairo(backend_gtk3.FigureCanvasGTK3,
                             backend_cairo.FigureCanvasCairo):
 
-    def _renderer_init(self):
-        """Use cairo renderer."""
+    def __init__(self, figure):
+        super().__init__(figure)
         self._renderer = RendererGTK3Cairo(self.figure.dpi)
 
     def _render_figure(self, width, height):
