bpo-39429: Add a new "Python Development Mode" doc page #18132
Conversation
Doc/library/devmode.rst
Outdated
| * Add ``default`` :ref:`warning filter <describing-warning-filters>`, as | ||
| :option:`-W default <-W>` command line option. The following warnings are | ||
| shown, whereas they are ignored by the default warning filters: | ||
|
|
||
| * :exc:`DeprecationWarning`; | ||
| * :exc:`ImportWarning`; | ||
| * :exc:`PendingDeprecationWarning`; | ||
| * :exc:`ResourceWarning`. |
There was a problem hiding this comment.
Hmm, the wording of this section isn't entirely clear to me. Is it explaining that the listed warnings are not filtered in development mode, so they're shown instead of hidden? Also, that to re-use the default warning filters, a new command-line option "-W default" has been added?
I had to read over this part a few times, and I'm still not 100% certain that I'm quite getting it.
If I'm correctly understanding it, I'd recommend restructuring it a bit to make that more clear (might need to adjust line width):
Normally, the following warnings are filtered by the default
:ref:`warning filters <describing-warning-filters>`:
* :exc:`DeprecationWarning`;
* :exc:`ImportWarning`;
* :exc:`PendingDeprecationWarning`;
* :exc:`ResourceWarning`.
In development mode, these warnings are no longer filtered. To re-enable the default
warning filters, use the new :option:`-W default <-W>` command line option.
(Correct me if I'm misunderstanding the section)
There was a problem hiding this comment.
I rewrote this section.
Doc/library/devmode.rst
Outdated
|
|
||
| * Enable :ref:`asyncio debug mode <asyncio-debug-mode>`. Similar to setting | ||
| :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``. | ||
| * Check *encoding* and *errors* arguments on string encoding and decoding |
There was a problem hiding this comment.
| * Check *encoding* and *errors* arguments on string encoding and decoding | |
| * Check the *encoding* and *errors* arguments for string encoding and decoding |
|
Also, thanks for adding this highly informative section, @vstinner! I actually learned a decent amount about the development mode that I wasn't previously aware of while proofreading it. |
Doc/library/devmode.rst
Outdated
|
|
||
| The Python Development Mode introduces additional runtime checks which are too | ||
| expensive to be enabled by default. It should not be more verbose than the | ||
| default if the code is correct: new warnings are only emitted when an issue is |
There was a problem hiding this comment.
The colon should probably be a semi-colon.
|
This is amazing. Thank you! Big +1. |
Doc/library/devmode.rst
Outdated
| * Add ``default`` :ref:`warning filter <describing-warning-filters>`, as | ||
| :option:`-W default <-W>` command line option. The following warnings are | ||
| shown, whereas they are ignored by the default warning filters: | ||
|
|
||
| * :exc:`DeprecationWarning`; | ||
| * :exc:`ImportWarning`; | ||
| * :exc:`PendingDeprecationWarning`; | ||
| * :exc:`ResourceWarning`. |
There was a problem hiding this comment.
I rewrote this section.
One last remaining change in L92-L93 of Doc/library/devmode.rst:
The Python Development Mode does not prevent the :option:`-O` command line option to
remove :keyword:`assert` statements nor to set :const:`__debug__` to ``False``.
to
The Python Development Mode does not prevent the :option:`-O` command line
option from removing :keyword:`assert` statements nor from setting
:const:`__debug__` to ``False``.
(Grammar and line width fix)
Other than that, LGTM! Thanks @vstinner.
Truncate also long lines
fixed |
https://bugs.python.org/issue39429