Add the deprecate_parameter decorator to deprecate parameters

Author: seisman

pygmt/helpers/__init__.py

@@ -1,7 +1,12 @@
 """
 Functions, classes, decorators, and context managers to help wrap GMT modules.
 """
-from pygmt.helpers.decorators import fmt_docstring, kwargs_to_strings, use_alias
+from pygmt.helpers.decorators import (
+    deprecate_parameter,
+    fmt_docstring,
+    kwargs_to_strings,
+    use_alias,
+)
 from pygmt.helpers.tempfile import GMTTempFile, unique_name
 from pygmt.helpers.utils import (
     args_in_kwargs,

pygmt/helpers/decorators.py

@@ -7,6 +7,7 @@
 """
 import functools
 import textwrap
+import warnings
 
 import numpy as np
 from pygmt.exceptions import GMTInvalidInput
@@ -469,3 +470,65 @@ def remove_bools(kwargs):
         else:
             new_kwargs[arg] = value
     return new_kwargs
+
+
+def deprecate_parameter(oldname, newname, deprecate_version, remove_version):
+    """
+    Decorator to deprecate a parameter.
+
+    Parameters
+    ----------
+    oldname : str
+        The old, deprecated parameter name.
+    newname : str
+        The new parameter name.
+    deprecate_version : str
+        The PyGMT version when the old parameter starts to be deprecated.
+    remove_version : str
+        The PyGMT version when the old parameter will be fully removed.
+
+    Examples
+    --------
+
+    >>> @deprecate_parameter("sizes", "size", "v0.0.0", "v9.9.9")
+    ... @deprecate_parameter("colors", "color", "v0.0.0", "v9.9.9")
+    ... def module(size=0, **kwargs):
+    ...     "A module that prints the arguments it received"
+    ...     print(f"size={size}, color={kwargs['color']}")
+    >>> # new names are supported
+    >>> module(size=5.0, color="red")
+    size=5.0, color=red
+    >>> # old names are supported
+    >>> module(sizes=5.0, colors="red")
+    size=5.0, color=red
+    """
+
+    def deprecator(module_func):
+        """
+        The decorator that creates our new function to work with both old and
+        new parameters.
+        """
+
+        @functools.wraps(module_func)
+        def new_module(*args, **kwargs):
+            """
+            New module instance that converts old parameters to new parameters.
+            """
+            if oldname in kwargs:
+                if newname in kwargs:
+                    raise GMTInvalidInput(
+                        f"Can't provide both '{newname}' and '{oldname}'"
+                    )
+                msg = (
+                    f"'{oldname}' is deprecated since {deprecate_version} and will"
+                    f" be removed in {remove_version}; use '{newname}' instead."
+                )
+                warnings.simplefilter("always", DeprecationWarning)  # turn off filter
+                warnings.warn(msg, DeprecationWarning, 2)
+                warnings.simplefilter("default", DeprecationWarning)  # reset filter
+                kwargs[newname] = kwargs.pop(oldname)
+            return module_func(*args, **kwargs)
+
+        return new_module
+
+    return deprecator

pygmt/src/plot.py

@@ -6,6 +6,7 @@
 from pygmt.helpers import (
     build_arg_string,
     data_kind,
+    deprecate_parameter,
     fmt_docstring,
     is_nonstr_iter,
     kwargs_to_strings,
@@ -43,7 +44,8 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
+@deprecate_parameter("sizes", "size", "v0.4.0", "v0.6.0")
+def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
     r"""
     Plot lines, polygons, and symbols in 2-D.
 
@@ -78,7 +80,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         Either a data file name or a 2d numpy array with the tabular data.
         Use parameter ``columns`` to choose which columns are x, y, color,
         and size, respectively.
-    sizes : 1d array
+    size : 1d array
         The sizes of the data points in units specified using ``style``.
         Only valid if using ``x``/``y``.
     direction : list of two 1d arrays
@@ -215,12 +217,12 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
             )
         extra_arrays.append(kwargs["G"])
         del kwargs["G"]
-    if sizes is not None:
+    if size is not None:
         if kind != "vectors":
             raise GMTInvalidInput(
-                "Can't use arrays for sizes if data is matrix or file."
+                "Can't use arrays for size if data is matrix or file."
             )
-        extra_arrays.append(sizes)
+        extra_arrays.append(size)
 
     for flag in ["I", "t"]:
         if flag in kwargs and is_nonstr_iter(kwargs[flag]):