@@ -15,8 +15,9 @@ Abstract

In Python 2.7 and Python 3.2, the default warning filters were updated to hide

DeprecationWarning by default, such that deprecation warnings in development

tools that were themselves written in Python (e.g. linters, static analysers,

test runners, code generators) wouldn't be visible to their users unless they

explicitly opted in to seeing them.

test runners, code generators), as well as any other applications that merely

happened to be written in Python, wouldn't be visible to their users unless

those users explicitly opted in to seeing them.

However, this change has had the unfortunate side effect of making

DeprecationWarning markedly less effective at its primary intended purpose:

@@ -115,6 +116,55 @@ support multiple Python versions: as a more reliably visible alternative to

``DeprecationWarning`` in Python 2.7 and versions of Python 3.x prior to 3.7.

Documentation Updates

=====================

The current reference documentation for the warnings system is relatively short

on specific *examples* of possible settings for the ``-W`` command line option

or the ``PYTHONWARNINGS`` environment variably that achieve particular end

results.

The following improvements are proposed as part of the implementation of this

PEP:

* Explicitly list the following entries under the description of the

``PYTHONWARNINGS`` environment variable::

PYTHONWARNINGS=error # Convert to exceptions

PYTHONWARNINGS=always # Warn every time

PYTHONWARNINGS=default # Warn once per call location

PYTHONWARNINGS=module # Warn once per calling module

PYTHONWARNINGS=once # Warn once per Python process

PYTHONWARNINGS=ignore # Never warn

* Explicitly list the corresponding short options

(``-We``, ``-Wa``, ``-Wd``, ``-Wm``,``-Wo``, ``-Wi``) for each of the

warning actions listed under the ``-W`` command line switch documentation

* Explicitly list the default filter set in the ``warnings`` module

documentation, using the ``action::category`` and ``action::category:module``

notation

* Explicitly list the following snippet in the ``warnings.simplefilter``

documentation as a recommended approach to turning off all warnings by

default in a Python application while still allowing them to be turned

back on via ``PYTHONWARNINGS`` or the ``-W`` command line switch::

if not sys.warnoptions:

warnings.simplefilter("ignore")

None of these are *new* (they already work in all still supported Python

versions), but they're not especially obvious given the current structure

of the related documentation.

Reference Implementation

========================

A reference implementation is available in the PR [4_] linked from the

related tracker issue for this PEP [5_].

Motivation

==========

@@ -134,15 +184,20 @@ The intent was to avoid cases of tooling output like the following::

Even when `devtool` is a tool specifically for Python programmers, this is not

a particularly useful warning, as it will be shown on every invocation, even

though the main helpful step an end user can take is to report a bug to the

developers of ``devtool``. The warning is even less helpful for general purpose

developer tools that are used across more languages than just Python.

developers of ``devtool``.

The warning is even less helpful for general purpose developer tools that are

used across more languages than just Python, and almost entirely \*un\*helpful

for applications that simply happen to be written in Python, and aren't

necessarily intended for a developer audience at all.

However, this change proved to have unintended consequences for the following

audiences:

* anyone using a test runner other than the default one built into ``unittest``

(since the request for third party test runners to change their default

warnings filters was never made explicitly)

(the request for third party test runners to change their default warnings

filters was never made explicitly, so many of them still rely on the

interpreter defaults that are designed to suit deployed applications)

* anyone using the default ``unittest`` test runner to test their Python code

in a subprocess (since even ``unittest`` only adjusts the warnings settings

in the current process)

@@ -200,6 +255,15 @@ inferring API deprecations from their contents was deemed to be an intractable

code analysis problem, and an explicit function and parameter marker syntax in

annotations was proposed instead.

The CPython reference implementation will also likely see the following related

changes in 3.7:

* a new ``-X dev`` command line option that combines several developer centric

settings (including ``-Wd``) into one command line flag:

https://bugs.python.org/issue32043

* changing the behaviour in debug builds to show more of the warnings that are

off by default in regular interpeter builds

References

==========

@@ -213,6 +277,16 @@ References

.. [3] Emitting warnings based on the location of the warning itself

(https://pypi.org/project/warn/)

.. [4] GitHub PR for PEP 565 implementation

(https://github.com/python/cpython/pull/4458)

.. [5] Tracker issue for PEP 565 implementation

(https://bugs.python.org/issue31975)

.. [6] python-dev discussion thread for this PEP

(https://mail.python.org/pipermail/python-dev/2017-November/150477.html)

Copyright

=========