Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9b99747

Browse files
ncoghlanncoghlan
authored
bpo-31975 (PEP 565): Show DeprecationWarning in __main__ (GH-4458)
- primary change is to add a new default filter entry for 'default::DeprecationWarning:__main__' - secondary change is an internal one to cope with plain strings in the warning module's internal filter list (this avoids the need to create a compiled regex object early on during interpreter startup) - assorted documentation updates, including many more examples of configuring the warnings settings - additional tests to ensure that both the pure Python and the C accelerated warnings modules have the expected default configuration
1 parent d138892 commit 9b99747

10 files changed

Lines changed: 333 additions & 124 deletions

File tree

‎Doc/library/exceptions.rst‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -661,11 +661,13 @@ depending on the system error code.
661661
:pep:`3151` - Reworking the OS and IO exception hierarchy
662662

663663

664+
.. _warning-categories-as-exceptions:
665+
664666
Warnings
665667
--------
666668

667-
The following exceptions are used as warning categories; see the :mod:`warnings`
668-
module for more information.
669+
The following exceptions are used as warning categories; see the
670+
:ref:`warning-categories` documentation for more details.
669671

670672
.. exception:: Warning
671673

@@ -679,12 +681,14 @@ module for more information.
679681

680682
.. exception:: DeprecationWarning
681683

682-
Base class for warnings about deprecated features.
684+
Base class for warnings about deprecated features when those warnings are
685+
intended for other Python developers.
683686

684687

685688
.. exception:: PendingDeprecationWarning
686689

687-
Base class for warnings about features which will be deprecated in the future.
690+
Base class for warnings about features which will be deprecated in the
691+
future.
688692

689693

690694
.. exception:: SyntaxWarning
@@ -699,8 +703,8 @@ module for more information.
699703

700704
.. exception:: FutureWarning
701705

702-
Base class for warnings about constructs that will change semantically in the
703-
future.
706+
Base class for warnings about deprecated features when those warnings are
707+
intended for end users of applications that are written in Python.
704708

705709

706710
.. exception:: ImportWarning
@@ -720,7 +724,8 @@ module for more information.
720724

721725
.. exception:: ResourceWarning
722726

723-
Base class for warnings related to resource usage.
727+
Base class for warnings related to resource usage. Ignored by the default
728+
warning filters.
724729

725730
.. versionadded:: 3.2
726731

‎Doc/library/warnings.rst‎

Lines changed: 156 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,17 @@ Warning Categories
5151
------------------
5252

5353
There are a number of built-in exceptions that represent warning categories.
54-
This categorization is useful to be able to filter out groups of warnings. The
55-
following warnings category classes are currently defined:
54+
This categorization is useful to be able to filter out groups of warnings.
55+
56+
While these are technically
57+
:ref:`built-in exceptions <warning-categories-as-exceptions>`, they are
58+
documented here, because conceptually they belong to the warnings mechanism.
59+
60+
User code can define additional warning categories by subclassing one of the
61+
standard warning categories. A warning category must always be a subclass of
62+
the :exc:`Warning` class.
63+
64+
The following warnings category classes are currently defined:
5665

5766
.. tabularcolumns:: |l|p{0.6\linewidth}|
5867

@@ -66,16 +75,20 @@ following warnings category classes are currently defined:
6675
| :exc:`UserWarning` | The default category for :func:`warn`. |
6776
+----------------------------------+-----------------------------------------------+
6877
| :exc:`DeprecationWarning` | Base category for warnings about deprecated |
69-
| | features (ignored by default). |
78+
| | features when those warnings are intended for |
79+
| | other Python developers (ignored by default, |
80+
| | unless triggered by code in ``__main__``). |
7081
+----------------------------------+-----------------------------------------------+
7182
| :exc:`SyntaxWarning` | Base category for warnings about dubious |
7283
| | syntactic features. |
7384
+----------------------------------+-----------------------------------------------+
7485
| :exc:`RuntimeWarning` | Base category for warnings about dubious |
7586
| | runtime features. |
7687
+----------------------------------+-----------------------------------------------+
77-
| :exc:`FutureWarning` | Base category for warnings about constructs |
78-
| | that will change semantically in the future. |
88+
| :exc:`FutureWarning` | Base category for warnings about deprecated |
89+
| | features when those warnings are intended for |
90+
| | end users of applications that are written in |
91+
| | Python. |
7992
+----------------------------------+-----------------------------------------------+
8093
| :exc:`PendingDeprecationWarning` | Base category for warnings about features |
8194
| | that will be deprecated in the future |
@@ -95,13 +108,12 @@ following warnings category classes are currently defined:
95108
| | resource usage. |
96109
+----------------------------------+-----------------------------------------------+
97110

