Zengtudor/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2024-11-24 14:15:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Add entry for warnings

Browse Source
This commit is contained in:
jiwaszki 2024-09-05 23:28:53 +02:00
parent 8a801bdc32
commit 7266988540
1 changed files with 24 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/advanced/exceptions.rst
View File

@ -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 <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')
==================================