Make the signature of Axes.draw() consistent with Artist.draw().

anntzer · anntzer · commit b226b0723a15 · 2020-01-01T18:27:22.000+01:00
... i.e. draw(renderer) instead of draw(renderer=None, inframe=False)
(with a deprecation period).
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -96,3 +96,15 @@ colormapping such as ``scatter()`` and ``imshow()`` is deprecated.
 Inestead of ``norm=LogNorm(), vmin=min_val, vmax=max_val`` pass
 ``norm=LogNorm(min_val, max_val)``. *vmin* and *vmax* should only be used
 without setting *norm*.
+
+Signatures of `.Artist.draw` and `.Axes.draw`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The *inframe* parameter to `.Axes.draw` is deprecated.  Use
+`.Axes.redraw_in_frame` instead.
+
+Not passing the *renderer* parameter to `.Axes.draw` is deprecated.  Use
+``axes.draw_artist(axes)`` instead.
+
+These changes make the signature of the ``draw`` (``artist.draw(renderer)``)
+method consistent across all artists; thus, additional parameters to
+`.Artist.draw` are deprecated.
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -26,7 +26,10 @@ def allow_rasterization(draw):
     renderer.
     """
 
-    # the axes class has a second argument inframe for its draw method.
+    # Axes has a second (deprecated) argument inframe for its draw method.
+    # args and kwargs are deprecated, but we don't wrap this in
+    # cbook._delete_parameter for performance; the relevant deprecation
+    # warning will be emitted by the inner draw() call.
     @wraps(draw)
     def draw_wrapper(artist, renderer, *args, **kwargs):
         try:
@@ -899,6 +902,8 @@ def set_agg_filter(self, filter_func):
         self._agg_filter = filter_func
         self.stale = True
 
+    @cbook._delete_parameter("3.3", "args")
+    @cbook._delete_parameter("3.3", "kwargs")
     def draw(self, renderer, *args, **kwargs):
         """
         Draw the Artist (and its children) using the given renderer.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1,4 +1,5 @@
 from collections import OrderedDict
+from contextlib import ExitStack
 import itertools
 import logging
 import math
@@ -2608,9 +2609,16 @@ def _update_title_position(self, renderer):
 
     # Drawing
     @martist.allow_rasterization
+    @cbook._delete_parameter(
+        "3.3", "inframe", alternative="Axes.redraw_in_frame()")
     def draw(self, renderer=None, inframe=False):
         # docstring inherited
         if renderer is None:
+            cbook.warn_deprecated(
+                "3.3", message="Support for not passing the 'renderer' "
+                "paramater to Axes.draw() is deprecated since %(since)s and "
+                "will be removed %(removal)s.  Use axes.draw_artist(axes) "
+                "instead.")
             renderer = self.figure._cachedRenderer
         if renderer is None:
             raise RuntimeError('No renderer defined')
@@ -2691,7 +2699,7 @@ def draw_artist(self, a):
         """
         This method can only be used after an initial draw which
         caches the renderer.  It is used to efficiently update Axes
-        data (axis ticks, labels, etc are not updated)
+        data (axis ticks, labels, etc are not updated).
         """
         if self.figure._cachedRenderer is None:
             raise AttributeError("draw_artist can only be used after an "
@@ -2702,12 +2710,17 @@ def redraw_in_frame(self):
         """
         This method can only be used after an initial draw which
         caches the renderer.  It is used to efficiently update Axes
-        data (axis ticks, labels, etc are not updated)
+        data (axis ticks, labels, etc are not updated).
         """
         if self.figure._cachedRenderer is None:
             raise AttributeError("redraw_in_frame can only be used after an "
                                  "initial draw which caches the renderer")
-        self.draw(self.figure._cachedRenderer, inframe=True)
+        with ExitStack() as stack:
+            for artist in [*self._get_axis_list(),
+                           self.title, self._left_title, self._right_title]:
+                stack.push(artist.set_visible, artist.get_visible())
+                artist.set_visible(False)
+            self.draw(self.figure._cachedRenderer)
 
     def get_renderer_cache(self):
         return self.figure._cachedRenderer
diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -309,7 +309,7 @@ def __repr__(self):
 _deprecated_parameter = _deprecated_parameter_class()
 
 
-def _delete_parameter(since, name, func=None):
+def _delete_parameter(since, name, func=None, **kwargs):
     """
     Decorator indicating that parameter *name* of *func* is being deprecated.
 
@@ -322,6 +322,8 @@ def _delete_parameter(since, name, func=None):
     such after the deprecation period has passed and the deprecated parameter
     is removed.
 
+    Additional kwargs are passed to `.warn_deprecated`.
+
     Examples
     --------
     ::
@@ -330,29 +332,45 @@ def func(used_arg, other_arg, unused, more_args): ...
     """
 
     if func is None:
-        return functools.partial(_delete_parameter, since, name)
+        return functools.partial(_delete_parameter, since, name, **kwargs)
 
     signature = inspect.signature(func)
     assert name in signature.parameters, (
         f"Matplotlib internal error: {name!r} must be a parameter for "
         f"{func.__name__}()")
-    func.__signature__ = signature.replace(parameters=[
-        param.replace(default=_deprecated_parameter) if param.name == name
-        else param
-        for param in signature.parameters.values()])
+    kind = signature.parameters[name].kind
+    is_varargs = kind is inspect.Parameter.VAR_POSITIONAL
+    is_varkwargs = kind is inspect.Parameter.VAR_KEYWORD
+    if not is_varargs and not is_varkwargs:
+        func.__signature__ = signature = signature.replace(parameters=[
+            param.replace(default=_deprecated_parameter) if param.name == name
+            else param
+            for param in signature.parameters.values()])
 
     @functools.wraps(func)
-    def wrapper(*args, **kwargs):
-        arguments = func.__signature__.bind(*args, **kwargs).arguments
+    def wrapper(*inner_args, **inner_kwargs):
+        arguments = signature.bind(*inner_args, **inner_kwargs).arguments
+        if is_varargs and arguments[name]:
+            warn_deprecated(
+                since, message=f"Additional positional arguments to "
+                f"{func.__name__}() are deprecated since %(since)s and "
+                f"support for them will be removed %(removal)s.")
+        elif is_varkwargs and arguments[name]:
+            warn_deprecated(
+                since, message=f"Additional keyword arguments to "
+                f"{func.__name__}() are deprecated since %(since)s and "
+                f"support for them will be removed %(removal)s.")
         # We cannot just check `name not in arguments` because the pyplot
         # wrappers always pass all arguments explicitly.
-        if name in arguments and arguments[name] != _deprecated_parameter:
+        elif name in arguments and arguments[name] != _deprecated_parameter:
             warn_deprecated(
-                since, message=f"The {name!r} parameter of {func.__name__}() "
-                f"is deprecated since Matplotlib {since} and will be removed "
-                f"%(removal)s.  If any parameter follows {name!r}, they "
-                f"should be pass as keyword, not positionally.")
-        return func(*args, **kwargs)
+                since,
+                name=repr(name),
+                obj_type=f"parameter of {func.__name__}()",
+                addendum=(f"If any parameter follows {name!r}, they should be "
+                          f"passed as keyword, not positionally."),
+                **kwargs)
+        return func(*inner_args, **inner_kwargs)
 
     return wrapper
 
