Support for raising chained exceptions

Note: the interface is not the same as that of pybind11:
``nb::raise_from`` takes a printf-style varargs input and it furthermore
re-raises ``nb::python_error``.

A lower-level interface (``nb::chain_error``) is also available.

Author: wjakob

docs/api_core.rst

@@ -1087,6 +1087,11 @@ the reference section on :ref:`class binding <class_binding>`.
       Example use case: handling a Python error that occurs in a C++
       destructor where you cannot raise a C++ exception.
 
+   .. cpp:function:: void discard_as_unraisable(const char * context) noexcept
+
+      Convenience wrapper around the above function, which takes a C-style
+      string for the ``context`` argument.
+
    .. cpp:function:: handle type() const
 
       Returns a handle to the exception type
@@ -1207,6 +1212,24 @@ the reference section on :ref:`class binding <class_binding>`.
    interface provided by :cpp:class:`exception` class. This function provides
    an escape hatch for more specialized use cases.
 
+.. cpp:function:: void chain_error(handle type, const char * fmt, ...) noexcept
+
+   Raise a Python error of type ``type`` using the format string ``fmt``
+   interpreted by ``PyErr_FormatV``.
+
+   This newly created error is chained on top of an already existing error
+   status that must be set before calling the function.
+
+.. cpp:function:: void raise_from(python_error &e, handle type, const char * fmt, ...)
+
+   Convenience wrapper around :cpp:func:`chain_error <chain_error>`. It takes
+   an existing Python error (e.g. caught in a ``catch`` block) and creates an
+   additional Python exception with the current error as cause. It then
+   re-raises :cpp:class:`python_error`. The argument ``fmt`` is a
+   ``printf``-style format string interpreted by ``PyErr_FormatV``.
+
+   Usage of this function is explained in the documentation section on
+   :ref:`exception chaining <exception_chaining>`.
 
 Casting
 -------

docs/exceptions.rst

@@ -218,3 +218,74 @@ Alternately, to ignore the error, call `PyErr_Clear()
 <https://docs.python.org/3/c-api/exceptions.html#c.PyErr_Clear>`__. Any
 Python error must be thrown or cleared, or nanobind will be left in an
 invalid state.
+
+.. _exception_chaining:
+
+Chaining exceptions ('raise from')
+----------------------------------
+
+Python has a mechanism for indicating that exceptions were caused by other
+exceptions:
+
+.. code-block:: py
+
+    try:
+        print(1 / 0)
+    except Exception as exc:
+        raise RuntimeError("could not divide by zero") from exc
+
+To do a similar thing in pybind11, you can use the :cpp:func:`nb::raise_from
+<raise_from>` function, which requires a :cpp:class:`nb::python_error
+<python_error>` and re-raises it with a chained exception object.
+
+.. code-block:: cpp
+
+    nb::callable f = ...;
+    int arg = 123;
+    try {
+        f(arg);
+    } catch (nb::python_error &e) {
+        nb::raise_from(e, PyExc_RuntimeError, "Could not call 'f' with %i", arg);
+    }
+
+The function is internally based on the Python function ``PyErr_FormatV`` and
+takes ``printf``-style arguments following the format descriptor.
+
+An even lower-level interface is available via :cpp:func:`nb::chain_error
+<chain_error>`.
+
+Handling unraisable exceptions
+------------------------------
+
+If a Python function invoked from a C++ destructor or any function marked
+``noexcept(true)`` (collectively, "noexcept functions") throws an exception, there
+is no way to propagate the exception, as such functions may not throw.
+Should they throw or fail to catch any exceptions in their call graph,
+the C++ runtime calls ``std::terminate()`` to abort immediately.
+
+Similarly, Python exceptions raised in a class's ``__del__`` method do not
+propagate, but are logged by Python as an unraisable error. In Python 3.8+, a
+`system hook is triggered
+<https://docs.python.org/3/library/sys.html#sys.unraisablehook>`_
+and an auditing event is logged.
+
+Any noexcept function should have a try-catch block that traps
+:cpp:class:`nb::python_error <python_error>` (or any other exception that can
+occur). A useful approach is to convert them to Python exceptions and then
+``discard_as_unraisable`` as shown below.
+
+.. code-block:: cpp
+
+    void nonthrowing_func() noexcept(true) {
+        try {
+            // ...
+        } catch (nb::python_error &e) {
+            // Discard the Python error using Python APIs, using the C++ magic
+            // variable __func__. Python already knows the type and value and of the
+            // exception object.
+            e.discard_as_unraisable(__func__);
+        } catch (const std::exception &e) {
+            // Log and discard C++ exceptions.
+            third_party::log(e);
+        }
+    }

docs/porting.rst

@@ -327,7 +327,6 @@ Removed features include:
   pybind11, however.
 - ● Buffer protocol binding (``.def_buffer()``) was removed in favor of
   :cpp:class:`nb::ndarray\<..\> <nanobind::ndarray>`.
-- ● Nested exceptions are not supported.
 - ● Features to facilitate pickling and unpickling were removed.
 - ● Support for evaluating Python code strings was removed.
 

include/nanobind/nb_error.h

@@ -56,6 +56,11 @@ class NB_EXPORT python_error : public std::exception {
         PyErr_WriteUnraisable(context.ptr());
     }
 
+    void discard_as_unraisable(const char *context) noexcept {
+        object context_s = steal(PyUnicode_FromString(context));
+        discard_as_unraisable(context_s);
+    }
+
     handle value() const { return m_value; }
 
 #if PY_VERSION_HEX < 0x030C0000
