ENH: Add function to schedule a warning to become an error

Author: effigies

nibabel/deprecated.py

@@ -1,7 +1,9 @@
 """Module to help with deprecating objects and classes
 """
+from __future__ import annotations
 
 import warnings
+from typing import Type
 
 from .deprecator import Deprecator
 from .pkg_info import cmp_pkg_version
@@ -77,3 +79,40 @@ class VisibleDeprecationWarning(UserWarning):
 
 
 deprecate_with_version = Deprecator(cmp_pkg_version)
+
+
+def alert_future_error(
+    msg: str,
+    version: str,
+    *,
+    warning_class: Type[Warning] = FutureWarning,
+    error_class: Type[Exception] = RuntimeError,
+    warning_rec: str = '',
+    error_rec: str = '',
+    stacklevel: int = 2,
+):
+    """Warn or error with appropriate messages for changing functionality.
+
+    Parameters
+    ----------
+    msg : str
+        Description of the condition that led to the alert
+    version : str
+        NiBabel version at which the warning will become an error
+    warning_class : subclass of Warning, optional
+        Warning class to emit before version
+    error_class : subclass of Exception, optional
+        Error class to emit after version
+    warning_rec : str, optional
+        Guidance for suppressing the warning and avoiding the future error
+    error_rec: str, optional
+        Guidance for resolving the error
+    stacklevel: int, optional
+        Warnings stacklevel to provide; note that this will be incremented by
+        1, so provide the stacklevel you would provide directly to warnings.warn()
+    """
+    if cmp_pkg_version(version) >= 0:
+        msg = f'{msg} This will error in NiBabel {version}. {warning_rec}'
+        warnings.warn(msg.strip(), warning_class, stacklevel=stacklevel + 1)
+    else:
+        raise error_class(f'{msg} {error_rec}'.strip())

nibabel/tests/test_deprecated.py

@@ -6,7 +6,12 @@
 import pytest
 
 from nibabel import pkg_info
-from nibabel.deprecated import FutureWarningMixin, ModuleProxy, deprecate_with_version
+from nibabel.deprecated import (
+    FutureWarningMixin,
+    ModuleProxy,
+    alert_future_error,
+    deprecate_with_version,
+)
 from nibabel.tests.test_deprecator import TestDeprecatorFunc as _TestDF
 
 
@@ -79,3 +84,28 @@ def func():
             assert func() == 99
     finally:
         pkg_info.cmp_pkg_version.__defaults__ = ('2.0',)
+
+
+def test_alert_future_error():
+    with pytest.warns(FutureWarning):
+        alert_future_error(
+            'Message',
+            '9999.9.9',
+            warning_rec='Silence this warning by doing XYZ.',
+            error_rec='Fix this issue by doing XYZ.',
+        )
+    with pytest.raises(RuntimeError):
+        alert_future_error(
+            'Message',
+            '1.0.0',
+            warning_rec='Silence this warning by doing XYZ.',
+            error_rec='Fix this issue by doing XYZ.',
+        )
+    with pytest.raises(ValueError):
+        alert_future_error(
+            'Message',
+            '1.0.0',
+            warning_rec='Silence this warning by doing XYZ.',
+            error_rec='Fix this issue by doing XYZ.',
+            error_class=ValueError,
+        )