add cause parameter to signal, error, cerror, warn

Technologicat · Technologicat · commit b2b5739f0509 · 2020-09-18T03:33:00.000+03:00
This allows, essentially, to perform `signal ... from ...` et al.,
like in `raise ... from ...`.
diff --git a/unpythonic/conditions.py b/unpythonic/conditions.py
@@ -86,8 +86,7 @@ class ControlError(Exception):
     when no handler handles the signal.
     """
 
-# TODO: now that signals have tracebacks (in Python 3.7+), "signal from" (like "raise from") would be nice.
-def signal(condition):
+def signal(condition, *, cause=None):
     """Signal a condition.
 
     Signaling a condition works similarly to raising an exception (pass an
@@ -120,6 +119,11 @@ def signal(condition):
     otherwise the same as `signal`, except it raises if `signal` would have
     returned normally.
 
+    The optional `cause` argument is as in `unpythonic.misc.raisef`.
+    In other words, if we pretend for a moment that `signal` is a Python
+    keyword, it essentially performs a `signal ... from ...`. The default
+    `cause=None` performs a plain `signal ...`.
+
     **Notes**
 
     This condition system is implemented on top of exceptions. The magic trick
@@ -159,17 +163,21 @@ def accepts_arg(f):
     #   special handling for the "class raised" case.
     #     https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement
     #     https://stackoverflow.com/questions/19768515/is-there-a-difference-between-raising-exception-class-and-exception-instance/19768732
-    def canonize(exc):
+    def canonize(exc, err_reason):
+        if exc is None:
+            return None
         if isinstance(exc, BaseException):  # "signal(SomeError())"
             return exc
         try:
             if issubclass(exc, BaseException):  # "signal(SomeError)"
                 return exc()  # instantiate with no args, like `raise` does
         except TypeError:  # "issubclass() arg 1 must be a class"
             pass
-        error(ControlError("Only exceptions and subclasses of Exception can be signaled; got {} with value '{}'.".format(type(condition), condition)))
+        error(ControlError("Only exceptions and subclasses of Exception can {}; got {} with value '{}'.".format(err_reason, type(condition), condition)))
 
-    condition = canonize(condition)
+    condition = canonize(condition, "be signaled")
+    cause = canonize(cause, "act as the cause of another signal")
+    condition.__cause__ = cause
 
     # Embed a stack trace in the signal, like Python does for raised exceptions.
     # This only works on Python 3.7 and later, because we need to create a traceback object in pure Python code.
@@ -666,8 +674,9 @@ def call_with_restarts(f):
     return call_with_restarts
 
 # Common Lisp standard error handling protocols, building on the `signal` function.
+# Pythonified to add the `cause` argument.
 
-def error(condition):
+def error(condition, *, cause=None):
     """Like `signal`, but raise `ControlError` if the condition is not handled.
 
     Note **raise**, not **signal**. Keep in mind the original Common Lisp
@@ -678,17 +687,23 @@ def error(condition):
 
     Note *handled* means that a handler must actually invoke a restart; a
     condition does not count as handled simply because a handler was triggered.
+
+    The optional `cause` argument is as in `unpythonic.misc.raisef`.
+    In other words, if we pretend for a moment that `error` is a Python
+    keyword, it essentially performs a `error ... from ...`. The default
+    `cause=None` performs a plain `error ...`.
     """
-    signal(condition)
+    signal(condition, cause=cause)
     # TODO: If we want to support the debugger at some point in the future,
     # TODO: this is the appropriate point to ask the user what to do,
     # TODO: before the call stack unwinds.
     #
     # TODO: Do we want to give one last chance to handle the ControlError?
     # TODO: And do we want to raise ControlError, or the original condition?
+    condition.__cause__ = cause  # chain the causes, since we'll add a new one next.
     raise ControlError("Unhandled error condition") from condition
 
-def cerror(condition):
+def cerror(condition, *, cause=None):
     """Like `error`, but allow a handler to instruct the caller to ignore the error.
 
     `cerror` internally establishes a restart named `proceed`, which can be
@@ -699,6 +714,11 @@ def cerror(condition):
     We use the name "proceed" instead of Common Lisp's "continue", because in
     Python `continue` is a reserved word.
 
+    The optional `cause` argument is as in `unpythonic.misc.raisef`.
+    In other words, if we pretend for a moment that `cerror` is a Python
+    keyword, it essentially performs a `cerror ... from ...`. The default
+    `cause=None` performs a plain `cerror ...`.
+
     Example::
 
         # If your condition needs data, it can be passed to __init__.
@@ -717,9 +737,9 @@ def __init__(self, value):
 
     """
     with restarts(proceed=(lambda: None)):  # just for control, no return value
-        error(condition)
+        error(condition, cause=cause)
 
-def warn(condition):
+def warn(condition, *, cause=None):
     """Like `signal`, but emit a warning if the condition is not handled.
 
     For emitting the warning, we use Python's standard `warnings.warn` mechanism.
@@ -732,6 +752,11 @@ def warn(condition):
     If not (i.e. some other subclass of `Exception` is being signaled), the
     generic category `Warning` is used, with the message set to `str(condition)`.
 
+    The optional `cause` argument is as in `unpythonic.misc.raisef`.
+    In other words, if we pretend for a moment that `warn` is a Python
+    keyword, it essentially performs a `warn ... from ...`. The default
+    `cause=None` performs a plain `warn ...`.
+
     Example::
 
         class HelpMe(Warning):
@@ -762,7 +787,7 @@ def __init__(self, value):
     """
     with restarts(muffle=(lambda: None)):  # just for control, no return value
         with restarts(_proceed=(lambda: None)):  # for internal use by unpythonic.test.fixtures
-            signal(condition)
+            signal(condition, cause=cause)
         if isinstance(condition, Warning):
             warnings.warn(condition, stacklevel=2)  # 2 to ignore our lispy `warn` wrapper.
         else:
diff --git a/unpythonic/test/test_conditions.py b/unpythonic/test/test_conditions.py
@@ -375,6 +375,53 @@ def warn_protocol():
                 test[unbox(result) == 42]
         warn_protocol()
 
+    # TODO: test the cause chain in the resulting ControlError from unhandled error(..., cause=...)
+    with testset("signal with cause (signal-from)"):
+        with handlers((JustTesting, lambda c: use_value(c))):
+            with restarts(use_value=(lambda x: x)) as result:
+                signal(JustTesting("Hullo"))  # no cause
+            test[unbox(result).__cause__ is None]
+
+            exc = JustTesting("Hello")
+            with restarts(use_value=(lambda x: x)) as result:
+                signal(JustTesting("Hullo"), cause=exc)  # cause given, like "raise ... from ..."
+            test[unbox(result).__cause__ is exc]
+
+            # The other protocols also support the cause parameter.
+            with restarts(use_value=(lambda x: x)) as result:
+                error(JustTesting("Hullo"), cause=exc)
+            test[unbox(result).__cause__ is exc]
+
+            with restarts(use_value=(lambda x: x)) as result:
+                cerror(JustTesting("Hullo"), cause=exc)
+            test[unbox(result).__cause__ is exc]
+
+            with restarts(use_value=(lambda x: x)) as result:
+                warn(JustTesting("Hullo"), cause=exc)
+            test[unbox(result).__cause__ is exc]
+
+        # An unhandled `error` or `cerror`, when it **raises** `ControlError`,
+        # sets the cause of that `ControlError` to the original unhandled signal.
+        # In Python 3.7+, this will also produce nice stack traces.
+        # In up to Python 3.6, it will at least show the chain of causes.
+        with catch_signals(False):
+            try:
+                exc1 = JustTesting("Hullo")
+                error(exc1)
+            except ControlError as err:
+                test[err.__cause__ is exc1]
+
+            # Causes can be chained, as with regular exceptions. Here's how
+            # this interacts with an unhandled signal:
+            try:
+                exc1 = JustTesting("Hello")
+                exc2 = JustTesting("Hullo")
+                error(exc2, cause=exc1)
+            except ControlError as err:
+                test[err.__cause__ is exc2]
+                test[err.__cause__.__cause__ is exc1]
+                test[err.__cause__.__cause__.__cause__ is None]
+
     # find_restart can be used to look for a restart before committing to
     # actually invoking it.
     with testset("find_restart"):
