Bump version 1.8.1 (with deprecation cleanup and a bug fix)

* chg: Deprecation util cleaned up and expanded a bit. More forgiving of unexpected inputs.

* fix: Bug in v1.8.0 deprecation util - deepcopy inadvertently replacing things like default_authenticator

* Bump version: 1.8.0 → 1.8.1

Author: RookieRick

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.8.0
+current_version = 1.8.1
 commit = True
 tag = True
 

CHANGELOG.rst

@@ -2,6 +2,18 @@ Changelog
 =========
 
 
+v1.8.1 (2019-06-14)
+-------------------
+
+Changes
+~~~~~~~
+- Deprecation util cleaned up and expanded a bit. More forgiving of unexpected inputs. [Rick Riensche]
+
+Fix
+~~~
+- Bug in v1.8.0 deprecation util - deepcopy inadvertently replacing things like default_authenticator
+
+
 v1.8.0 (2019-06-12)
 -------------------
 

flask_rebar/utils/deprecation.py

@@ -8,9 +8,9 @@
     :license: MIT, see LICENSE for details.
 """
 
-import copy
 import functools
 import warnings
+from collections import namedtuple
 
 from werkzeug.local import LocalProxy as module_property  # noqa
 
@@ -55,21 +55,19 @@ def deprecated(new_func=None, eol_version=None):
     :param Union[str, (str, str)] new_func: Name (or name and end-of-life version) of replacement
     :param str eol_version: Version in which this function may no longer work
     :return:
+    Raise a deprecation warning for decorated function.
+    Tuple is supported for new_func just in case somebody infers it as an option based on the way we
+    deprecate params..
+    If tuple form is used for new_func AND eol_version is provided, eol_version will trump whatever is
+    found in the tuple; caveat emptor
     """
 
     def decorator(f):
         @functools.wraps(f)
         def wrapper(*args, **kwargs):
-            new = None
-            eol = eol_version
-            if (
-                type(new_func) is tuple
-            ):  # in case somebody inferred this from the way we deprecate params..
-                new = str(new_func[0])
-                eol = str(new_func[1])
-            elif new_func:
-                new = str(new_func)
-            _deprecation_warning(f.__name__, new, eol)
+            new, eol = _validated_deprecation_spec(new_func)
+            eol = eol_version or eol
+            _deprecation_warning(f.__name__, new, eol, stacklevel=3)
             return f(*args, **kwargs)
 
         return wrapper
@@ -96,35 +94,54 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
+def _validated_deprecation_spec(spec):
+    """
+    :param Union[new_name, (new_name, eol_version)] spec:  new name and/or expected end-of-life version
+    :return: (str new_name, str eol_version), normalized to tuple and sanitized to deal with malformed inputs
+    Parse a deprecation spec (string or tuple) to a standardized namedtuple form.
+    If spec is provided as a bare value (presumably string), we'll treat as new name with no end-of-life version
+    If spec is provided (likely on accident) as a 1-element tuple, we'll treat same as a bare value
+    If spec is provided as a tuple with more than 2 elements, we'll simply ignore the extraneous
+    """
+    new_name = None
+    eol_version = None
+    if type(spec) is tuple:
+        if len(spec) > 0:
+            new_name = str(spec[0]) if spec[0] else None
+        if len(spec) > 1:
+            eol_version = str(spec[1]) if spec[1] else None
+    elif spec:
+        new_name = str(spec)
+    validated = namedtuple("deprecation_spec", ["new_name", "eol_version"])(
+        new_name, eol_version
+    )
+    return validated
+
+
 def _remap_kwargs(func_name, kwargs, aliases):
     """
     Adapted from https://stackoverflow.com/a/49802489/977046
     """
-    remapped_args = copy.deepcopy(kwargs)
+    remapped_args = dict(kwargs)
     for alias, new_spec in aliases.items():
         if alias in remapped_args:
-            eol_version = None
-            if type(new_spec) is tuple:
-                new = str(new_spec[0])
-                if len(new_spec) >= 2:
-                    eol_version = str(new_spec[1]) if new_spec[1] else None
-            else:
-                new = str(new_spec)
+            new, eol_version = _validated_deprecation_spec(new_spec)
             if new in remapped_args:
                 raise TypeError(
                     "{} received both {} and {}".format(func_name, alias, new)
                 )
             else:
