Merge pull request #61 from pyiron/fail

ImportAlarm: Expose _fail_on_warning and rename

Author: pmrv

pyiron_snippets/import_alarm.py

@@ -7,7 +7,7 @@
 
 
 class ImportAlarmError(ImportError):
-    """To be raised in addition to warning under test conditions"""
+    """To be raised instead of a warning when a package is missing."""
 
 
 class ImportAlarm:
@@ -45,19 +45,26 @@ class ImportAlarm:
     >>> import_alarm.warn_if_failed()
     """
 
-    def __init__(self, message=None, _fail_on_warning: bool = False):
+    def __init__(
+        self,
+        message=None,
+        raise_exception: bool = False,
+    ):
         """
         Initialize message value.
 
+        If a `raise_exception` is `True`, raise a :class:`.ImportAlarmError`, which is a subclass of `ImportError`.
+
         Args:
             message (str): What to say alongside your ImportError when the decorated
             function is called. (Default is None, which says nothing and raises no
             error.)
+            raise_exception (bool, optional): raise an exception instead of issuing a warning
         """
         self.message = message
         # Catching warnings in tests can be janky, so instead open a flag for failing
         # instead.
-        self._fail_on_warning = _fail_on_warning
+        self.raise_exception = raise_exception
 
     def __call__(self, func):
         return self.wrapper(func)
@@ -78,7 +85,7 @@ def warn_if_failed(self):
         """
         if self.message is not None:
             warnings.warn(self.message, category=ImportWarning, stacklevel=2)
-            if self._fail_on_warning:
+            if self.raise_exception:
                 raise ImportAlarmError(self.message)
 
     def __enter__(self):

tests/unit/test_import_alarm.py

@@ -6,13 +6,13 @@
 class TestImportAlarm(unittest.TestCase):
 
     def test_instance(self):
-        no_alarm = ImportAlarm(_fail_on_warning=True)
+        no_alarm = ImportAlarm(raise_exception=True)
 
         @no_alarm
         def add_one(x):
             return x + 1
 
-        yes_alarm = ImportAlarm("Here is a message", _fail_on_warning=True)
+        yes_alarm = ImportAlarm("Here is a message", raise_exception=True)
 
         @yes_alarm
         def subtract_one(x):
@@ -37,11 +37,11 @@ def subtract_one(x):
             subtract_one(0)
 
     def test_context(self):
-        with ImportAlarm("Working import", _fail_on_warning=True) as alarm_working:
+        with ImportAlarm("Working import", raise_exception=True) as alarm_working:
             # Suppose all the imports here pass fine
             pass
 
-        with ImportAlarm("Broken import", _fail_on_warning=True) as alarm_broken:
+        with ImportAlarm("Broken import", raise_exception=True) as alarm_broken:
             raise ImportError("Suppose a package imported here is not available")
 
         @alarm_working