update deprecator to exactly match 3.13 deprecated decorator

Author: cadenmyers13

src/diffpy/utils/_deprecator.py

@@ -10,79 +10,40 @@
     _builtin_deprecated = None
 
 
-def deprecated(*, alt_name=None, message=None):
-    """Marks a function or class as deprecated.
+def deprecated(message, *, category=DeprecationWarning, stacklevel=1):
+    """Compatibility wrapper for Python <3.13.
 
-    Emits a DeprecationWarning whenever the decorated function is called
-    or the decorated class is instantiated.
-
-    Parameters
-    ----------
-    alt_name : str, optional
-        Name of the recommended alternative.
-    message : str, optional
-        Custom deprecation message. If None, a default message is generated.
-
-    Returns
-    -------
-    decorator : function
-        Decorator that wraps the deprecated object.
-
-    Examples
-    --------
-    .. code-block:: python
-
-        from diffpy._deprecations import deprecated
-
-        # ------------------------------
-        # Deprecated function
-        # ------------------------------
-        @deprecated(alt_name="new_function")
-        def old_function(x, y):
-            return x + y
-
-        def new_function(x, y):
-            return x + y
-
-        # Usage
-        old_function(1, 2)  # Emits DeprecationWarning
-        new_function(1, 2)  # No warning
-
-        # ------------------------------
-        # Deprecated class
-        # ------------------------------
-        @deprecated(alt_name="NewAtom")
-        class OldAtom:
-            def __init__(self, symbol):
-                self.symbol = symbol
-
-        # Usage
-        a = OldAtom("C")  # Emits DeprecationWarning
-        atom = NewAtom("C")  # No warning
+    Matches the Python 3.13 warnings.deprecated API exactly.
     """
-    if _builtin_deprecated:
-        return _builtin_deprecated
+    # If Python 3.13 implementation exists, delegate to it
+    if _builtin_deprecated is not None:
+        return _builtin_deprecated(
+            message, category=category, stacklevel=stacklevel
+        )
 
-    def decorator(obj):
-        name = getattr(obj, "__name__", repr(obj))
-        msg = message or (
-            f"'{name}' is deprecated. Use '{alt_name}' instead."
-            if alt_name
-            else f"'{name}' is deprecated."
+    # Validate message type like Python 3.13 does
+    if not isinstance(message, str):
+        raise TypeError(
+            f"Expected an object of type str for 'message', not "
+            f"{type(message).__name__!r}"
         )
 
+    def decorator(obj):
+        # Set __deprecated__ attribute (required by PEP 702)
+        setattr(obj, "__deprecated__", message)
+
+        # Must support functions AND classes
         if callable(obj):
 
             @functools.wraps(obj)
             def wrapper(*args, **kwargs):
-                warnings.warn(msg, DeprecationWarning, stacklevel=2)
+                warnings.warn(message, category, stacklevel=stacklevel + 1)
                 return obj(*args, **kwargs)
 
             return wrapper
-        else:
-            raise TypeError(
-                "deprecated decorator can only be applied to functions or "
-                "classes"
-            )
+
+        raise TypeError(
+            "deprecated decorator can only be applied to functions or classes"
+        )
 
     return decorator