[EHN] New decorator deprecated_kwargs (#1103)

* lint importing

* [EHN] New decorator `deprecated_kwargs`

* Test `deprecated_kwargs`

* Update CHANGELOG.md

* lint codes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add return section

* lint codes

* Adjust the sequence of section

* Revert "lint codes"

This reverts commit 710c70a.

* Test normal case

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Apply suggestions from code review

Co-authored-by: Jeremy Goh <[email protected]>

* Drop duplicated `"`

* Update example in docstring

* Correct variable name

* Title more clearer names

* Rename function names

* Test `message`

* Fix testsuits

* [EHN] New option `error` to raise error or warning

* Lint importing

* Ignore DAR402

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Ma <[email protected]>
Co-authored-by: Jeremy Goh <[email protected]>

Author: 4 people

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 -   [DOC] Updated developer guide docs.
 -   [ENH] Allow column selection/renaming within conditional_join. #1102 @samukweku.
+-   [EHN] New decorator `deprecated_kwargs` for breaking API. #1103 @Zeroto521
 
 ## [v0.23.1] - 2022-05-03
 

janitor/utils.py

@@ -1,16 +1,11 @@
 """Miscellaneous internal PyJanitor helper functions."""
 
-import functools
 import os
 import socket
 import sys
-import warnings
-from typing import (
-    Callable,
-    Dict,
-    Iterable,
-    Union,
-)
+from warnings import warn
+from functools import singledispatch, wraps
+from typing import Callable, Dict, Iterable, Union
 
 import numpy as np
 import pandas as pd
@@ -46,7 +41,7 @@ def check(varname: str, value, expected_types: list):
         raise TypeError(f"{varname} should be one of {expected_types}.")
 
 
-@functools.singledispatch
+@singledispatch
 def _expand_grid(value, grid_index, key):
     """
     Base function for dispatch of `_expand_grid`.
@@ -231,6 +226,59 @@ def idempotent(func: Callable, df: pd.DataFrame, *args, **kwargs):
         )
 
 
+def deprecated_kwargs(
+    *arguments: list[str],
+    message: str = (
+        "The keyword argument '{argument}' of '{func_name}' is deprecated."
+    ),
+    error: bool = True,
+) -> Callable:
+    """
+    Used as a decorator when deprecating function's keyword arguments.
+
+    Example:
+
+    ```python
+    from janitor.utils import deprecated_kwargs
+
+    @deprecated_kwargs('x', 'y')
+    def plus(a, b, x=0, y=0):
+        return a + b
+    ```
+
+    :param arguments: The list of deprecated keyword arguments.
+    :param message: The message of `ValueError` or `DeprecationWarning`.
+        It should be a string or a string template. If a string template
+        defaults input `func_name` and `argument`.
+    :param error: If True raises `ValueError` else returns
+        `DeprecationWarning`.
+    :return: The original function wrapped with the deprecated `kwargs`
+        checking function.
+    :raises ValueError: If one of `arguments` is in the decorated function's
+        keyword arguments.  # noqa: DAR402
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            for argument in arguments:
+                if argument in kwargs:
+                    msg = message.format(
+                        func_name=func.__name__,
+                        argument=argument,
+                    )
+                    if error:
+                        raise ValueError(msg)
+                    else:
+                        warn(msg, DeprecationWarning)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
 def deprecated_alias(**aliases) -> Callable:
     """
     Used as a decorator when deprecating old function argument names, while
@@ -252,7 +300,7 @@ def simple_sum(alpha, beta):
     """  # noqa: E501
 
     def decorator(func):
-        @functools.wraps(func)
+        @wraps(func)
         def wrapper(*args, **kwargs):
             rename_kwargs(func.__name__, kwargs, aliases)
             return func(*args, **kwargs)
@@ -287,7 +335,7 @@ def simple_sum(alpha, beta):
 
     def decorator(func):
         def emit_warning(*args, **kwargs):
-            warnings.warn(message, FutureWarning)
+            warn(message, FutureWarning)
             return func(*args, **kwargs)
 
         return emit_warning
@@ -315,7 +363,7 @@ def rename_kwargs(func_name: str, kwargs: Dict, aliases: Dict):
                 raise TypeError(
                     f"{func_name} received both {old_alias} and {new_alias}"
                 )
-            warnings.warn(
+            warn(
                 f"{old_alias} is deprecated; use {new_alias}",
                 DeprecationWarning,
             )
@@ -449,7 +497,7 @@ def is_connected(url: str) -> bool:
             return True
     except OSError as e:
 
-        warnings.warn(
+        warn(
             "There was an issue connecting to the internet. "
             "Please see original error below."
         )

tests/utils/test_deprecated_kwargs.py

@@ -0,0 +1,99 @@
+import pytest
+
+from janitor.utils import deprecated_kwargs
+
+
+@pytest.mark.utils
+@pytest.mark.parametrize(
+    "arguments, message, func_kwargs, msg_expected",
+    [
+        (
+            ["a"],
+            "The keyword argument '{argument}' of '{func_name}' is deprecated",
+            dict(a=1),
+            "The keyword argument 'a' of 'simple_sum' is deprecated",
+        ),
+        (
+            ["b"],
+            "The keyword argument '{argument}' of '{func_name}' is deprecated",
+            dict(b=2),
+            "The keyword argument 'b' of 'simple_sum' is deprecated",
+        ),
+        (
+            ["a", "b"],
+            "The option '{argument}' of '{func_name}' is deprecated.",
+            dict(a=1, b=2),
+            "The option 'a' of 'simple_sum' is deprecated.",
+        ),
+        (
+            ["b", "a"],
+            "The keyword of function is deprecated.",
+            dict(a=1, b=2),
+            "The keyword of function is deprecated.",
+        ),
+    ],
+)
+def test_error(arguments, message, func_kwargs, msg_expected):
+    @deprecated_kwargs(*arguments, message=message)
+    def simple_sum(alpha, beta, a=0, b=0):
+        return alpha + beta
+
+    with pytest.raises(ValueError, match=msg_expected):
+        simple_sum(1, 2, **func_kwargs)
+
+
+@pytest.mark.utils
+@pytest.mark.parametrize(
+    "arguments, message, func_kwargs, msg_expected",
+    [
+        (
+            ["a"],
+            "The keyword argument '{argument}' of '{func_name}' is deprecated",
+            dict(a=1),
+            "The keyword argument 'a' of 'simple_sum' is deprecated",
+        ),
+        (
+            ["b"],
+            "The keyword argument '{argument}' of '{func_name}' is deprecated",
+            dict(b=2),
+            "The keyword argument 'b' of 'simple_sum' is deprecated",
+        ),
+        (
+            ["a", "b"],
+            "The option '{argument}' of '{func_name}' is deprecated.",
+            dict(a=1, b=2),
+            "The option 'a' of 'simple_sum' is deprecated.",
+        ),
+        (
+            ["b", "a"],
+            "The keyword of function is deprecated.",
+            dict(a=1, b=2),
+            "The keyword of function is deprecated.",
+        ),
+    ],
+)
+def test_warning(arguments, message, func_kwargs, msg_expected):
+    @deprecated_kwargs(*arguments, message=message, error=False)
+    def simple_sum(alpha, beta, a=0, b=0):
+        return alpha + beta
+
+    with pytest.warns(DeprecationWarning, match=msg_expected):
+        simple_sum(1, 2, **func_kwargs)
+
+
+@pytest.mark.utils
+@pytest.mark.parametrize(
+    "arguments, func_args, expected",
+    [
+        (["a"], [0, 0], 0),
+        (["b"], [1, 1], 2),
+        (["a", "b"], [0, 1], 1),
+        (["b", "a"], [0, 1], 1),
+    ],
+)
+def test_without_error(arguments, func_args, expected):
+    @deprecated_kwargs(*arguments)
+    def simple_sum(alpha, beta, a=0, b=0):
+        return alpha + beta
+
+    assert simple_sum(*func_args) == expected