Add documentation entry for warnings #5356
Conversation
docs/advanced/exceptions.rst
Outdated
|
|
||
| py::warnings::new_warning_type(m, "CustomWarning", PyExc_RuntimeWarning); | ||
|
|
||
| .. versionadded:: 2.14 |
There was a problem hiding this comment.
@rwgk I cannot predict roadmap for versioning... is 2.14 okay?
There was a problem hiding this comment.
FYI, I'm switching employers (last day today, first day Monday). I'll try to get back here asap.
There was a problem hiding this comment.
@rwgk Congrats and my best wishes for your next chapter!
There was a problem hiding this comment.
Congrats and my best wishes for your next chapter!
Thanks!
.. versionadded:: 2.14
We only keep track of this in the Changelog. Please omit here.
docs/advanced/exceptions.rst
Outdated
| Handling warnings from the Python C API | ||
| ===================================== | ||
|
|
||
| Where possible, use :ref:`pybind11 warnings <warnings>` instead of calling |
There was a problem hiding this comment.
This :ref: does not work, just like the existing one above (line 307 here).
I don't know if you want to go in fixing the existing problem, up to you.
Here I'd simply write (i.e. replace this entire paragraph, lines 334-336, with):
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``).
There was a problem hiding this comment.
I have copied your text over (with small change to fit docs requirements, "I don't know if you want to go in fixing the existing problem" -- I would not get into it right now...:)).
docs/advanced/exceptions.rst
Outdated
|
|
||
| py::warnings::warn("This is warning!", PyExc_Warning); | ||
|
|
||
| // When calling `stack_level` can be specified as well. |
There was a problem hiding this comment.
// Optionally, `stack_level` can be specified.
There was a problem hiding this comment.
Got it! It's way simpler... 😄
docs/advanced/exceptions.rst
Outdated
|
|
||
| py::warnings::new_warning_type(m, "CustomWarning", PyExc_RuntimeWarning); | ||
|
|
||
| .. versionadded:: 2.14 |
There was a problem hiding this comment.
Congrats and my best wishes for your next chapter!
Thanks!
.. versionadded:: 2.14
We only keep track of this in the Changelog. Please omit here.
docs/advanced/exceptions.rst
Outdated
| 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: |
There was a problem hiding this comment.
I'd give it an extra "the":
Warnings can be raised with the ``warn`` function:
| ===================================== | ||
|
|
||
| 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 |
There was a problem hiding this comment.
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?
| @@ -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 | |||
| ===================================== | |||
There was a problem hiding this comment.
Could you please add a couple more =, to line up with the text above?
(I overlooked this before.)
Description
Documentation entry for #5291 - short explanation of new
py::warningsnamespace.