Make signature of Axes.annotate() more explicit.

timhoffm · timhoffm · commit c4116bb841f6 · 2022-02-04T22:01:40.000+01:00
The signature is identical to Annotation. This makes the parameters
explicit instead of `*args`, which improves usability. On the downside,
this introduces redundancy. But we can bear that. The signature will
not change often and I've added a test that ensures the signatures
stay synchronized.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -662,8 +662,13 @@ def text(self, x, y, s, fontdict=None, **kwargs):
         return t
 
     @docstring.dedent_interpd
-    def annotate(self, text, xy, *args, **kwargs):
-        a = mtext.Annotation(text, xy, *args, **kwargs)
+    def annotate(self, text, xy, xytext=None, xycoords='data', textcoords=None,
+                 arrowprops=None, annotation_clip=None, **kwargs):
+        # Signature must match Annotation. This is verified in
+        # test_annotate_signature().
+        a = mtext.Annotation(text, xy, xytext=xytext, xycoords=xycoords,
+                             textcoords=textcoords, arrowprops=arrowprops,
+                             annotation_clip=annotation_clip, **kwargs)
         a.set_transform(mtransforms.IdentityTransform())
         if 'clip_on' in kwargs:
             a.set_clip_path(self.patch)
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2334,8 +2334,13 @@ def angle_spectrum(
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @_copy_docstring_and_deprecators(Axes.annotate)
-def annotate(text, xy, *args, **kwargs):
-    return gca().annotate(text, xy, *args, **kwargs)
+def annotate(
+        text, xy, xytext=None, xycoords='data', textcoords=None,
+        arrowprops=None, annotation_clip=None, **kwargs):
+    return gca().annotate(
+        text, xy, xytext=xytext, xycoords=xycoords,
+        textcoords=textcoords, arrowprops=arrowprops,
+        annotation_clip=annotation_clip, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -2,6 +2,7 @@
 import datetime
 from decimal import Decimal
 from functools import partial
+import inspect
 import io
 from itertools import product
 import platform
@@ -26,6 +27,7 @@
 import matplotlib.patches as mpatches
 import matplotlib.path as mpath
 import matplotlib.pyplot as plt
+import matplotlib.text as mtext
 import matplotlib.ticker as mticker
 import matplotlib.transforms as mtransforms
 from numpy.testing import (
@@ -622,6 +624,16 @@ def test_annotate_default_arrow():
     assert ann.arrow_patch is not None
 
 
+def test_annotate_signature():
+    """Check that the signature of Axes.annotate() matches Annotation."""
+    fig, ax = plt.subplots()
+    annotate_params = inspect.signature(ax.annotate).parameters
+    annotation_params = inspect.signature(mtext.Annotation).parameters
+    assert list(annotate_params.keys()) == list(annotation_params.keys())
+    for p1, p2 in zip(annotate_params.values(), annotation_params.values()):
+        assert p1 == p2
+
+
 @image_comparison(['fill_units.png'], savefig_kwarg={'dpi': 60})
 def test_fill_units():
     import matplotlib.testing.jpl_units as units
