feat: docstring generator function

Author: sbillinge

src/diffpy/utils/_deprecator.py

@@ -20,8 +20,7 @@ def deprecated(message, *, category=DeprecationWarning, stacklevel=1):
 
     .. code-block:: python
 
-        from diffpy._deprecations import deprecated
-        import warnings
+        from diffpy.utils._deprecator import deprecated, d
 
         @deprecated("old_function is deprecated; use new_function instead")
         def old_function(x, y):
@@ -38,12 +37,17 @@ def new_function(x, y):
 
     .. code-block:: python
 
-        from diffpy._deprecations import deprecated
+        from diffpy._deprecations import deprecated, deprecation_message
         import warnings
 
         warnings.simplefilter("always", DeprecationWarning)
 
-        @deprecated("OldAtom is deprecated; use NewAtom instead")
+        deprecation_warning = build_deprecation_message("diffpy.utils",
+                                                        "OldAtom",
+                                                        "NewAtom",
+                                                        "4.0.0")
+
+        @deprecated(deprecation_warning)
         class OldAtom:
             def __init__(self, symbol):
                 self.symbol = symbol
@@ -52,8 +56,8 @@ class NewAtom:
             def __init__(self, symbol):
                 self.symbol = symbol
 
-        a = OldAtom("C")     # Emits DeprecationWarning
-        b = NewAtom("C")     # No warning
+        a = OldAtom("C")     # Works but emits DeprecationWarning
+        b = NewAtom("C")     # Works with no warning
     """
     if _builtin_deprecated is not None:
         return _builtin_deprecated(
@@ -75,34 +79,78 @@ def wrapper(*args, **kwargs):
                 return obj(*args, **kwargs)
 
             return wrapper
-
         raise TypeError(
             "deprecated decorator can only be applied to functions or classes"
         )
 
     return decorator
 
 
-def deprecation_message(base, old_name, new_name, removal_version):
+def build_deprecation_message(
+    old_base, old_name, new_name, removal_version, new_base=None
+):
     """Generate a deprecation message.
 
     Parameters
     ----------
-    base : str
+    old_base : str
         The base module or class where the deprecated item resides.
+        This will look like the import statement used in the code
+        currently
     old_name : str
         The name of the deprecated item.
     new_name : str
         The name of the new item to use.
     removal_version : str
         The version when the deprecated item will be removed.
+    new_base : str Optional. Defaults to old_base.
+        The base module or class where the new item resides.
+        This will look like the import statement that
+        will be used in the code moving forward. If not specified,
+        the new base defaults to the old one.
 
     Returns
     -------
     str
         A formatted deprecation message.
     """
+    if new_base is None:
+        new_base = old_base
     return (
-        f"'{base}.{old_name}' is deprecated and will be removed in "
-        f"version {removal_version}. Please use '{base}.{new_name}' instead."
+        f"'{old_base}.{old_name}' is deprecated and will be removed in "
+        f"version {removal_version}. Please use '{new_base}.{new_name}' "
+        f"instead."
+    )
+
+
+def generate_deprecation_docstring(new_name, removal_version, new_base=None):
+    """Generate a docstring for copy-pasting into a deprecated function.
+
+    this function will print the text to the terminal for copy-pasting
+
+    usage:
+      python
+      >>> import diffpy.utils._deprecator.generate_deprecation_docstring as gdd
+      >>> gdd("new_name", "4.0.0")
+
+    Parameters
+    ----------
+    new_name: str
+        The name of the new function or class to replace the existing one
+    removal_version: str
+        The version when the deprecated item is targeted for removal,
+        e.g., 4.0.0
+    new_base: str Optional. Defaults to old_base.
+        The new base for importing.  The new import statement would look like
+        "from new_base import new_name"
+
+    Returns
+    -------
+    None
+    """
+    print(
+        f"This function has been deprecated and will be "
+        f"removed in version {removal_version}. Please use"
+        f"{new_base}.{new_name} instead."
     )
+    return