Merge pull request #2692 from devitocodes/JDBetteridge/devito_warnings

misc: Add custom warnings functionality

Author: mloubout

devito/__init__.py

@@ -27,6 +27,7 @@
 from devito.builtins import *  # noqa
 from devito.data.allocators import *  # noqa
 from devito.logger import error, warning, info, set_log_level  # noqa
+from devito.warnings import warn  # noqa
 from devito.mpi import MPI, CustomTopology  # noqa
 try:
     from devito.checkpointing import DevitoCheckpoint, CheckpointOperator  # noqa

devito/logger.py

@@ -22,6 +22,10 @@
 CRITICAL = logging.CRITICAL
 
 logging.addLevelName(PERF, "PERF")
+# Note: Do not use
+# logging.captureWarnings(True)
+# here as it will swallow all warnings (not just Devito warnings)
+# Instead use the `devito.warnings` module to log warnings
 
 logger_registry = {
     'DEBUG': DEBUG,

devito/warnings.py

@@ -0,0 +1,36 @@
+import warnings
+
+from devito.logger import warning as log_warning
+
+
+class DevitoWarning(Warning):
+    pass
+
+
+def warn(message, category=None, stacklevel=2, source=None):
+    """
+    `devito.warn` follows the Python call signature for `warning.warn`:
+    https://docs.python.org/3/library/warnings.html#warnings.warn
+
+    Parameters
+    ----------
+    message: str or Warning
+        Message to display
+    category: None or Warning
+        Leave as None to get a `DevitoWarning`
+    stacklevel: int
+        Set a custom stack level
+    source: None or object
+        the destroyed object which emitted a `ResourceWarning`
+    """
+    warning_type = None
+    if isinstance(message, Warning):
+        warning_type = message.__class__.__name__
+    elif category is not None:
+        warning_type = category.__name__
+
+    if warning_type is not None:
+        message = f'from {warning_type}: {str(message)}'
+
+    log_warning(message)
+    warnings.warn(message, category=DevitoWarning, stacklevel=stacklevel, source=source)

tests/test_warnings.py

@@ -0,0 +1,76 @@
+import pytest
+import warnings
+
+from devito.warnings import warn, DevitoWarning
+
+
+class NewWarning(UserWarning):
+    """
+    A custom warning class
+    """
+    pass
+
+
+@pytest.fixture
+def custom_warning():
+    # Instance of custom warning class
+    return NewWarning('** NEW ** A fun new kind of warning')
+
+
+class TestDevitoWarnings:
+    """
+    In all cases check that the `DevitoWarning` type of Warning is raised
+    __in all cases__, even if a custom type is provided
+    """
+    def test_raise(self):
+        with pytest.warns(DevitoWarning) as w:
+            warn('Let this be a warning to you')
+
+        assert len(w) == 1
+        assert 'DevitoWarning' in repr(w[0].message)
+        assert w[0].filename == __file__
+
+    def test_raise_from_user(self):
+        with pytest.warns(DevitoWarning) as w:
+            warn('Let this be another warning to you', UserWarning)
+
+        assert len(w) == 1
+        assert 'UserWarning:' in str(w[0].message)
+        assert w[0].filename == __file__
+
+    def test_raise_from_user_kw(self):
+        with pytest.warns(DevitoWarning) as w:
+            warn('Let this be another warning to you', category=UserWarning)
+
+        assert len(w) == 1
+        assert 'UserWarning:' in str(w[0].message)
+        assert w[0].filename == __file__
+
+    def test_raise_from_custom(self, custom_warning):
+        with pytest.warns(DevitoWarning) as w:
+            warn(custom_warning)
+
+        assert len(w) == 1
+        assert 'NewWarning:' in str(w[0].message)
+        assert w[0].filename == __file__
+
+
+class TestWarning:
+    """
+    Check that the custom DevitoWarning does not interfere with Python warnings
+    """
+    def test_raise(self):
+        with pytest.warns(UserWarning):
+            warnings.warn('Let this be a warning to you')
+
+    def test_raise_devito(self):
+        with pytest.warns(DevitoWarning):
+            warnings.warn('Let this be another warning to you', DevitoWarning)
+
+    def test_raise_devito_kw(self):
+        with pytest.warns(DevitoWarning):
+            warn('Let this be another warning to you', category=DevitoWarning)
+
+    def test_raise_from_custom(self, custom_warning):
+        with pytest.warns(NewWarning):
+            warnings.warn(custom_warning)