show deprecation chaining

README.md

@@ -106,15 +106,15 @@ from deprecate import deprecated, void
   target=accuracy_score,
   # custom warning stream
   stream=logging.warning,
+  # number or warnings per lifetime (with -1 for always_
+  num_warns=5,
   # custom message template
   template_mgs="`%(source_name)s` was deprecated, use `%(target_path)s`",
-  # as target args are different, define mapping
+  # as target args are different, define mapping from source to target func
   args_mapping={'preds': 'y_pred', 'target': 'y_true', 'blabla': None}
 )
 def depr_accuracy(preds: list, target: list, blabla: float) -> float:
-    """
-    My deprecated function which is mapping to sklearn accuracy.
-    """
+    """My deprecated function which is mapping to sklearn accuracy."""
     # to stop complain your IDE about unused argument you can use void/empty function
     void(preds, target, blabla)
 
@@ -139,9 +139,7 @@ from deprecate import deprecated
 
 @deprecated(target=None, deprecated_in="0.1", remove_in="0.5")
 def my_sum(a: int, b: int = 5) -> int:
-    """
-    My deprecated function which still has to have implementation.
-    """
+    """My deprecated function which still has to have implementation."""
     return a + b
 
 # call this function will raise deprecation warning:
@@ -155,7 +153,7 @@ sample output:
 
 ### Self argument mapping
 
-We aso support deprecation and argument mapping for the function itself:
+We also support deprecation and argument mapping for the function itself:
 
 ```python
 from deprecate import deprecated
@@ -167,9 +165,7 @@ from deprecate import deprecated
   deprecated_in="0.2", remove_in="0.4",
 )
 def any_pow(base: float, coef: float = 0, new_coef: float = 0) -> float:
-    """
-    My deprecated function which is mapping to sklearn accuracy.
-    """
+    """My function with deprecated argument `coef` mapped to `new_coef`."""
     return base ** new_coef
 
 # call this function will raise deprecation warning:
@@ -182,6 +178,31 @@ sample output:
 8
 ```
 
+Eventually you can set multiple deprecation levels via chaining deprecation arguments as each could be deprecated in another version:
+
+```python
+from deprecate import deprecated
+
+@deprecated(
+  True, "0.3", "0.6", args_mapping=dict(c1='nc1'),
+  template_mgs="Depr: v%(deprecated_in)s rm v%(remove_in)s for args: %(argument_map)s."
+)
+@deprecated(
+  True, "0.4", "0.7", args_mapping=dict(nc1='nc2'),
+  template_mgs="Depr: v%(deprecated_in)s rm v%(remove_in)s for args: %(argument_map)s."
+)
+def any_pow(base, c1: float = 0, nc1: float = 0, nc2: float = 2) -> float:
+    return base**nc2
+
+# call this function will raise deprecation warning:
+#   DeprecationWarning('Depr: v0.3 rm v0.6 for args: `c1` -> `nc1`.')
+#   DeprecationWarning('Depr: v0.4 rm v0.7 for args: `nc1` -> `nc2`.')
+print(any_pow(2, 3))
+```
+sample output:
+```
+8
+```
 
 ### Class deprecation
 

tests/collection_deprecate.py

@@ -7,7 +7,8 @@
 from deprecate import deprecated, void
 from tests.collection_targets import base_pow_args, base_sum_kwargs
 
-_SHORT_MSG = "`%(source_name)s` >> `%(target_name)s` in v%(deprecated_in)s rm v%(remove_in)s."
+_SHORT_MSG_FUNC = "`%(source_name)s` >> `%(target_name)s` in v%(deprecated_in)s rm v%(remove_in)s."
+_SHORT_MSG_ARGS = "Depr: v%(deprecated_in)s rm v%(remove_in)s for args: %(argument_map)s."
 
 
 @deprecated(target=None, deprecated_in="0.2", remove_in="0.3")
@@ -45,7 +46,7 @@ def depr_sum_msg(a: int, b: int = 5) -> int:
     void(a, b)
 
 
-@deprecated(target=base_pow_args, deprecated_in="1.0", remove_in="1.3", template_mgs=_SHORT_MSG)
+@deprecated(target=base_pow_args, deprecated_in="1.0", remove_in="1.3", template_mgs=_SHORT_MSG_FUNC)
 def depr_pow_args(a: float, b: float) -> float:
     void(a, b)
 
@@ -86,4 +87,10 @@ def depr_pow_self(base: float, coef: float = 0, new_coef: float = 0) -> float:
     args_mapping=dict(c1='nc1', c2='nc2')
 )
 def depr_pow_self_double(base: float, c1: float = 0, c2: float = 0, nc1: float = 1, nc2: float = 2) -> float:
-    return base**(nc1 + nc2)
+    return base**(c1 + c2 + nc1 + nc2)
+
+
+@deprecated(True, "0.3", "0.6", args_mapping=dict(c1='nc1'), template_mgs=_SHORT_MSG_ARGS)
+@deprecated(True, "0.4", "0.7", args_mapping=dict(nc1='nc2'), template_mgs=_SHORT_MSG_ARGS)
+def depr_pow_self_twice(base: float, c1: float = 0, nc1: float = 0, nc2: float = 2) -> float:
+    return base**(c1 + nc1 + nc2)

tests/test_functions.py

@@ -12,6 +12,7 @@
     depr_pow_mix,
     depr_pow_self,
     depr_pow_self_double,
+    depr_pow_self_twice,
     depr_pow_wrong,
     depr_sum,
     depr_sum_calls_2,
@@ -30,6 +31,7 @@ def test_deprecated_func_warn_only() -> None:
 
 
 def test_deprecated_func_arguments() -> None:
+    """Test deprecation function arguments"""
     with no_warning_call():
         assert depr_pow_self(2, new_coef=3) == 8
 
@@ -52,7 +54,18 @@ def test_deprecated_func_arguments() -> None:
         assert depr_pow_self_double(2, c1=3, c2=4) == 128
 
 
+def test_deprecated_func_chain() -> None:
+    """Test chaining deprecation wrappers."""
+    with pytest.warns(DeprecationWarning) as warns:
+        assert depr_pow_self_twice(2, 3) == 8
+    assert len(warns) == 2
+
+    with no_warning_call():
+        assert depr_pow_self_twice(2, c1=3) == 8
+
+
 def test_deprecated_func_default() -> None:
+    """Testing some base/default configurations."""
     with pytest.deprecated_call(
         match='The `depr_sum` was deprecated since v0.1 in favor of `tests.collection_targets.base_sum_kwargs`.'
         ' It will be removed in v0.5.'
@@ -113,6 +126,7 @@ def test_deprecated_func_incomplete() -> None:
 
 
 def test_deprecated_func_mapping() -> None:
+    """Test mapping to external functions"""
     with pytest.deprecated_call():
         assert depr_accuracy_map([1, 0, 1, 2]) == 0.5