From 726698854053a054f4ba2b72e03872e2fada6137 Mon Sep 17 00:00:00 2001 From: jiwaszki Date: Thu, 5 Sep 2024 23:28:53 +0200 Subject: [PATCH 1/4] [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 8f0e9c93a4..970cf136f9 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/4] 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 970cf136f9..a4a282162a 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 From 706ece4ba5be086033c21741897cafd2a458d60c Mon Sep 17 00:00:00 2001 From: jiwaszki Date: Tue, 1 Oct 2024 00:30:52 +0200 Subject: [PATCH 3/4] Update docs --- docs/advanced/exceptions.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/advanced/exceptions.rst b/docs/advanced/exceptions.rst index a4a282162a..8660bcfdee 100644 --- a/docs/advanced/exceptions.rst +++ b/docs/advanced/exceptions.rst @@ -331,17 +331,17 @@ 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. +Wrappers for handling Python warnings are implemented in ``pybind11/warnings.h``, +which must be ``#include``ed explicitly (in other words, it is not transitively +included with ``pybind11/pybind11.h``). -Warnings can be raised with ``warn`` function: +Warnings can be raised with the ``warn`` function: .. code-block:: cpp py::warnings::warn("This is warning!", PyExc_Warning); - // When calling `stack_level` can be specified as well. + // Optionally, `stack_level` can be specified. py::warnings::warn("Another one!", PyExc_DeprecationWarning, 3); New warning types can be registered on the module level with ``new_warning_type``: @@ -350,8 +350,6 @@ New warning types can be registered on the module level with ``new_warning_type` py::warnings::new_warning_type(m, "CustomWarning", PyExc_RuntimeWarning); -.. versionadded:: 2.14 - Chaining exceptions ('raise from') ================================== From b42f2af09079a909aede4589422dee6df29dc805 Mon Sep 17 00:00:00 2001 From: jiwaszki Date: Tue, 1 Oct 2024 00:35:41 +0200 Subject: [PATCH 4/4] Fix issue with docs --- docs/advanced/exceptions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/exceptions.rst b/docs/advanced/exceptions.rst index 8660bcfdee..2de70c9488 100644 --- a/docs/advanced/exceptions.rst +++ b/docs/advanced/exceptions.rst @@ -332,8 +332,8 @@ Handling warnings from the Python C API ===================================== Wrappers for handling Python warnings are implemented in ``pybind11/warnings.h``, -which must be ``#include``ed explicitly (in other words, it is not transitively -included with ``pybind11/pybind11.h``). +which means that ``#include`` must be added explicitly (in other words, it is not +transitively included with ``pybind11/pybind11.h``). Warnings can be raised with the ``warn`` function: