Examples of parameter renames.

anntzer · anntzer · commit 7fe750037e5e · 2019-01-14T11:05:12.000+01:00
diff --git a/doc/api/next_api_changes/2018-01-10-AL.rst b/doc/api/next_api_changes/2018-01-10-AL.rst
@@ -0,0 +1,11 @@
+Changes in parameter names
+``````````````````````````
+
+- The ``arg`` argument to `matplotlib.use` has been renamed to ``backend``.
+- The ``normed`` argument to `Axes.hist2d` has been renamed to ``density``.
+- The ``s`` argument to `Annotation` (and indirectly `Axes.annotation`) has
+  been renamed to ``text``.
+
+In each case, the old argument name remains supported (it cannot be used
+simultaneously with the new name), but suppport for it will be dropped in
+Matplotlib 3.3.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1171,13 +1171,14 @@ def __exit__(self, exc_type, exc_value, exc_tb):
         self.__fallback()
 
 
-def use(arg, warn=False, force=True):
+@cbook._rename_parameter("3.1", "arg", "backend")
+def use(backend, warn=False, force=True):
     """
     Set the matplotlib backend to one of the known backends.
 
     Parameters
     ----------
-    arg : str
+    backend : str
         The backend to switch to.  This can either be one of the
         'standard' backend names:
 
@@ -1193,6 +1194,8 @@ def use(arg, warn=False, force=True):
 
         Note: Standard backend names are case-insensitive here.
 
+        *arg* is a deprecated synonym for this parameter.
+
     warn : bool, optional
         If True, warn if this is called after pyplot has been imported
         and a backend is set up.
@@ -1209,7 +1212,7 @@ def use(arg, warn=False, force=True):
     :ref:`backends`
     matplotlib.get_backend
     """
-    name = validate_backend(arg)
+    name = validate_backend(backend)
 
     # if setting back to the same thing, do nothing
     if (dict.__getitem__(rcParams, 'backend') == name):
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6871,7 +6871,8 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
             return tops, bins, cbook.silent_list('Lists of Patches', patches)
 
     @_preprocess_data(replace_names=["x", "y", "weights"])
-    def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
+    @cbook._rename_parameter("3.1", "normed", "density")
+    def hist2d(self, x, y, bins=10, range=None, density=False, weights=None,
                cmin=None, cmax=None, **kwargs):
         """
         Make a 2D histogram plot.
@@ -6905,8 +6906,9 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
              xmax], [ymin, ymax]]``. All values outside of this range will be
              considered outliers and not tallied in the histogram.
 
-        normed : bool, optional, default: False
-             Normalize histogram.
+        density : bool, optional, default: False
+             Normalize histogram.  *normed* is a deprecated synonym for this
+             parameter.
 
         weights : array_like, shape (n, ), optional, default: None
             An array of values w_i weighing each sample (x_i, y_i).
@@ -6965,7 +6967,7 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
         """
 
         h, xedges, yedges = np.histogram2d(x, y, bins=bins, range=range,
-                                           normed=normed, weights=weights)
+                                           normed=density, weights=weights)
 
         if cmin is not None:
             h[h < cmin] = None
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2631,12 +2631,12 @@ def hist(
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @_autogen_docstring(Axes.hist2d)
 def hist2d(
-        x, y, bins=10, range=None, normed=False, weights=None,
+        x, y, bins=10, range=None, density=False, weights=None,
         cmin=None, cmax=None, *, data=None, **kwargs):
     __ret = gca().hist2d(
-        x, y, bins=bins, range=range, normed=normed, weights=weights,
-        cmin=cmin, cmax=cmax, **({"data": data} if data is not None
-        else {}), **kwargs)
+        x, y, bins=bins, range=range, density=density,
+        weights=weights, cmin=cmin, cmax=cmax, **({"data": data} if
+        data is not None else {}), **kwargs)
     sci(__ret[-1])
     return __ret
 
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -1977,15 +1977,16 @@ class Annotation(Text, _AnnotationBase):
     def __str__(self):
         return "Annotation(%g, %g, %r)" % (self.xy[0], self.xy[1], self._text)
 
-    def __init__(self, s, xy,
+    @cbook._rename_parameter("3.1", "s", "text")
+    def __init__(self, text, xy,
                  xytext=None,
                  xycoords='data',
                  textcoords=None,
                  arrowprops=None,
                  annotation_clip=None,
                  **kwargs):
         """
-        Annotate the point *xy* with text *s*.
+        Annotate the point *xy* with text *text*.
 
         In the simplest form, the text is placed at *xy*.
 
@@ -1995,8 +1996,9 @@ def __init__(self, s, xy,
 
         Parameters
         ----------
-        s : str
-            The text of the annotation.
+        text : str
+            The text of the annotation.  *s* is a deprecated synonym for this
+            parameter.
 
         xy : (float, float)
             The point *(x,y)* to annotate.
@@ -2171,7 +2173,7 @@ def transform(renderer) -> Transform
             xytext = self.xy
         x, y = xytext
 
-        Text.__init__(self, x, y, s, **kwargs)
+        Text.__init__(self, x, y, text, **kwargs)
 
         self.arrowprops = arrowprops
 