-                _deprecation_warning(alias, new, eol_version)
-                remapped_args[new] = remapped_args.pop(alias)
+                _deprecation_warning(alias, new, eol_version, stacklevel=4)
+                if new:
+                    remapped_args[new] = remapped_args.pop(alias)
 
     return remapped_args
 
 
-def _deprecation_warning(old_name, new_name, eol_version):
+def _deprecation_warning(old_name, new_name, eol_version, stacklevel=1):
     eol_clause = (
         " and may be removed in version {}".format(eol_version) if eol_version else ""
     )
     replacement_clause = "; use {}".format(new_name) if new_name else ""
     msg = "{} is deprecated{}{}".format(old_name, eol_clause, replacement_clause)
-    warnings.warn(msg, config.warning_type)
+    warnings.warn(message=msg, category=config.warning_type, stacklevel=stacklevel)

setup.py

@@ -5,7 +5,7 @@
 if __name__ == "__main__":
     setup(
         name="flask-rebar",
-        version="1.8.0",
+        version="1.8.1",
         author="Barak Alon",
         author_email="[email protected]",
         description="Flask-Rebar combines flask, marshmallow, and swagger for robust REST services.",

tests/test_deprecation_utils.py

@@ -14,13 +14,35 @@
 
 
 @deprecated_parameters(
-    old_param1="new_param1",
-    old_param2=("new_param2", "v99"),
-    old_param3=("new_param3",),
-    old_param4=("new_param4", None),
+    old_param1="new_param1",  # rename with no predicted end-of-life version
+    old_param2=("new_param2", "v99"),  # rename with predicted end-of-life version
+    old_param3=("new_param3",),  # rename with a poorly formed tuple
+    old_param4=("new_param4", None),  # rename with explicitly None end-of-life version
+    old_param5=(None, "v99.5"),  # no rename with explicit end-of-life version
+    old_param6=None,  # deprecated param with no replacement, no specific end-of-life-version
+    old_param7=(None, None),  # same as 6, but for the truly pedantic
+    old_param8=(),  # could imagine someone accidentally doing this.. :P
 )
-def _add(new_param1=0, new_param2=0, new_param3=0, new_param4=0):
-    return new_param1 + new_param2 + new_param3 + new_param4
+def _add(
+    new_param1=0,
+    new_param2=0,
+    new_param3=0,
+    new_param4=0,
+    old_param5=0,
+    old_param6=0,
+    old_param7=0,
+    old_param8=0,
+):
+    return (
+        new_param1
+        + new_param2
+        + new_param3
+        + new_param4
+        + old_param5
+        + old_param6
+        + old_param7
+        + old_param8
+    )
 
 
 @deprecated()
@@ -103,6 +125,42 @@ def test_parameter_deprecation_warnings(self):
             )
             self.assertIs(w[0].category, FutureWarning)
 
+        # with no replacement but specific expiration
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            result = _add(new_param1=1, old_param5=5)
+            self.assertEqual(result, 6)
+            self.assertEqual(len(w), 1)
+            msg = str(w[0].message)
+            self.assertIn("old_param5 is deprecated", msg)
+            self.assertIn("v99.5", msg)
+            self.assertNotIn("new_param", msg)
+            self.assertIs(w[0].category, FutureWarning)
+
+        # with no replacement (specified as None)
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            result = _add(new_param1=1, old_param5=5)
+            self.assertEqual(result, 6)
+            self.assertEqual(len(w), 1)
+            msg = str(w[0].message)
+            self.assertIn("old_param5 is deprecated", msg)
+            self.assertIn("v99.5", msg)
+            self.assertNotIn("new_param", msg)
+            self.assertIs(w[0].category, FutureWarning)
+
+        # with no replacement -- specified as explicit (None, None) and implicit ()
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            result = _add(old_param7=7, old_param8=8)
+            self.assertEqual(result, 15)
+            self.assertEqual(len(w), 2)
+            msgs = {str(w[0].message), str(w[1].message)}
+            expected_msgs = {"old_param7 is deprecated", "old_param8 is deprecated"}
+            self.assertEqual(expected_msgs, msgs)
+            self.assertIn("v99.5", msg)
+            self.assertNotIn("new_param", msg)
+
     def test_parameter_deprecation_warning_type(self):
         """Deprecation supports specifying type of warning"""
         deprecation_config.warning_type = DeprecationWarning