Provide deprecation warnings to the user.

hexrd/deprecation.py

@@ -0,0 +1,36 @@
+import os
+import functools
+
+
+class DeprecatedFunctionError(Exception):
+    """Custom exception for deprecated functions."""
+
+    pass
+
+
+def deprecated(new_func=None):
+    """
+    Decorator to mark functions as deprecated. Raises an error if
+    the 'ACK_DEPRECATED' environment variable is not set. Alerts the
+    user to the replacement function if provided.
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if new_func:
+                new_func_path = f"{new_func.__module__}.{new_func.__name__}"
+                print(
+                    f"Warning: {func.__name__} is deprecated and is marked for removal. "
+                    f"Please use {new_func_path} instead."
+                )
+            if os.getenv('ACK_DEPRECATED') != 'true':
+                raise DeprecatedFunctionError(
+                    f"Function {func.__name__} is deprecated. "
+                    "Set the environment variable 'ACK_DEPRECATED' to 'true' to acknowledge."
+                )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

hexrd/xrdutil/utils.py

@@ -46,6 +46,9 @@
 
 from hexrd import distortion as distortion_pkg
 
+from hexrd.deprecation import deprecated
+from hexrd.instrument.hedm_instrument import HEDMInstrument
+
 
 # =============================================================================
 # PARAMETERS
@@ -366,7 +369,7 @@ def validateAngleRanges(
     return reflInRange
 
 
-# TODO: Deprecate this function
+@deprecated
 def simulateOmeEtaMaps(
     omeEdges,
     etaEdges,
@@ -1137,7 +1140,7 @@ def simulateGVecs(
     return valid_ids, valid_hkl, valid_ang, valid_xy, ang_ps
 
 
-# TODO: Deprecate this function
+@deprecated(new_func=HEDMInstrument.simulate_laue_pattern)
 def simulateLauePattern(
     hkls,
     bMat,