Spaces:
Runtime error
Runtime error
Exceptions | |
########## | |
Built-in C++ to Python exception translation | |
============================================ | |
When Python calls C++ code through pybind11, pybind11 provides a C++ exception handler | |
that will trap C++ exceptions, translate them to the corresponding Python exception, | |
and raise them so that Python code can handle them. | |
pybind11 defines translations for ``std::exception`` and its standard | |
subclasses, and several special exception classes that translate to specific | |
Python exceptions. Note that these are not actually Python exceptions, so they | |
cannot be examined using the Python C API. Instead, they are pure C++ objects | |
that pybind11 will translate the corresponding Python exception when they arrive | |
at its exception handler. | |
.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| | |
+--------------------------------------+--------------------------------------+ | |
| Exception thrown by C++ | Translated to Python exception type | | |
+======================================+======================================+ | |
| :class:`std::exception` | ``RuntimeError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`std::bad_alloc` | ``MemoryError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`std::domain_error` | ``ValueError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`std::invalid_argument` | ``ValueError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`std::length_error` | ``ValueError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`std::out_of_range` | ``IndexError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`std::range_error` | ``ValueError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`std::overflow_error` | ``OverflowError`` | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`pybind11::stop_iteration` | ``StopIteration`` (used to implement | | |
| | custom iterators) | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`pybind11::index_error` | ``IndexError`` (used to indicate out | | |
| | of bounds access in ``__getitem__``, | | |
| | ``__setitem__``, etc.) | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`pybind11::value_error` | ``ValueError`` (used to indicate | | |
| | wrong value passed in | | |
| | ``container.remove(...)``) | | |
+--------------------------------------+--------------------------------------+ | |
| :class:`pybind11::key_error` | ``KeyError`` (used to indicate out | | |
| | of bounds access in ``__getitem__``, | | |
| | ``__setitem__`` in dict-like | | |
| | objects, etc.) | | |
+--------------------------------------+--------------------------------------+ | |
Exception translation is not bidirectional. That is, *catching* the C++ | |
exceptions defined above above will not trap exceptions that originate from | |
Python. For that, catch :class:`pybind11::error_already_set`. See :ref:`below | |
<handling_python_exceptions_cpp>` for further details. | |
There is also a special exception :class:`cast_error` that is thrown by | |
when the input arguments cannot be converted to Python | |
objects. | |
Registering custom translators | |
============================== | |
If the default exception conversion policy described above is insufficient, | |
pybind11 also provides support for registering custom exception translators. | |
To register a simple exception conversion that translates a C++ exception into | |
a new Python exception using the C++ exception's ``what()`` method, a helper | |
function is available: | |
.. code-block:: cpp | |
py::register_exception<CppExp>(module, "PyExp"); | |
This call creates a Python exception class with the name ``PyExp`` in the given | |
module and automatically converts any encountered exceptions of type ``CppExp`` | |
into Python exceptions of type ``PyExp``. | |
When more advanced exception translation is needed, the function | |
``py::register_exception_translator(translator)`` can be used to register | |
functions that can translate arbitrary exception types (and which may include | |
additional logic to do so). The function takes a stateless callable (e.g. a | |
function pointer or a lambda function without captured variables) with the call | |
signature ``void(std::exception_ptr)``. | |
When a C++ exception is thrown, the registered exception translators are tried | |
in reverse order of registration (i.e. the last registered translator gets the | |
first shot at handling the exception). | |
Inside the translator, ``std::rethrow_exception`` should be used within | |
a try block to re-throw the exception. One or more catch clauses to catch | |
the appropriate exceptions should then be used with each clause using | |
``PyErr_SetString`` to set a Python exception or ``ex(string)`` to set | |
the python exception to a custom exception type (see below). | |
To declare a custom Python exception type, declare a ``py::exception`` variable | |
and use this in the associated exception translator (note: it is often useful | |
to make this a static declaration when using it inside a lambda expression | |
without requiring capturing). | |
The following example demonstrates this for a hypothetical exception classes | |
``MyCustomException`` and ``OtherException``: the first is translated to a | |
custom python exception ``MyCustomError``, while the second is translated to a | |
standard python RuntimeError: | |
.. code-block:: cpp | |
static py::exception<MyCustomException> exc(m, "MyCustomError"); | |
py::register_exception_translator([](std::exception_ptr p) { | |
try { | |
if (p) std::rethrow_exception(p); | |
} catch (const MyCustomException &e) { | |
exc(e.what()); | |
} catch (const OtherException &e) { | |
PyErr_SetString(PyExc_RuntimeError, e.what()); | |
} | |
}); | |
Multiple exceptions can be handled by a single translator, as shown in the | |
example above. If the exception is not caught by the current translator, the | |
previously registered one gets a chance. | |
If none of the registered exception translators is able to handle the | |
exception, it is handled by the default converter as described in the previous | |
section. | |
.. seealso:: | |
The file :file:`tests/test_exceptions.cpp` contains examples | |
of various custom exception translators and custom exception types. | |
.. note:: | |
Call either ``PyErr_SetString`` or a custom exception's call | |
operator (``exc(string)``) for every exception caught in a custom exception | |
translator. Failure to do so will cause Python to crash with ``SystemError: | |
error return without exception set``. | |
Exceptions that you do not plan to handle should simply not be caught, or | |
may be explicitly (re-)thrown to delegate it to the other, | |
previously-declared existing exception translators. | |
.. _handling_python_exceptions_cpp: | |
Handling exceptions from Python in C++ | |
====================================== | |
When C++ calls Python functions, such as in a callback function or when | |
manipulating Python objects, and Python raises an ``Exception``, pybind11 | |
converts the Python exception into a C++ exception of type | |
whose payload contains a C++ string textual | |
summary and the actual Python exception. ``error_already_set`` is used to | |
propagate Python exception back to Python (or possibly, handle them in C++). | |
.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| | |
+--------------------------------------+--------------------------------------+ | |
| Exception raised in Python | Thrown as C++ exception type | | |
+======================================+======================================+ | |
| Any Python ``Exception`` | :class:`pybind11::error_already_set` | | |
+--------------------------------------+--------------------------------------+ | |
For example: | |
.. code-block:: cpp | |
try { | |
// open("missing.txt", "r") | |
auto file = py::module::import("io").attr("open")("missing.txt", "r"); | |
auto text = file.attr("read")(); | |
file.attr("close")(); | |
} catch (py::error_already_set &e) { | |
if (e.matches(PyExc_FileNotFoundError)) { | |
py::print("missing.txt not found"); | |
} else if (e.match(PyExc_PermissionError)) { | |
py::print("missing.txt found but not accessible"); | |
} else { | |
throw; | |
} | |
} | |
Note that C++ to Python exception translation does not apply here, since that is | |
a method for translating C++ exceptions to Python, not vice versa. The error raised | |
from Python is always ``error_already_set``. | |
This example illustrates this behavior: | |
.. code-block:: cpp | |
try { | |
py::eval("raise ValueError('The Ring')"); | |
} catch (py::value_error &boromir) { | |
// Boromir never gets the ring | |
assert(false); | |
} catch (py::error_already_set &frodo) { | |
// Frodo gets the ring | |
py::print("I will take the ring"); | |
} | |
try { | |
// py::value_error is a request for pybind11 to raise a Python exception | |
throw py::value_error("The ball"); | |
} catch (py::error_already_set &cat) { | |
// cat won't catch the ball since | |
// py::value_error is not a Python exception | |
assert(false); | |
} catch (py::value_error &dog) { | |
// dog will catch the ball | |
py::print("Run Spot run"); | |
throw; // Throw it again (pybind11 will raise ValueError) | |
} | |
Handling errors from the Python C API | |
===================================== | |
Where possible, use :ref:`pybind11 wrappers <wrappers>` instead of calling | |
the Python C API directly. When calling the Python C API directly, in | |
addition to manually managing reference counts, one must follow the pybind11 | |
error protocol, which is outlined here. | |
After calling the Python C API, if Python returns an error, | |
``throw py::error_already_set();``, which allows pybind11 to deal with the | |
exception and pass it back to the Python interpreter. This includes calls to | |
the error setting functions such as ``PyErr_SetString``. | |
.. code-block:: cpp | |
PyErr_SetString(PyExc_TypeError, "C API type error demo"); | |
throw py::error_already_set(); | |
// But it would be easier to simply... | |
throw py::type_error("pybind11 wrapper type error"); | |
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 Python/pybind11 will be left in | |
an invalid state. | |
.. _unraisable_exceptions: | |
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 | |
class:`error_already_set` (or any other exception that can occur). Note that | |
pybind11 wrappers around Python exceptions such as | |
:class:`pybind11::value_error` are *not* Python exceptions; they are C++ | |
exceptions that pybind11 catches and converts to Python exceptions. Noexcept | |
functions cannot propagate these exceptions either. 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 (py::error_already_set &eas) { | |
// 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. | |
eas.discard_as_unraisable(__func__); | |
} catch (const std::exception &e) { | |
// Log and discard C++ exceptions. | |
third_party::log(e); | |
} | |
} | |
.. versionadded:: 2.6 | |