Add decorator for deprecated classes

Author: vishal-bala

redisvl/utils/utils.py

@@ -173,6 +173,46 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
+def deprecated_class(name: Optional[str] = None, replacement: Optional[str] = None):
+    """
+    Decorator to mark a class as deprecated.
+
+    When the decorated class is instantiated, the decorator will emit a
+    deprecation warning.
+
+    Args:
+        name: Optional custom name for the class in the warning message.
+              If not provided, uses the class's __name__.
+        replacement: Optional message describing what to use instead.
+
+    Example:
+        @deprecated_class(replacement="Use NewClass instead.")
+        class OldClass:
+            pass
+    """
+
+    def decorator(cls):
+        class_name = name or cls.__name__
+        warning_message = (
+            f"Class {class_name} is deprecated and will be "
+            "removed in the next major release. "
+        )
+        if replacement:
+            warning_message += replacement
+
+        original_init = cls.__init__
+
+        @wraps(original_init)
+        def new_init(self, *args, **kwargs):
+            warn(warning_message, category=DeprecationWarning, stacklevel=2)
+            original_init(self, *args, **kwargs)
+
+        cls.__init__ = new_init
+        return cls
+
+    return decorator
+
+
 def sync_wrapper(fn: Callable[[], Coroutine[Any, Any, Any]]) -> Callable[[], None]:
     def wrapper():
         # Check if the interpreter is shutting down

tests/unit/test_utils.py

@@ -16,6 +16,7 @@
     assert_no_warnings,
     denorm_cosine_distance,
     deprecated_argument,
+    deprecated_class,
     deprecated_function,
     lazy_import,
     norm_cosine_distance,
@@ -534,6 +535,94 @@ def test_logging_configuration_not_overridden(self):
         ), f"Date format changed: was present before: {has_date_pre}, present after: {has_date_post}"
 
 
+class TestDeprecatedClass:
+    def test_deprecated_class_warning_with_replacement(self):
+        @deprecated_class(replacement="Use NewClass instead.")
+        class OldClass:
+            def __init__(self, value):
+                self.value = value
+
+        with pytest.warns(DeprecationWarning) as record:
+            obj = OldClass(42)
+
+        assert len(record) == 1
+        assert str(record[0].message) == (
+            "Class OldClass is deprecated and will be removed in the next major release. "
+            "Use NewClass instead."
+        )
+        assert obj.value == 42
+
+    def test_deprecated_class_warning_without_replacement(self):
+        @deprecated_class()
+        class OldClass:
+            def __init__(self, value):
+                self.value = value
+
+        with pytest.warns(DeprecationWarning) as record:
+            obj = OldClass(42)
+
+        assert len(record) == 1
+        assert str(record[0].message) == (
+            "Class OldClass is deprecated and will be removed in the next major release. "
+        )
+        assert obj.value == 42
+
+    def test_deprecated_class_with_custom_name(self):
+        @deprecated_class(name="CustomOldClass", replacement="Use NewClass instead.")
+        class OldClass:
+            pass
+
+        with pytest.warns(DeprecationWarning) as record:
+            OldClass()
+
+        assert len(record) == 1
+        assert str(record[0].message) == (
+            "Class CustomOldClass is deprecated and will be removed in the next major release. "
+            "Use NewClass instead."
+        )
+
+    def test_deprecated_class_preserves_functionality(self):
+        @deprecated_class(replacement="Use NewClass instead.")
+        class OldClass:
+            def __init__(self, x, y):
+                self.x = x
+                self.y = y
+
+            def add(self):
+                return self.x + self.y
+
+        with pytest.warns(DeprecationWarning):
+            obj = OldClass(10, 20)
+
+        assert obj.x == 10
+        assert obj.y == 20
+        assert obj.add() == 30
+
+    def test_deprecated_class_with_inheritance(self):
+        @deprecated_class(replacement="Use NewBase instead.")
+        class OldBase:
+            def __init__(self, value):
+                self.value = value
+
+        class Derived(OldBase):
+            def __init__(self, value, extra):
+                super().__init__(value)
+                self.extra = extra
+
+        # Creating an instance of the deprecated base class should warn
+        with pytest.warns(DeprecationWarning):
+            base_obj = OldBase(42)
+
+        # Creating an instance of the derived class should also warn
+        # because it calls the deprecated __init__
+        with pytest.warns(DeprecationWarning):
+            derived_obj = Derived(42, "extra")
+
+        assert base_obj.value == 42
+        assert derived_obj.value == 42
+        assert derived_obj.extra == "extra"
+
+
 class TestLazyImport:
     def test_import_standard_library(self):
         """Test lazy importing of a standard library module"""