From 2b7985e548ee7fb551528384ae864f8b175ffbe9 Mon Sep 17 00:00:00 2001 From: jbarlow83 Date: Tue, 13 Jul 2021 12:32:56 -0700 Subject: [PATCH] Improve documentation of discard_as_unraisable() API (#2697) * Improve documentation of discard_as_unraisable() API * Update pytypes.h Remove "the above" * Update pytypes.h Fix precommit error Co-authored-by: Aaron Gokaslan --- include/pybind11/pytypes.h | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/include/pybind11/pytypes.h b/include/pybind11/pytypes.h index 32386a44..0fca32a4 100644 --- a/include/pybind11/pytypes.h +++ b/include/pybind11/pytypes.h @@ -345,16 +345,17 @@ public: /// error variables (but the `.what()` string is still available). void restore() { PyErr_Restore(m_type.release().ptr(), m_value.release().ptr(), m_trace.release().ptr()); } - /// If it is impossible to raise the currently-held error, such as in destructor, we can write - /// it out using Python's unraisable hook (sys.unraisablehook). The error context should be - /// some object whose repr() helps identify the location of the error. Python already knows the - /// type and value of the error, so there is no need to repeat that. For example, __func__ could - /// be helpful. After this call, the current object no longer stores the error variables, - /// and neither does Python. + /// If it is impossible to raise the currently-held error, such as in a destructor, we can write + /// it out using Python's unraisable hook (`sys.unraisablehook`). The error context should be + /// some object whose `repr()` helps identify the location of the error. Python already knows the + /// type and value of the error, so there is no need to repeat that. After this call, the current + /// object no longer stores the error variables, and neither does Python. void discard_as_unraisable(object err_context) { restore(); PyErr_WriteUnraisable(err_context.ptr()); } + /// An alternate version of `discard_as_unraisable()`, where a string provides information on the + /// location of the error. For example, `__func__` could be helpful. void discard_as_unraisable(const char *err_context) { discard_as_unraisable(reinterpret_steal(PYBIND11_FROM_STRING(err_context))); }