PEP 565: Update for python-dev discussion (#478)

pep-0565.rst

@@ -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
+test runners, code generators), as well as any other applications that merely
-explicitly opted in to seeing them.
+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
+developers of ``devtool``.
-developer tools that are used across more languages than just Python.
+
+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
+  (the request for third party test runners to change their default warnings
-  warnings filters was never made explicitly)
+  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
 =========