chore: Add decorator @deprecated and add it to is_str()

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,65 @@
+"""
+Utils for deprecating our code using warning.warn().
+The warning message is written to stderr when shown.
+
+For the difference between DeprecationWarning
+and PendingDeprecationWarning, refer to
+https://peps.python.org/pep-0565/#additional-use-case-for-futurewarning
+
+If external packages import deprecated/pending-deprecation
+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:
+    if replacement:
+        return f"{message}, please consider to use {replacement}"
+    return f"{message} and there is no replacement."
+
+
+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", 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
+
+
+def pending_deprecation(replacement: Optional[str]) -> Callable[[Callable[..., RT]], Callable[..., RT]]:
+    """
+    Mark a function/method as pending deprecation.
+
+    The warning is not shown by default in runtime.
+    """
+
+    def decorator(func: Callable[..., RT]) -> Callable[..., RT]:
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> RT:  # type: ignore
+            warning_message = _make_message(f"{func.__name__} will be deprecated", replacement)
+            # Setting stacklevel=2 to let Python print the line that calls
+            # this wrapper, not the line below.
+            warnings.warn(warning_message, PendingDeprecationWarning, 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,39 @@
+import warnings
+from unittest import TestCase
+
+from samtranslator.internal.deprecation_control import deprecated, pending_deprecation
+
+
+def replacement_function(x, y):
+    return x + y
+
+
+@deprecated(replacement="replacement_function")
+def deprecated_function(x, y):
+    return x + y
+
+
+@pending_deprecation(replacement="replacement_function")
+def pending_deprecation_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, please consider to use replacement_function", str(w[-1].message)
+            )
+
+    def test_pending_deprecation_decorator(self):
+        with warnings.catch_warnings(record=True) as w:
+            pending_deprecation_function(1, 1)
+            self.assertEqual(len(w), 1)
+            self.assertTrue(issubclass(w[-1].category, PendingDeprecationWarning))
+            self.assertIn(
+                "pending_deprecation_function will be deprecated, please consider to use replacement_function",
+                str(w[-1].message),
+            )