From 726698854053a054f4ba2b72e03872e2fada6137 Mon Sep 17 00:00:00 2001 From: jiwaszki Date: Thu, 5 Sep 2024 23:28:53 +0200 Subject: [PATCH 1/2] [docs] Add entry for warnings --- docs/advanced/exceptions.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/advanced/exceptions.rst b/docs/advanced/exceptions.rst index 8f0e9c93a..970cf136f 100644 --- a/docs/advanced/exceptions.rst +++ b/docs/advanced/exceptions.rst @@ -328,6 +328,30 @@ 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. +Handling warnings from the Python C API +===================================== + +Where possible, use :ref:`pybind11 warnings ` instead of calling +the Python C API directly. The motivation is similar to previously mentioned errors. +All warnings categories are required to be a subclass of `PyExc_Warning` from Python C API. + +Warnings can be raised with `warn` function: + +.. code-block:: cpp + + py::warnings::warn("This is warning!", PyExc_Warning); + + // When calling `stack_level` can be specified as well. + py::warnings::warn("Another one!", PyExc_DeprecationWarning, 3); + +New warning types can be registered on the module level with `new_warning_type`: + +.. code-block:: cpp + + py::warnings::new_warning_type(m, "CustomWarning", PyExc_RuntimeWarning); + +.. versionadded:: 2.14 + Chaining exceptions ('raise from') ================================== From 2fbd013434e4dafc5fae99c85d94990d40397447 Mon Sep 17 00:00:00 2001 From: jiwaszki Date: Thu, 5 Sep 2024 23:59:11 +0200 Subject: [PATCH 2/2] Fix code formatting --- docs/advanced/exceptions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/advanced/exceptions.rst b/docs/advanced/exceptions.rst index 970cf136f..a4a282162 100644 --- a/docs/advanced/exceptions.rst +++ b/docs/advanced/exceptions.rst @@ -333,9 +333,9 @@ Handling warnings from the Python C API Where possible, use :ref:`pybind11 warnings ` instead of calling the Python C API directly. The motivation is similar to previously mentioned errors. -All warnings categories are required to be a subclass of `PyExc_Warning` from Python C API. +All warnings categories are required to be a subclass of ``PyExc_Warning`` from Python C API. -Warnings can be raised with `warn` function: +Warnings can be raised with ``warn`` function: .. code-block:: cpp @@ -344,7 +344,7 @@ Warnings can be raised with `warn` function: // When calling `stack_level` can be specified as well. py::warnings::warn("Another one!", PyExc_DeprecationWarning, 3); -New warning types can be registered on the module level with `new_warning_type`: +New warning types can be registered on the module level with ``new_warning_type``: .. code-block:: cpp