Add support for explicit exception cause chaining to the throw special form (#863)

Fixes #862

---------

Co-authored-by: Christopher Rink <[email protected]>

Author: chrisrink10

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
  * Added filename metadata to compiler exceptions (#844)
  * Added a compile-time warning for attempting to call a function with an unsupported number of arguments (#671)
+ * Added support for explicit cause exception chaining to the `throw` special form (#862)
 
 ### Changed
  * Cause exceptions arising from compilation issues during macroexpansion will no longer be nested for each level of macroexpansion (#852)

docs/specialforms.rst

@@ -370,11 +370,21 @@ Primary Special Forms
       The Basilisp compiler makes attempts to verify whether a ``set!`` is legal at compile time, but there are cases which must be deferred to runtime due to the dynamic nature of the language.
       In particular, due to the non-lexical nature of dynamic Var bindings, it can be difficult to establish if a Var is thread-bound when it is ``set!``, so this check is deferred to runtime.
 
-.. lpy:specialform:: (throw exc)
+.. lpy:specialform:: (throw exc cause?)
 
    Throw the exception named by ``exc``.
    The semantics of ``throw`` are identical to those of Python's `raise <https://docs.python.org/3/reference/simple_stmts.html#the-raise-statement>`_ statement with exception.
-   Unlike Python's ``raise``, an exception is always required and no explicit exception chaining is permitted (as by the ``from`` keyword in Python).
+   Unlike Python's ``raise``, an exception is always required.
+   A second optional cause exception may be provided after the exception to be thrown -- this is a direct Basilisp equivalent to ``from`` semantics to Python's ``raise`` statement.
+   The cause may be ``nil`` to suppress cause chaining.
+
+   .. note::
+
+      Cause exceptions are stored in the ``__cause__`` attribute on thrown exceptions.
+      Contrast this with the case where during the handling of an exception ``a`` , a second exception ``b`` is raised.
+      Without explicit chaining, ``a`` would be stored in the ``__context__`` attribute of ``b``.
+      Standard Python exception formatting language will show both cause and context exceptions, but describes each differently.
+      For more details, see Python's documentation on `exception context <https://docs.python.org/3/library/exceptions.html#exception-context>`_.
 
 .. lpy:specialform:: (try *exprs *catch-exprs finally?)
 

src/basilisp/lang/compiler/analyzer.py

@@ -3026,11 +3026,27 @@ def _set_bang_ast(form: ISeq, ctx: AnalyzerContext) -> SetBang:
 
 def _throw_ast(form: ISeq, ctx: AnalyzerContext) -> Throw:
     assert form.first == SpecialForm.THROW
+    nelems = count(form)
+
+    if nelems < 2 or nelems > 3:
+        raise ctx.AnalyzerException(
+            "throw forms must contain exactly 2 or 3 elements: (throw exc [cause])",
+            form=form,
+        )
+
     with ctx.expr_pos():
         exc = _analyze_form(runtime.nth(form, 1), ctx)
+
+    if nelems == 3:
+        with ctx.expr_pos():
+            cause = _analyze_form(runtime.nth(form, 2), ctx)
+    else:
+        cause = None
+
     return Throw(
         form=form,
         exception=exc,
+        cause=cause,
         env=ctx.get_node_env(pos=ctx.syntax_position),
     )
 

src/basilisp/lang/compiler/generator.py

@@ -2938,11 +2938,23 @@ def _throw_to_py_ast(ctx: GeneratorContext, node: Throw) -> GeneratedPyAST[ast.e
     assert node.op == NodeOp.THROW
 
     exc_ast = gen_py_ast(ctx, node.exception)
-    raise_body = ast.Raise(exc=exc_ast.node, cause=None)
+
+    cause: Optional[ast.AST]
+    cause_deps: Iterable[ast.AST]
+    if (
+        node.cause is not None
+        and (cause_ast := gen_py_ast(ctx, node.cause)) is not None
+    ):
+        cause = cause_ast.node
+        cause_deps = cause_ast.dependencies
+    else:
+        cause, cause_deps = None, []
+
+    raise_body = ast.Raise(exc=exc_ast.node, cause=cause)
 
     return GeneratedPyAST(
         node=_noop_node(),
-        dependencies=list(chain(exc_ast.dependencies, [raise_body])),
+        dependencies=list(chain(exc_ast.dependencies, cause_deps, [raise_body])),
     )
 
 

src/basilisp/lang/compiler/nodes.py

@@ -879,6 +879,7 @@ class SetBang(Node[SpecialForm]):
 class Throw(Node[SpecialForm]):
     form: SpecialForm
     exception: Node
+    cause: Optional[Node]
     env: NodeEnv
     children: Sequence[kw.Keyword] = vec.v(EXCEPTION)
     op: NodeOp = NodeOp.THROW

tests/basilisp/compiler_test.py

@@ -5134,15 +5134,72 @@ def test_syntax_quoting(test_ns: str, lcompile: CompileFn, resolver: reader.Reso
     )
 
 
-def test_throw(lcompile: CompileFn):
-    with pytest.raises(AttributeError):
-        lcompile("(throw (python/AttributeError))")
+class TestThrow:
+    def test_throw_not_enough_args(self, lcompile: CompileFn):
+        with pytest.raises(compiler.CompilerException):
+            lcompile("(throw)")
 
-    with pytest.raises(TypeError):
-        lcompile("(throw (python/TypeError))")
+    def test_throw_too_many_args(self, lcompile: CompileFn):
+        with pytest.raises(compiler.CompilerException):
+            lcompile("(throw (python/ValueError) nil :a)")
+
+    def test_throw(self, lcompile: CompileFn):
+        with pytest.raises(AttributeError):
+            lcompile("(throw (python/AttributeError))")
+
+        with pytest.raises(TypeError):
+            lcompile("(throw (python/TypeError))")
 
-    with pytest.raises(ValueError):
-        lcompile("(throw (python/ValueError))")
+        with pytest.raises(ValueError):
+            lcompile("(throw (python/ValueError))")
+
+    def test_throw_chained(self, lcompile: CompileFn):
+        try:
+            lcompile(
+                """
+            (try
+              (/ 1.0 0)
+              (catch python/ZeroDivisionError e
+                (throw (python/ValueError "lol") e)))
+            """
+            )
+        except ValueError as e:
+            assert str(e) == "lol"
+            assert e.__suppress_context__ is True
+            assert isinstance(e.__cause__, ZeroDivisionError)
+            assert isinstance(e.__context__, ZeroDivisionError)
+
+    def test_throw_suppress_chain(self, lcompile: CompileFn):
+        try:
+            lcompile(
+                """
+            (try
+              (/ 1.0 0)
+              (catch python/ZeroDivisionError e
+                (throw (python/ValueError "lol") nil)))
+            """
+            )
+        except ValueError as e:
+            assert str(e) == "lol"
+            assert e.__suppress_context__ is True
+            assert e.__cause__ is None
+            assert isinstance(e.__context__, ZeroDivisionError)
+
+    def test_throw_context_only(self, lcompile: CompileFn):
+        try:
+            lcompile(
+                """
+            (try
+              (/ 1.0 0)
+              (catch python/ZeroDivisionError e
+                (throw (python/ValueError "lol"))))
+            """
+            )
+        except ValueError as e:
+            assert str(e) == "lol"
+            assert e.__suppress_context__ is False
+            assert e.__cause__ is None
+            assert isinstance(e.__context__, ZeroDivisionError)
 
 
 class TestTryCatch: