cbook._rename_parameter.

anntzer · anntzer · commit 5c6b096df1e8 · 2019-01-27T19:52:18.000+01:00
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -32,7 +32,8 @@
 
 import matplotlib
 from .deprecation import (
-    mplDeprecation, deprecated, warn_deprecated, MatplotlibDeprecationWarning)
+    deprecated, warn_deprecated, _rename_parameter,
+    MatplotlibDeprecationWarning, mplDeprecation)
 
 
 @deprecated("3.0")
diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -258,3 +258,51 @@ def wrapper(*args, **kwargs):
         return finalize(wrapper, new_doc)
 
     return deprecate
+
+
+def _rename_parameter(since, old, new, func=None):
+    """
+    Decorator indicating that parameter *old* of *func* is renamed to *new*.
+
+    The actual implementation of *func* should use *new*, not *old*.  If *old*
+    is passed to *func*, a DeprecationWarning is emitted, and its value is
+    used, even if *new* is also passed by keyword (this is to simplify pyplot
+    wrapper functions, which always pass *new* explicitly to the Axes method).
+    If *new* is also passed but positionally, a TypeError will be raised by the
+    underlying function during argument binding.
+
+    Examples
+    --------
+
+    ::
+        @_rename_parameter("3.1", "bad_name", "good_name")
+        def func(good_name): ...
+    """
+
+    if func is None:
+        return functools.partial(_rename_parameter, since, old, new)
+
+    signature = inspect.signature(func)
+    assert old not in signature.parameters, (
+        f"Matplotlib internal error: {old!r} cannot be a parameter for "
+        "{func.__name__}()")
+    assert new in signature.parameters, (
+        f"Matplotlib internal error: {new!r} must be a parameter for "
+        "{func.__name__}()")
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        if old in kwargs:
+            warn_deprecated(
+                since, message=f"The {old!r} parameter of {func.__name__}() "
+                f"has been renamed {new!r} since {since}; support for the old "
+                f"name will be dropped %(removal)s.")
+            kwargs[new] = kwargs.pop(old)
+        return func(*args, **kwargs)
+
+    # wrapper() must keep the same documented signature as func(): if we
+    # instead made both *old* and *new* appear in wrapper()'s signature, they
+    # would both show up in the pyplot function for an Axes method as well and
+    # pyplot would explicitly pass both arguments to the Axes method.
+
+    return wrapper