98-
99-
While these are technically built-in exceptions, they are documented here,
100-
because conceptually they belong to the warnings mechanism.
101-
102-
User code can define additional warning categories by subclassing one of the
103-
standard warning categories. A warning category must always be a subclass of
104-
the :exc:`Warning` class.
111+
.. versionchanged:: 3.7
112+
Previously :exc:`DeprecationWarning` and :exc:`FutureWarning` were
113+
distinguished based on whether a feature was being removed entirely or
114+
changing its behaviour. They are now distinguished based on their
115+
intended audience and the way they're handled by the default warnings
116+
filters.
105117

106118

107119
.. _warning-filter:
@@ -114,7 +126,7 @@ into errors (raising an exception).
114126

115127
Conceptually, the warnings filter maintains an ordered list of filter
116128
specifications; any specific warning is matched against each filter
117-
specification in the list in turn until a match is found; the match determines
129+
specification in the list in turn until a match is found; the filter determines
118130
the disposition of the match. Each entry is a tuple of the form (*action*,
119131
*message*, *category*, *module*, *lineno*), where:
120132

@@ -123,19 +135,19 @@ the disposition of the match. Each entry is a tuple of the form (*action*,
123135
+---------------+----------------------------------------------+
124136
| Value | Disposition |
125137
+===============+==============================================+
138+
| ``"default"`` | print the first occurrence of matching |
139+
| | warnings for each location (module + |
140+
| | line number) where the warning is issued |
141+
+---------------+----------------------------------------------+
126142
| ``"error"`` | turn matching warnings into exceptions |
127143
+---------------+----------------------------------------------+
128144
| ``"ignore"`` | never print matching warnings |
129145
+---------------+----------------------------------------------+
130146
| ``"always"`` | always print matching warnings |
131147
+---------------+----------------------------------------------+
132-
| ``"default"`` | print the first occurrence of matching |
133-
| | warnings for each location where the warning |
134-
| | is issued |
135-
+---------------+----------------------------------------------+
136148
| ``"module"`` | print the first occurrence of matching |
137149
| | warnings for each module where the warning |
138-
| | is issued |
150+
| | is issued (regardless of line number) |
139151
+---------------+----------------------------------------------+
140152
| ``"once"`` | print only the first occurrence of matching |
141153
| | warnings, regardless of location |
@@ -157,41 +169,128 @@ the disposition of the match. Each entry is a tuple of the form (*action*,
157169
Since the :exc:`Warning` class is derived from the built-in :exc:`Exception`
158170
class, to turn a warning into an error we simply raise ``category(message)``.
159171

172+
If a warning is reported and doesn't match any registered filter then the
173+
"default" action is applied (hence its name).
174+
175+
176+
.. _describing-warning-filters:
177+
178+
Describing Warning Filters
179+
~~~~~~~~~~~~~~~~~~~~~~~~~~
180+
160181
The warnings filter is initialized by :option:`-W` options passed to the Python
161-
interpreter command line. The interpreter saves the arguments for all
162-
:option:`-W` options without interpretation in ``sys.warnoptions``; the
163-
:mod:`warnings` module parses these when it is first imported (invalid options
164-
are ignored, after printing a message to ``sys.stderr``).
182+
interpreter command line and the :envvar:`PYTHONWARNINGS` environment variable.
183+
The interpreter saves the arguments for all supplied entries without
184+
interpretation in ``sys.warnoptions``; the :mod:`warnings` module parses these
185+
when it is first imported (invalid options are ignored, after printing a
186+
message to ``sys.stderr``).
187+
188+
Individual warnings filters are specified as a sequence of fields separated by
189+
colons::
165190

191+
action:message:category:module:line
166192

167-
Default Warning Filters
168-
~~~~~~~~~~~~~~~~~~~~~~~
193+
The meaning of each of these fields is as described in :ref:`warning-filter`.
194+
When listing multiple filters on a single line (as for
195+
:envvar:`PYTHONWARNINGS`), the individual filters are separated by commas,and
196+
the filters listed later take precedence over those listed before them (as
197+
they're applied left-to-right, and the most recently applied filters take
198+
precedence over earlier ones).
199+
200+
Commonly used warning filters apply to either all warnings, warnings in a
201+
particular category, or warnings raised by particular modules or packages.
202+
Some examples::
203+
204+
default # Show all warnings (even those ignored by default)
205+
ignore # Ignore all warnings
206+
error # Convert all warnings to errors
207+
error::ResourceWarning # Treat ResourceWarning messages as errors
208+
default::DeprecationWarning # Show DeprecationWarning messages
209+
ignore,default:::mymodule # Only report warnings triggered by "mymodule"
210+
error:::mymodule[.*] # Convert warnings to errors in "mymodule"
211+
# and any subpackages of "mymodule"
212+
213+
214+
.. _default-warning-filter:
215+
216+
Default Warning Filter
217+
~~~~~~~~~~~~~~~~~~~~~~
169218

170219
By default, Python installs several warning filters, which can be overridden by
171-
the command-line options passed to :option:`-W` and calls to
172-
:func:`filterwarnings`.
220+
the :option:`-W` command-line option, the :envvar:`PYTHONWARNINGS` environment
221+
variable and calls to :func:`filterwarnings`.
173222

174-
* :exc:`DeprecationWarning` and :exc:`PendingDeprecationWarning`, and
175-
:exc:`ImportWarning` are ignored.
223+
In regular release builds, the default warning filter has the following entries
224+
(in order of precedence)::
176225

177-
* :exc:`BytesWarning` is ignored unless the :option:`-b` option is given once or
178-
twice; in this case this warning is either printed (``-b``) or turned into an
179-
exception (``-bb``).
226+
default::DeprecationWarning:__main__
227+
ignore::DeprecationWarning
228+
ignore::PendingDeprecationWarning
229+
ignore::ImportWarning
230+
ignore::ResourceWarning
180231

181-
* :exc:`ResourceWarning` is ignored unless Python was built in debug mode.
232+
In debug builds, the list of default warning filters is empty.
182233

183234
.. versionchanged:: 3.2
184235
:exc:`DeprecationWarning` is now ignored by default in addition to
185236
:exc:`PendingDeprecationWarning`.
186237

238+
.. versionchanged:: 3.7
239+
:exc:`DeprecationWarning` is once again shown by default when triggered
240+
directly by code in ``__main__``.
241+
242+
.. versionchanged:: 3.7
243+
:exc:`BytesWarning` no longer appears in the default filter list and is
244+
instead configured via :data:`sys.warnoptions` when :option:`-b` is specified
245+
twice.
246+
247+
248+
.. _warning-disable:
249+
250+
Overriding the default filter
251+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
252+
253+
Developers of applications written in Python may wish to hide *all* Python level
254+
warnings from their users by default, and only display them when running tests
255+
or otherwise working on the application. The :data:`sys.warnoptions` attribute
256+
used to pass filter configurations to the interpreter can be used as a marker to
257+
indicate whether or not warnings should be disabled::
258+
259+
import sys
260+
261+
if not sys.warnoptions:
262+
import warnings
263+
warnings.simplefilter("ignore")
264+
265+
Developers of test runners for Python code are advised to instead ensure that
266+
*all* warnings are displayed by default for the code under test, using code
267+
like::
268+
269+
import sys
270+
271+
if not sys.warnoptions:
272+
import os, warnings
273+
warnings.simplefilter("default") # Change the filter in this process
274+
os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses
275+
276+
Finally, developers of interactive shells that run user code in a namespace
277+
other than ``__main__`` are advised to ensure that :exc:`DeprecationWarning`
278+
messages are made visible by default, using code like the following (where
279+
``user_ns`` is the module used to execute code entered interactively)::
280+
281+
import warnings
282+
warnings.filterwarnings("default", category=DeprecationWarning,
283+
module=user_ns.get("__name__"))
284+
187285

188286
.. _warning-suppress:
189287

190288
Temporarily Suppressing Warnings
191289
--------------------------------
192290

193291
If you are using code that you know will raise a warning, such as a deprecated
194-
function, but do not want to see the warning, then it is possible to suppress
292+
function, but do not want to see the warning (even when warnings have been
293+
explicitly configured via the command line), then it is possible to suppress
195294
the warning using the :class:`catch_warnings` context manager::
196295

197296
import warnings
@@ -261,38 +360,30 @@ entries from the warnings list before each new operation).
261360

262361
.. _warning-ignored:
263362

264-
Updating Code For New Versions of Python
265-
----------------------------------------
266-
267-
Warnings that are only of interest to the developer are ignored by default. As
268-
such you should make sure to test your code with typically ignored warnings
269-
made visible. You can do this from the command-line by passing :option:`-Wd <-W>`
270-
to the interpreter (this is shorthand for :option:`!-W default`). This enables
271-
default handling for all warnings, including those that are ignored by default.
272-
To change what action is taken for encountered warnings you simply change what
273-
argument is passed to :option:`-W`, e.g. :option:`!-W error`. See the
274-
:option:`-W` flag for more details on what is possible.
275-
276-
To programmatically do the same as :option:`!-Wd`, use::
277-
278-
warnings.simplefilter('default')
279-
280-
Make sure to execute this code as soon as possible. This prevents the
281-
registering of what warnings have been raised from unexpectedly influencing how
282-
future warnings are treated.
283-
284-
Having certain warnings ignored by default is done to prevent a user from
285-
seeing warnings that are only of interest to the developer. As you do not
286-
necessarily have control over what interpreter a user uses to run their code,
287-
it is possible that a new version of Python will be released between your
288-
release cycles. The new interpreter release could trigger new warnings in your
289-
code that were not there in an older interpreter, e.g.
290-
:exc:`DeprecationWarning` for a module that you are using. While you as a
291-
developer want to be notified that your code is using a deprecated module, to a
292-
user this information is essentially noise and provides no benefit to them.
293-
294-
The :mod:`unittest` module has been also updated to use the ``'default'``
295-
filter while running tests.
363+
Updating Code For New Versions of Dependencies
364+
----------------------------------------------
365+
366+
Warning categories that are primarily of interest to Python developers (rather
367+
than end users of applications written in Python) are ignored by default.
368+
369+
Notably, this "ignored by default" list includes :exc:`DeprecationWarning`
370+
(for every module except ``__main__``), which means developers should make sure
371+
to test their code with typically ignored warnings made visible in order to
372+
receive timely notifications of future breaking API changes (whether in the
373+
standard library or third party packages).
374+
375+
In the ideal case, the code will have a suitable test suite, and the test runner
376+
will take care of implicitly enabling all warnings when running tests
377+
(the test runner provided by the :mod:`unittest` module does this).
378+
379+
In less ideal cases, applications can be checked for use of deprecated
380+
interfaces by passing :option:`-Wd <-W>` to the Python interpreter (this is
381+
shorthand for :option:`!-W default`) or setting ``PYTHONWARNINGS=default`` in
382+
the environment. This enables default handling for all warnings, including those
383+
that are ignored by default. To change what action is taken for encountered
384+
warnings you can change what argument is passed to :option:`-W` (e.g.
385+
:option:`!-W error`). See the :option:`-W` flag for more details on what is
386+
possible.
296387

297388

298389
.. _warning-functions:

‎Doc/tools/susp-ignored.csv‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -259,12 +259,8 @@ tutorial/stdlib2,,:start,extra = data[start:start+extra_size]
259259
tutorial/stdlib2,,:start,"fields = struct.unpack('<IIIHH', data[start:start+16])"
260260
tutorial/stdlib2,,:start,filename = data[start:start+filenamesize]
261261
tutorial/stdlib2,,:Warning,WARNING:root:Warning:config file server.conf not found
262-
using/cmdline,,:category,action:message:category:module:line
263262
using/cmdline,,:errorhandler,:errorhandler
264-
using/cmdline,,:line,action:message:category:module:line
265263
using/cmdline,,:line,file:line: category: message
266-
using/cmdline,,:message,action:message:category:module:line
267-
using/cmdline,,:module,action:message:category:module:line
268264
using/unix,,:Packaging,https://en.opensuse.org/Portal:Packaging
269265
whatsnew/2.0,,:len,
270266
whatsnew/2.3,,::,
@@ -302,6 +298,20 @@ whatsnew/3.2,,:prefix,zope-conf = ${custom:prefix}/etc/zope.conf
302298
library/re,,`,!#$%&'*+-.^_`|~:
303299
library/re,,`,!\#\$%\&'\*\+\-\.\^_`\|\~:
304300
library/tarfile,,:xz,'x:xz'
301+
library/warnings,,:message,action:message:category:module:line
302+
library/warnings,,:category,action:message:category:module:line
303+
library/warnings,,:module,action:message:category:module:line
304+
library/warnings,,:line,action:message:category:module:line
305+
library/warnings,,::,error::ResourceWarning
306+
library/warnings,,::,default::DeprecationWarning
307+
library/warnings,,::,default:::mymodule
308+
library/warnings,,:mymodule,default:::mymodule
309+
library/warnings,,::,error:::mymodule
310+
library/warnings,,:mymodule,error:::mymodule
311+
library/warnings,,::,ignore::DeprecationWarning
312+
library/warnings,,::,ignore::PendingDeprecationWarning
313+
library/warnings,,::,ignore::ImportWarning
314+
library/warnings,,::,ignore::ResourceWarning
305315
library/xml.etree.elementtree,,:sometag,prefix:sometag
306316
library/xml.etree.elementtree,,:fictional,"<actors xmlns:fictional=""http://characters.example.com"""
307317
library/xml.etree.elementtree,,:character,<fictional:character>Lancelot</fictional:character>
@@ -330,3 +340,4 @@ whatsnew/3.7,,`,'`'
330340
whatsnew/3.7,,::,error::BytesWarning
331341
whatsnew/changelog,,::,error::BytesWarning
332342
whatsnew/changelog,,::,default::BytesWarning
343+
whatsnew/changelog,,::,default::DeprecationWarning

0 commit comments

Comments
 (0)