Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation entry for warnings #5356

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Add documentation entry for warnings #5356

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7266988
[docs] Add entry for warnings
jiwaszki Sep 5, 2024
2fbd013
Fix code formatting
jiwaszki Sep 5, 2024
706ece4
Update docs
jiwaszki Sep 30, 2024
b42f2af
Fix issue with docs
jiwaszki Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/advanced/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
=====================================
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please add a couple more =, to line up with the text above?

(I overlooked this before.)


Wrappers for handling Python warnings are implemented in ``pybind11/warnings.h``,
which means that ``#include`` must be added explicitly (in other words, it is not
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

which means is not correct here. It was a choice to not include warnings.h in pybind11.h. We just want to state that here, to be helpful.

Could you please change this to

which must be included explicitly?

transitively included with ``pybind11/pybind11.h``).

Warnings can be raised with the ``warn`` function:

.. code-block:: cpp

py::warnings::warn("This is warning!", PyExc_Warning);

// 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``:

.. code-block:: cpp

py::warnings::new_warning_type(m, "CustomWarning", PyExc_RuntimeWarning);

Chaining exceptions ('raise from')
==================================

Expand Down
Loading