@@ -142,4 +147,7 @@ class exception : public object {
     }
 };
 
+NB_CORE void chain_error(handle type, const char *fmt, ...) noexcept;
+NB_CORE void raise_from(python_error &e, handle type, const char *fmt, ...);
+
 NAMESPACE_END(NB_NAMESPACE)

src/error.cpp

@@ -8,6 +8,7 @@
 */
 
 #include <nanobind/nanobind.h>
+#include <cstdarg>
 #include "buffer.h"
 #include "nb_internals.h"
 
@@ -248,4 +249,70 @@ NB_CORE PyObject *exception_new(PyObject *scope, const char *name,
 }
 
 NAMESPACE_END(detail)
+
+static void chain_error_v(handle type, const char *fmt, va_list args) noexcept {
+#if PY_VERSION_HEX >= 0x030C0000
+    PyObject *value = PyErr_GetRaisedException();
+    check(value, "nanobind::detail::raise_from(): error status is not set!");
+#else
+    PyObject *tp = nullptr, *value = nullptr, *traceback = nullptr;
+
+    PyErr_Fetch(&tp, &value, &traceback);
+    check(tp, "nanobind::detail::raise_from(): error status is not set!");
+
+    PyErr_NormalizeException(&tp, &value, &traceback);
+    if (traceback) {
+        PyException_SetTraceback(value, traceback);
+        Py_DECREF(traceback);
+    }
+
+    Py_DECREF(tp);
+#endif
+
+#if !defined(PYPY_VERSION)
+    PyErr_FormatV(type.ptr(), fmt, args);
+#else
+    PyObject *exc_str = PyUnicode_FromFormatV(fmt, args);
+    check(exc_str, "nanobind::detail::raise_from(): PyUnicode_FromFormatV() failed!");
+    PyErr_SetObject(type.ptr(), exc_str);
+    Py_DECREF(exc_str);
+#endif
+
+    PyObject *value_2 = nullptr;
+#if PY_VERSION_HEX >= 0x030C0000
+    value_2 = PyErr_GetRaisedException();
+#else
+    PyErr_Fetch(&tp, &value_2, &traceback);
+    PyErr_NormalizeException(&tp, &value_2, &traceback);
+#endif
+
+    Py_INCREF(value);
+    PyException_SetCause(value_2, value); // steals
+    PyException_SetContext(value_2, value); // steals
+
+#if PY_VERSION_HEX >= 0x030C0000
+    PyErr_SetRaisedException(value_2);
+#else
+    PyErr_Restore(tp, value_2, traceback);
+#endif
+}
+
+void chain_error(handle type, const char *fmt, ...) noexcept {
+    va_list args;
+    va_start(args, fmt);
+    chain_error_v(type, fmt, args);
+    va_end(args);
+}
+
+void raise_from(python_error &e, handle type, const char *fmt, ...) {
+    e.restore();
+
+    va_list args;
+    va_start(args, fmt);
+    chain_error_v(type, fmt, args);
+    va_end(args);
+
+    detail::raise_python_error();
+}
+
 NAMESPACE_END(NB_NAMESPACE)

src/nb_type.cpp

@@ -1000,7 +1000,7 @@ bool nb_type_get(const std::type_info *cpp_type, PyObject *src, uint8_t flags,
         if (NB_LIKELY(valid)) {
             nb_inst *inst = (nb_inst *) src;
 
-            if (NB_UNLIKELY(((flags & (uint8_t) cast_flags::construct) != 0) == inst->ready)) {
+            if (NB_UNLIKELY(((flags & (uint8_t) cast_flags::construct) != 0) == (bool) inst->ready)) {
                 PyErr_WarnFormat(
                     PyExc_RuntimeWarning, 1, "nanobind: %s of type '%s'!\n",
                     inst->ready
@@ -1386,8 +1386,8 @@ static void nb_type_put_unique_finalize(PyObject *o,
     nb_inst *inst = (nb_inst *) o;
 
     if (cpp_delete) {
-        check(inst->ready == is_new && inst->destruct == is_new &&
-                  inst->cpp_delete == is_new,
+        check((bool) inst->ready == is_new && (bool) inst->destruct == is_new &&
+                  (bool) inst->cpp_delete == is_new,
               "nanobind::detail::nb_type_put_unique(type='%s', cpp_delete=%i): "
               "unexpected status flags! (ready=%i, destruct=%i, cpp_delete=%i)",
               type_name(cpp_type), cpp_delete, inst->ready, inst->destruct,

tests/test_exception.cpp

@@ -49,4 +49,14 @@ NB_MODULE(test_exception_ext, m) {
 
     nb::exception<MyError3>(m, "MyError3");
     m.def("raise_my_error_3", [] { throw MyError3(); });
+
+    m.def("raise_nested", [](nb::callable c) {
+            int arg = 123;
+            try {
+                c(arg);
+            } catch (nb::python_error &e) {
+                nb::raise_from(e, PyExc_RuntimeError, "Call with value %i failed", arg);
+            }
+        }
+    );
 }

tests/test_exception.py

@@ -93,3 +93,12 @@ def test19_raise_my_error_3():
     with pytest.raises(t.MyError3) as excinfo:
         assert t.raise_my_error_3()
     assert str(excinfo.value) == 'MyError3'
+
+def test20_nested():
+    def foo(arg):
+        return arg / 0
+    with pytest.raises(RuntimeError) as excinfo:
+        t.raise_nested(foo)
+    assert str(excinfo.value) == 'Call with value 123 failed'
+    assert str(excinfo.value.__cause__) == 'division by zero'
+