From e2f86af216d969188ca0fb42e2059aa517dd3a6d Mon Sep 17 00:00:00 2001 From: Jan Iwaszkiewicz Date: Tue, 17 Jun 2025 20:03:58 +0200 Subject: [PATCH] docs: add documentation entry for warnings (#5356) * [docs] Add entry for warnings * Fix code formatting * Update docs * Fix issue with docs * [skip ci] Minor edits. --------- Co-authored-by: Ralf W. Grosse-Kunstleve --- docs/advanced/exceptions.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/advanced/exceptions.rst b/docs/advanced/exceptions.rst index 8f0e9c93a..921b4367f 100644 --- a/docs/advanced/exceptions.rst +++ b/docs/advanced/exceptions.rst @@ -328,6 +328,28 @@ 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 +======================================= + +Wrappers for handling Python warnings are provided in ``pybind11/warnings.h``. +This header must be included explicitly; it is not transitively included via +``pybind11/pybind11.h``. + +Warnings can be raised with the ``warn`` function: + +.. code-block:: cpp + + py::warnings::warn("This is a warning!", PyExc_Warning); + + // Optionally, a `stack_level` can be specified. + py::warnings::warn("Another one!", PyExc_DeprecationWarning, 3); + +New warning types can be registered at the module level using ``new_warning_type``: + +.. code-block:: cpp + + py::warnings::new_warning_type(m, "CustomWarning", PyExc_RuntimeWarning); + Chaining exceptions ('raise from') ==================================