Deprecate cleared kwarg to get_renderer.

This makes it easier for to mock the agg backend (e.g., in mplcairo).
Note that this is anyways only a shorthand for calling a method
(`.clear()`) on the renderer itself, so just issuing that call is just
as simple, more explicit, and can be done even when one just has access
to the renderer and not to the canvas (an admittedly rather hypothetical
case).

Author: anntzer

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

@@ -0,0 +1,4 @@
+*cleared* parameter of ``get_renderer``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This parameter, which only existed for agg-based backends, has been deprecated.
+Use ``renderer.clear()`` instead to explicitly clear the renderer buffer.

lib/matplotlib/backends/backend_agg.py

@@ -427,7 +427,8 @@ def restore_region(self, region, bbox=None, xy=None):
 
     def draw(self):
         # docstring inherited
-        self.renderer = self.get_renderer(cleared=True)
+        self.renderer = self.get_renderer()
+        self.renderer.clear()
         # Acquire a lock on the shared font cache.
         with RendererAgg.lock, \
              (self.toolbar._wait_cursor_for_draw_cm() if self.toolbar
@@ -437,6 +438,7 @@ def draw(self):
             # don't forget to call the superclass.
             super().draw()
 
+    @_api.delete_parameter("3.6", "cleared", alternative="renderer.clear()")
     def get_renderer(self, cleared=False):
         w, h = self.figure.bbox.size
         key = w, h, self.figure.dpi

lib/matplotlib/backends/backend_macosx.py

@@ -36,8 +36,9 @@ def set_cursor(self, cursor):
         _macosx.set_cursor(cursor)
 
     def _draw(self):
-        renderer = self.get_renderer(cleared=self.figure.stale)
+        renderer = self.get_renderer()
         if self.figure.stale:
+            renderer.clear()
             self.figure.draw(renderer)
         return renderer
 

lib/matplotlib/backends/backend_webagg_core.py

@@ -255,6 +255,7 @@ def get_diff_image(self):
                 Image.fromarray(data).save(png, format="png")
                 return png.getvalue()
 
+    @_api.delete_parameter("3.6", "cleared", alternative="renderer.clear()")
     def get_renderer(self, cleared=None):
         # Mirrors super.get_renderer, but caches the old one so that we can do
         # things such as produce a diff image in get_diff_image.