@@ -37,10 +37,18 @@ The PEP also proposes a number of small adjustments to the reference
37 37
interpreter and standard library documentation to help make the warnings
38 38
subsystem more approachable for new Python developers.
39 39 40 +
As part of the documentation updates, it will be made clearer that the
41 +
``unittest`` test runner displays all warnings by default when executing
42 +
test cases, and that other test runners are advised to follow that example.
43 + 40 44 41 45
Specification
42 46
=============
43 47 48 + 49 +
New default warnings filter entry
50 +
---------------------------------
51 + 44 52
The current set of default warnings filters consists of::
45 53 46 54
ignore::DeprecationWarning
@@ -82,42 +90,87 @@ While continuing to be hidden by default for:
82 90
* code imported from an executable script wrapper generated at installation time
83 91
based on a ``console_scripts`` or ``gui_scripts`` entry point definition
84 92 85 -
As a result, API deprecation warnings encountered by development tools written
86 -
in Python should continue to be hidden by default for users of those tools
93 +
This means that tool developers that create an installable or executable
94 +
artifact (such as a ``zipapp`` archive) for distribution to their users
95 +
shouldn't see any change from the status quo, while users of more ad hoc
96 +
personal or locally distributed scripts are likely to start seeing relevant
97 +
deprecation warnings again (as they did in Python 2.6 and earlier).
98 + 99 + 100 +
Additional use case for ``FutureWarning``
101 +
-----------------------------------------
87 102 88 -
While not its originally intended purpose, the standard library documentation
89 -
will also be updated to explicitly recommend the use of ``FutureWarning`` (rather
90 -
than ``DeprecationWarning``) for backwards compatibility warnings that are
91 -
intended to be seen by *users* of an application.
103 +
The standard library documentation will be updated to explicitly recommend the
104 +
use of ``FutureWarning`` (rather than ``DeprecationWarning``) for backwards
105 +
compatibility warnings that are intended to be seen by *users* of an
106 +
application. (This will be in addition to the existing use of ``FutureWarning``
107 +
to warn about constructs that will remain valid code in the future,
108 +
but will have different semantics).
92 109 93 110
This will give the following three distinct categories of backwards
94 111
compatibility warning, with three different intended audiences:
95 112 96 -
* ``PendingDeprecationWarning``: reported by default only in test runners that
97 -
override the default set of warning filters. The intended audience is Python
98 -
developers that take an active interest in ensuring the future compatibility
99 -
of their software (e.g. professional Python application developers with
100 -
specific support obligations).
113 +
* ``PendingDeprecationWarning``: hidden by default for all code.
114 +
The intended audience is Python developers that take an active interest in
115 +
ensuring the future compatibility of their software (e.g. professional
116 +
Python application developers with specific support obligations).
101 117
* ``DeprecationWarning``: reported by default for code that runs directly in
102 118
the ``__main__`` module (as such code is considered relatively unlikely to
103 -
have a dedicated test suite), but relies on test suite based reporting for
104 -
code in other modules. The intended audience is Python developers that are at
105 -
risk of upgrades to their dependencies (including upgrades to Python itself)
106 -
breaking their software (e.g. developers using Python to script environments
107 -
where someone else is in control of the timing of dependency upgrades).
108 -
* ``FutureWarning``: always reported by default. The intended audience is users
109 -
of applications written in Python, rather than other Python developers
110 -
(e.g. warning about use of a deprecated setting in a configuration file
111 -
format).
119 +
have a dedicated test suite), but hidden by default for code in other modules.
120 +
The intended audience is Python developers that are at risk of upgrades to
121 +
their dependencies (including upgrades to Python itself) breaking their
122 +
software (e.g. developers using Python to script environments where someone
123 +
else is in control of the timing of dependency upgrades).
124 +
* ``FutureWarning``: reported by default for all code.
125 +
The intended audience is users of applications written in Python, rather than
126 +
other Python developers (e.g. warning about use of a deprecated setting in a
127 +
configuration file format).
128 + 129 +
For libraries and framework authors that want to ensure their API compatibility
130 +
warnings are more reliably seen by their users, the recommendation is to use a
131 +
custom warning class that derives from ``DeprecationWarning`` in Python 3.7+,
132 +
and from ``FutureWarning`` in earlier versions.
133 + 134 + 135 +
Recommended filter settings for test runners
136 +
--------------------------------------------
137 + 138 +
Developers of test runners are advised to implement logic equivalent to the
139 +
following when determining their default warnings filters::
140 + 141 +
if not sys.warnoptions:
142 +
warnings.simplefilter("default")
112 143 113 -
Given its presence in the standard library since Python 2.3, ``FutureWarning``
114 -
would then also have a secondary use case for libraries and frameworks that
115 -
support multiple Python versions: as a more reliably visible alternative to
116 -
``DeprecationWarning`` in Python 2.7 and versions of Python 3.x prior to 3.7.
144 +
This effectively enables all warnings by default, as if the ``-Wd`` command
145 +
line option had been passed.
117 146 147 +
Note that actually enabling ``BytesWarning`` in a test suite still requires
148 +
passing the ``-b`` option to the interpreter at the command line. For implicit
149 +
bytes conversion and bytes comparison warnings, the warnings filter machinery
150 +
is only used to determine whether they should be printed as warnings or raised
151 +
as exceptions - when the command line flag isn't set, the interpreter doesn't
152 +
even emit the warning in the first place.
118 153 119 -
Documentation Updates
120 -
=====================
154 + 155 +
Recommended filter settings for interactive shells
156 +
--------------------------------------------------
157 + 158 +
Developers of interactive shells are advised to add a filter that enables
159 +
``DeprecationWarning`` in the namespace where user code is entered and executed.
160 + 161 +
If that namespace is ``__main__`` (as it is for the default CPython REPL), then
162 +
no changes are needed beyond those in this PEP.
163 + 164 +
Interactive shell implementations which use a namespace other than
165 +
``__main__`` will need to add their own filter. For example, IPython uses the
166 +
following command ([8_]) to set up a suitable filter::
167 + 168 +
warnings.filterwarnings("default", category=DeprecationWarning,
169 +
module=self.user_ns.get("__name__"))
170 + 171 + 172 +
Other documentation updates
173 +
---------------------------
121 174 122 175
The current reference documentation for the warnings system is relatively short
123 176
on specific *examples* of possible settings for the ``-W`` command line option
@@ -226,18 +279,18 @@ and 3.2.
226 279
This PEP does not solve all known problems with the current approach to handling
227 280
deprecation warnings. Most notably:
228 281 229 -
* the default ``unittest`` test runner does not currently report deprecation
282 +
* The default ``unittest`` test runner does not currently report deprecation
230 283
warnings emitted at module import time, as the warnings filter override is only
231 284
put in place during test execution, not during test discovery and loading.
232 -
* the default ``unittest`` test runner does not currently report deprecation
285 +
* The default ``unittest`` test runner does not currently report deprecation
233 286
warnings in subprocesses, as the warnings filter override is applied directly
234 287
to the loaded ``warnings`` module, not to the ``PYTHONWARNINGS`` environment
235 288
variable.
236 -
* the standard library doesn't provide a straightforward way to opt-in to seeing
289 +
* The standard library doesn't provide a straightforward way to opt-in to seeing
237 290
all warnings emitted *by* a particular dependency prior to upgrading it
238 291
(the third-party ``warn`` module [3_] does provide this, but enabling it
239 292
involves monkeypatching the standard library's ``warnings`` module).
240 -
* re-enabling deprecation warnings by default in __main__ doesn't help in
293 +
* Re-enabling deprecation warnings by default in ``__main__`` doesn't help in
241 294
handling cases where software has been factored out into support modules, but
242 295
those modules still have little or no automated test coverage. Near term, the
243 296
best currently available answer is to run such applications with
@@ -247,7 +300,7 @@ deprecation warnings. Most notably:
247 300
working on static analysis of Python code: how to reliably find usage of
248 301
deprecated APIs, and how to infer that an API or parameter is deprecated
249 302
based on ``warnings.warn`` calls, without actually running either the code
250 -
providing the API or the code accessing it
303 +
providing the API or the code accessing it.
251 304 252 305
While these are real problems with the status quo, they're excluded from
253 306
consideration in this PEP because they're going to require more complex
@@ -290,9 +343,15 @@ References
290 343
.. [5] Tracker issue for PEP 565 implementation
291 344
(https://bugs.python.org/issue31975)
292 345 293 -
.. [6] python-dev discussion thread for this PEP
346 +
.. [6] First python-dev discussion thread
294 347
(https://mail.python.org/pipermail/python-dev/2017-November/150477.html)
295 348 349 +
.. [7] Second python-dev discussion thread
350 +
(https://mail.python.org/pipermail/python-dev/2017-November/150819.html)
351 + 352 +
.. [8] IPython's DeprecationWarning auto-configuration
353 +
(https://github.com/ipython/ipython/blob/6.2.x/IPython/core/interactiveshell.py#L619)
354 + 296 355 297 356
Copyright
298 357
=========
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4