Add py::raise_from to enable chaining exceptions on Python 3.3+

Author: virtuald

docs/advanced/exceptions.rst

@@ -261,6 +261,34 @@ Alternately, to ignore the error, call `PyErr_Clear
 Any Python error must be thrown or cleared, or Python/pybind11 will be left in
 an invalid state.
 
+Chaining exceptions ('raise from')
+==================================
+
+In Python 3.3 a mechanism for indicating that exceptions were caused by other
+exceptions was introduced:
+
+.. 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 ``py::raise_from`` function. It
+sets the current python error indicator, so to continue propagating the exception
+you should ``throw py::error_already_set()``.
+
+.. code-block:: cpp
+
+    try {
+        py::eval("print(1 / 0"));
+    } catch (py::error_already_set &e) {
+        py::raise_from(e, PyExc_RuntimeError, "could not divide by zero");
+        throw py::error_already_set();
+    }
+
+.. versionadded:: 2.6
+
 .. _unraisable_exceptions:
 
 Handling unraisable exceptions

include/pybind11/pytypes.h

@@ -372,6 +372,42 @@ class error_already_set : public std::runtime_error {
     object m_type, m_value, m_trace;
 };
 
+#if PY_VERSION_HEX >= 0x03030000
+
+/// Replaces the current Python error indicator with the chosen error, performing a
+/// 'raise from' to indicate that the chosen error was caused by the original error
+inline void raise_from(PyObject *type, const char *message) {
+    // from cpython/errors.c _PyErr_FormatVFromCause
+    PyObject *exc, *val, *val2, *tb;
+    PyErr_Fetch(&exc, &val, &tb);
+
+    PyErr_NormalizeException(&exc, &val, &tb);
+    if (tb != nullptr) {
+        PyException_SetTraceback(val, tb);
+        Py_DECREF(tb);
+    }
+    Py_DECREF(exc);
+
+    PyErr_SetString(type, message);
+    PyErr_Fetch(&exc, &val2, &tb);
+    PyErr_NormalizeException(&exc, &val2, &tb);
+    Py_INCREF(val);
+    PyException_SetCause(val2, val);
+    PyException_SetContext(val2, val);
+    PyErr_Restore(exc, val2, tb);
+}
+
+/// Sets the current Python error indicator with the chosen error, performing a 'raise from'
+/// from the error contained in error_already_set to indicate that the chosen error was
+/// caused by the original error. After this function is called error_already_set will
+/// no longer contain an error.
+inline void raise_from(error_already_set& err, PyObject *type, const char *message) {
+    err.restore();
+    raise_from(type, message);
+}
+
+#endif
+
 /** \defgroup python_builtins _
     Unless stated otherwise, the following C++ functions behave the same
     as their Python counterparts.

tests/test_exceptions.cpp

@@ -198,6 +198,26 @@ TEST_SUBMODULE(exceptions, m) {
         throw py::error_already_set();
     });
 
+#if PY_VERSION_HEX >= 0x03030000
+
+    m.def("raise_from", []() {
+        PyErr_SetString(PyExc_ValueError, "inner");
+        py::raise_from(PyExc_ValueError, "outer");
+        throw py::error_already_set();
+    });
+
+    m.def("raise_from_already_set", []() {
+        try {
+            PyErr_SetString(PyExc_ValueError, "inner");
+            throw py::error_already_set();
+        } catch (py::error_already_set& e) {
+            py::raise_from(e, PyExc_ValueError, "outer");
+            throw py::error_already_set();
+        }
+    });
+
+#endif
+
     m.def("python_call_in_destructor", [](py::dict d) {
         try {
             PythonCallInDestructor set_dict_in_destructor(d);

tests/test_exceptions.py

@@ -3,6 +3,8 @@
 
 import pytest
 
+import env  # noqa: F401
+
 from pybind11_tests import exceptions as m
 import pybind11_cross_module_tests as cm
 
@@ -23,6 +25,22 @@ def test_error_already_set(msg):
     assert msg(excinfo.value) == "foo"
 
 
+@pytest.mark.skipif("env.PY2")
+def test_raise_from(msg):
+    with pytest.raises(ValueError) as excinfo:
+        m.raise_from()
+    assert msg(excinfo.value) == "outer"
+    assert msg(excinfo.value.__cause__) == "inner"
+
+
+@pytest.mark.skipif("env.PY2")
+def test_raise_from_already_set(msg):
+    with pytest.raises(ValueError) as excinfo:
+        m.raise_from_already_set()
+    assert msg(excinfo.value) == "outer"
+    assert msg(excinfo.value.__cause__) == "inner"
+
+
 def test_cross_module_exceptions():
     with pytest.raises(RuntimeError) as excinfo:
         cm.raise_runtime_error()