updated/generalized function deprecator - it now accepts an is_replaced warning

Author: Alexander Ororbia

ngcsimlib/_src/deprecators.py

@@ -1,17 +1,23 @@
 from ngcsimlib._src.logger import warn
 
 
-def deprecated(fn):
-    def _wrapped(*args, **kwargs):
-        warn(fn.__qualname__, "is deprecated")
-        return fn(*args, **kwargs)
-
-    _wrapped._is_deprecated = True
-    _wrapped._original = fn
-    return _wrapped
+def deprecated(replaced_by=None): ## function deprecating decorator
+    def decorator(fn):
+        def _wrapped(*args, **kwargs):
+            message = "is deprecated" ## <= default warning message
+            if replaced_by: ## make known substitute function name, if replaced_by != None
+                ## uses __name__ or string representation
+                new_name = getattr(replaced_by, '__name__', str(replaced_by))
+                message += f" (use {new_name} instead)"
+            warn(fn.__qualname__, message)
+            return fn(*args, **kwargs)
+        _wrapped._is_deprecated = True
+        _wrapped._original = fn 
+        return _wrapped
+    return decorator
 
 
-def deprecate_args(_rebind=True, **arg_list):
+def deprecate_args(_rebind=True, **arg_list): ## argument deprecating decorator
     def _deprecate_args(fn):
         def _wrapped(*args, **kwargs):
             for kwarg in list(kwargs.keys()):