From 24c35369c944e69de5b29bb37ef8e3c58e7bc43a Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Fri, 24 Sep 2021 14:18:18 +0800 Subject: [PATCH 1/4] Add a decorator to raise a FutureWarning when positional arguments are passed for functions that changed parameter orders --- pygmt/helpers/decorators.py | 58 +++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index bf270d3455d..506d93107a9 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -811,3 +811,61 @@ def new_module(*args, **kwargs): return new_module return deprecator + + +def check_data_input_order(deprecate_version, remove_version): + """ + Decorator to raise a FutureWarning if the order of data input parameters + changes and positional arguments are passed. + + Parameters + ---------- + deprecate_version : str + The PyGMT version when the order of data input parameters is changed. + remove_version : str + The PyGMT version when the deprecation warning should be removed. + + Examples + -------- + >>> @check_data_input_order("v0.0.0", "v9.9.9") + ... def module(data=None, x=None, y=None, z=None, **kwargs): + ... "A module that prints the arguments it received" + ... print(f"data={data}, x={x}, y={y}, z={z}") + >>> module(data="table.txt") + data=table.txt, x=None, y=None, z=None + >>> module(x=0, y=1, z=2) + data=None, x=0, y=1, z=2 + >>> with warnings.catch_warnings(record=True) as w: + ... module(0, 1, 2) + ... assert len(w) == 1 + ... assert issubclass(w[0].category, FutureWarning) + ... + data=0, x=1, y=2, z=None + """ + + def data_input_order_checker(module_func): + """ + The decorator that creates the new function to check if positional + arguments are passed. + """ + + @functools.wraps(module_func) + def new_module(*args, **kwargs): + """ + New module instance that raises a warning if positional arguments + are passed. + """ + if len(args) != 0: # positional arguments are used + msg = ( + "The function parameters has been re-ordered as 'data, x, y, [z]' " + f"since {deprecate_version} but you're passing positional arguments. " + "You can silence the warning by passing keyword arguments " + "like 'x=x, y=y, z=z'. Otherwise, the warning will be removed " + f"in {remove_version}." + ) + warnings.warn(msg, category=FutureWarning, stacklevel=2) + return module_func(*args, **kwargs) + + return new_module + + return data_input_order_checker From 59e8858e2d8d237155401a858024f800d410f943 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 26 Sep 2021 18:33:32 +0800 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com> --- pygmt/helpers/decorators.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 506d93107a9..1af6a2baa58 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -817,6 +817,8 @@ def check_data_input_order(deprecate_version, remove_version): """ Decorator to raise a FutureWarning if the order of data input parameters changes and positional arguments are passed. + + The decorator is temporary and should be removed in v0.7.0. Parameters ---------- @@ -855,7 +857,7 @@ def new_module(*args, **kwargs): New module instance that raises a warning if positional arguments are passed. """ - if len(args) != 0: # positional arguments are used + if len(args) > 0: # positional arguments are used msg = ( "The function parameters has been re-ordered as 'data, x, y, [z]' " f"since {deprecate_version} but you're passing positional arguments. " From f134ed5d16f3871b06dd62fde6b336593f016ed4 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 26 Sep 2021 19:13:52 +0800 Subject: [PATCH 3/4] Fix style --- pygmt/helpers/decorators.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 1af6a2baa58..ce6fd0abd6b 100644 --- a/pygmt/helpers/decorators.py +++ b/pygmt/helpers/decorators.py @@ -817,7 +817,7 @@ def check_data_input_order(deprecate_version, remove_version): """ Decorator to raise a FutureWarning if the order of data input parameters changes and positional arguments are passed. - + The decorator is temporary and should be removed in v0.7.0. Parameters From a03c736dff452cd5c248754249163b3db9526ef5 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 26 Sep 2021 19:39:32 +0800 Subject: [PATCH 4/4] Add the decorator to __init__.py --- pygmt/helpers/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pygmt/helpers/__init__.py b/pygmt/helpers/__init__.py index 4b9c4051e80..b52f2c5022a 100644 --- a/pygmt/helpers/__init__.py +++ b/pygmt/helpers/__init__.py @@ -2,6 +2,7 @@ Functions, classes, decorators, and context managers to help wrap GMT modules. """ from pygmt.helpers.decorators import ( + check_data_input_order, deprecate_parameter, fmt_docstring, kwargs_to_strings,