Merge pull request #15049 from ksunden/annotate_argument

QuLogic · web-flow · commit a032c6f5edb7 · 2020-03-26T17:26:59.000-04:00
Annotate argument in axes class match upstream
diff --git a/doc/api/next_api_changes/behaviour.rst b/doc/api/next_api_changes/behaviour.rst
@@ -138,3 +138,12 @@ Calling ax.arrow() will now autoscale the axes.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ... because the offset text can rarely be interpreted without tick labels
 anyways.
+
+`.Axes.annotate` and `.pyplot.annotate` parameter name changed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The parameter ``s`` to `.Axes.annotate` and  `.pyplot.annotate` is renamed to
+``text``, matching `.Annotation`.
+
+The old parameter name remains supported, but
+support for it will be dropped in a future Matplotlib release.
+
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -753,9 +753,10 @@ def text(self, x, y, s, fontdict=None, **kwargs):
         self._add_text(t)
         return t
 
+    @cbook._rename_parameter("3.3", "s", "text")
     @docstring.dedent_interpd
-    def annotate(self, s, xy, *args, **kwargs):
-        a = mtext.Annotation(s, xy, *args, **kwargs)
+    def annotate(self, text, xy, *args, **kwargs):
+        a = mtext.Annotation(text, xy, *args, **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
@@ -2254,8 +2254,8 @@ def angle_spectrum(
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @_copy_docstring_and_deprecators(Axes.annotate)
-def annotate(s, xy, *args, **kwargs):
-    return gca().annotate(s, xy, *args, **kwargs)
+def annotate(text, xy, *args, **kwargs):
+    return gca().annotate(text, xy, *args, **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
@@ -435,6 +435,14 @@ def test_basic_annotate():
                 xytext=(3, 3), textcoords='offset points')
 
 
+def test_annotate_parameter_warn():
+    fig, ax = plt.subplots()
+    with pytest.warns(MatplotlibDeprecationWarning,
+                      match=r"The \'s\' parameter of annotate\(\) "
+                             "has been renamed \'text\'"):
+        ax.annotate(s='now named text', xy=(0, 1))
+
+
 @image_comparison(['arrow_simple.png'], remove_text=True)
 def test_arrow_simple():
     # Simple image test for ax.arrow
