chore: Add decorator @deprecated and @pending_deprecation (#2889)

Author: aahung

samtranslator/internal/__init__.py

@@ -0,0 +1,6 @@
+"""
+The module for samtranslator internal implementations.
+
+External packages should not import anything from it
+as all interfaces are subject to change without warning.
+"""

samtranslator/internal/deprecation_control.py

@@ -0,0 +1,44 @@
+"""
+Utils for deprecating our code using warning.warn().
+The warning message is written to stderr when shown.
+
+For the difference between DeprecationWarning
+and other deprecation warning classes, refer to
+https://peps.python.org/pep-0565/#additional-use-case-for-futurewarning
+
+If external packages import deprecated interfaces,
+it is their responsibility to detect and remove them.
+"""
+import warnings
+from functools import wraps
+from typing import Callable, Optional, TypeVar
+
+RT = TypeVar("RT")  # return type
+
+
+def _make_message(message: str, replacement: Optional[str]) -> str:
+    return f"{message}, please use {replacement}" if replacement else message
+
+
+def deprecated(replacement: Optional[str]) -> Callable[[Callable[..., RT]], Callable[..., RT]]:
+    """
+    Mark a function/method as deprecated.
+
+    The warning is shown by default when triggered directly
+    by code in __main__.
+    """
+
+    def decorator(func: Callable[..., RT]) -> Callable[..., RT]:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> RT:  # type: ignore
+            warning_message = _make_message(
+                f"{func.__name__} is deprecated and will be removed in a future release", replacement
+            )
+            # Setting stacklevel=2 to let Python print the line that calls
+            # this wrapper, not the line below.
+            warnings.warn(warning_message, DeprecationWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

samtranslator/model/types.py

@@ -11,6 +11,7 @@
 from typing import Any, Callable, Type, Union
 
 import samtranslator.model.exceptions
+from samtranslator.internal.deprecation_control import deprecated
 
 # Validator always looks like def ...(value: Any, should_raise: bool = True) -> bool,
 # However, Python type hint doesn't support functions with optional keyword argument
@@ -137,6 +138,7 @@ def validate(value: Any, should_raise: bool = False) -> bool:
     return validate
 
 
+@deprecated(replacement="IS_STR")
 def is_str() -> Validator:
     """
     For compatibility reason, we need this `is_str()` as it

tests/internal/test_deprecation_control.py

@@ -0,0 +1,26 @@
+import warnings
+from unittest import TestCase
+
+from samtranslator.internal.deprecation_control import deprecated
+
+
+def replacement_function(x, y):
+    return x + y
+
+
+@deprecated(replacement="replacement_function")
+def deprecated_function(x, y):
+    return x + y
+
+
+class TestDeprecationControl(TestCase):
+    def test_deprecated_decorator(self):
+        with warnings.catch_warnings(record=True) as w:
+            deprecated_function(1, 1)
+            self.assertEqual(len(w), 1)
+            self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+            self.assertIn(
+                "deprecated_function is deprecated and will be removed in a future release, "
+                "please use replacement_function",
+                str(w[-1].message),
+            )