MNT: deprecate draw method args and kwargs

doc/api/next_api_changes/deprecations/27768-REC.rst

@@ -0,0 +1,5 @@
+``[XYZ]Axis.draw``, ``*Image.draw`` *args* and *kwargs*...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... are deprecated because they have no effect.  This will make the calling sequence
+consistent with the ``draw`` method of other artists.

galleries/examples/misc/demo_ribbon_box.py

@@ -49,15 +49,15 @@ def __init__(self, ax, bbox, color, *, extent=(0, 1, 0, 1), **kwargs):
         self._ribbonbox = RibbonBox(color)
         self.set_transform(BboxTransformTo(bbox))
 
-    def draw(self, renderer, *args, **kwargs):
+    def draw(self, renderer):
         stretch_factor = self._bbox.height / self._bbox.width
 
         ny = int(stretch_factor*self._ribbonbox.nx)
         if self.get_array() is None or self.get_array().shape[0] != ny:
             arr = self._ribbonbox.get_stretched_image(stretch_factor)
             self.set_array(arr)
 
-        super().draw(renderer, *args, **kwargs)
+        super().draw(renderer)
 
 
 def main():

lib/matplotlib/axis.py

@@ -1373,6 +1373,8 @@ def get_tick_padding(self):
             values.append(self.minorTicks[0].get_tick_padding())
         return max(values, default=0)
 
+    @_api.delete_parameter('3.9', 'args')
+    @_api.delete_parameter('3.9', 'kwargs')
     @martist.allow_rasterization
     def draw(self, renderer, *args, **kwargs):
         # docstring inherited

lib/matplotlib/image.py

@@ -626,6 +626,8 @@ def _check_unsampled_image(self):
         """
         return False
 
+    @_api.delete_parameter('3.9', 'args')
+    @_api.delete_parameter('3.9', 'kwargs')
     @martist.allow_rasterization
     def draw(self, renderer, *args, **kwargs):
         # if not visible, declare victory and return

tools/stubtest.py

@@ -18,14 +18,33 @@ def __init__(self, filepath, output):
         self.output = output
 
     def visit_FunctionDef(self, node):
-        if any("delete_parameter" in ast.unparse(line) for line in node.decorator_list):
-            parents = []
-            if hasattr(node, "parent"):
-                parent = node.parent
-                while hasattr(parent, "parent") and not isinstance(parent, ast.Module):
-                    parents.insert(0, parent.name)
-                    parent = parent.parent
-            self.output.write(f"{'.'.join(self.context + parents)}.{node.name}\n")
+        # delete_parameter adds a private sentinel value that leaks
+        # we do not want that sentinel value in the type hints but it breaks typing
+        # Does not apply to variadic arguments (args/kwargs)
+        for dec in node.decorator_list:
+            if "delete_parameter" in ast.unparse(dec):
+                deprecated_arg = dec.args[1].value
+                if (
+                    node.args.vararg is not None
+                    and node.args.vararg.arg == deprecated_arg
+                ):
+                    continue
+                if (
+                    node.args.kwarg is not None
+                    and node.args.kwarg.arg == deprecated_arg
+                ):
+                    continue
+
+                parents = []
+                if hasattr(node, "parent"):
+                    parent = node.parent
+                    while hasattr(parent, "parent") and not isinstance(
+                        parent, ast.Module
+                    ):
+                        parents.insert(0, parent.name)
+                        parent = parent.parent
+                self.output.write(f"{'.'.join(self.context + parents)}.{node.name}\n")
+                break
 
     def visit_ClassDef(self, node):
         for dec in node.decorator_list: