PEP 565: Fix footnotes (#2741)

Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
Hugo van Kemenade 2022-08-04 11:42:03 +03:00 committed by GitHub
parent f74f32b030
commit 7f4e764885
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 34 deletions

View File

@ -14,14 +14,14 @@ Abstract
======== ========
In Python 2.7 and Python 3.2, the default warning filters were updated to hide 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 ``DeprecationWarning`` by default, such that deprecation warnings in development
tools that were themselves written in Python (e.g. linters, static analysers, tools that were themselves written in Python (e.g. linters, static analysers,
test runners, code generators), as well as any other applications that merely 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 happened to be written in Python, wouldn't be visible to their users unless
those users explicitly opted in to seeing them. those users explicitly opted in to seeing them.
However, this change has had the unfortunate side effect of making However, this change has had the unfortunate side effect of making
DeprecationWarning markedly less effective at its primary intended purpose: ``DeprecationWarning`` markedly less effective at its primary intended purpose:
providing advance notice of breaking changes in APIs (whether in CPython, the providing advance notice of breaking changes in APIs (whether in CPython, the
standard library, or in third party libraries) to users of those APIs. standard library, or in third party libraries) to users of those APIs.
@ -74,10 +74,10 @@ to be::
This means that in cases where the nominal location of the warning (as This means that in cases where the nominal location of the warning (as
determined by the ``stacklevel`` parameter to ``warnings.warn``) is in the determined by the ``stacklevel`` parameter to ``warnings.warn``) is in the
``__main__`` module, the first occurrence of each DeprecationWarning will once ``__main__`` module, the first occurrence of each ``DeprecationWarning`` will once
again be reported. again be reported.
This change will lead to DeprecationWarning being displayed by default for: This change will lead to ``DeprecationWarning`` being displayed by default for:
* code executed directly at the interactive prompt * code executed directly at the interactive prompt
* code executed directly as part of a single-file script * code executed directly as part of a single-file script
@ -164,7 +164,7 @@ no changes are needed beyond those in this PEP.
Interactive shell implementations which use a namespace other than Interactive shell implementations which use a namespace other than
``__main__`` will need to add their own filter. For example, IPython uses the ``__main__`` will need to add their own filter. For example, IPython uses the
following command ([8_]) to set up a suitable filter:: following command ([6]_) to set up a suitable filter::
warnings.filterwarnings("default", category=DeprecationWarning, warnings.filterwarnings("default", category=DeprecationWarning,
module=self.user_ns.get("__name__")) module=self.user_ns.get("__name__"))
@ -215,8 +215,8 @@ of the related documentation.
Reference Implementation Reference Implementation
======================== ========================
A reference implementation is available in the PR [4_] linked from the A reference implementation is available in the PR [4]_ linked from the
related tracker issue for this PEP [5_]. related tracker issue for this PEP [5]_.
As a side-effect of implementing this PEP, the internal warnings filter list As a side-effect of implementing this PEP, the internal warnings filter list
will start allowing the use of plain strings as part of filter definitions (in will start allowing the use of plain strings as part of filter definitions (in
@ -229,7 +229,7 @@ early access to the ``re`` module.
Motivation Motivation
========== ==========
As discussed in [1_] and mentioned in [2_], Python 2.7 and Python 3.2 changed As discussed in [1]_ and mentioned in [2]_, Python 2.7 and Python 3.2 changed
the default handling of ``DeprecationWarning`` such that: the default handling of ``DeprecationWarning`` such that:
* the warning was hidden by default during normal code execution * the warning was hidden by default during normal code execution
@ -274,7 +274,7 @@ Limitations on PEP Scope
This PEP exists specifically to explain both the proposed addition to the This PEP exists specifically to explain both the proposed addition to the
default warnings filter for 3.7, *and* to more clearly articulate the rationale default warnings filter for 3.7, *and* to more clearly articulate the rationale
for the original change to the handling of DeprecationWarning back in Python 2.7 for the original change to the handling of ``DeprecationWarning`` back in Python 2.7
and 3.2. and 3.2.
This PEP does not solve all known problems with the current approach to handling This PEP does not solve all known problems with the current approach to handling
@ -289,7 +289,7 @@ deprecation warnings. Most notably:
variable. variable.
* The standard library doesn't provide a straightforward way to opt-in to seeing * The standard library doesn't provide a straightforward way to opt-in to seeing
all warnings emitted *by* a particular dependency prior to upgrading it all warnings emitted *by* a particular dependency prior to upgrading it
(the third-party ``warn`` module [3_] does provide this, but enabling it (the third-party ``warn`` module [3]_ does provide this, but enabling it
involves monkeypatching the standard library's ``warnings`` module). involves monkeypatching the standard library's ``warnings`` module).
* When software has been factored out into support modules, but those modules * When software has been factored out into support modules, but those modules
have little or no automated test coverage, re-enabling deprecation warnings have little or no automated test coverage, re-enabling deprecation warnings
@ -321,12 +321,12 @@ changes in 3.7:
* a new ``-X dev`` command line option that combines several developer centric * a new ``-X dev`` command line option that combines several developer centric
settings (including ``-Wd``) into one command line flag: settings (including ``-Wd``) into one command line flag:
https://bugs.python.org/issue32043 https://github.com/python/cpython/issues/76224
* changing the behaviour in debug builds to show more of the warnings that are * changing the behaviour in debug builds to show more of the warnings that are
off by default in regular interpreter builds: https://bugs.python.org/issue32088 off by default in regular interpreter builds: https://github.com/python/cpython/issues/76269
Independently of the proposed changes to the default filters in this PEP, Independently of the proposed changes to the default filters in this PEP,
issue 32229 [9_] is a proposal to add a ``warnings.hide_warnings`` API to issue 32229 [7]_ is a proposal to add a ``warnings.hide_warnings`` API to
make it simpler for application developers to hide warnings during normal make it simpler for application developers to hide warnings during normal
operation, while easily making them visible when testing. operation, while easily making them visible when testing.
@ -347,32 +347,21 @@ References
(https://github.com/python/cpython/pull/4458) (https://github.com/python/cpython/pull/4458)
.. [5] Tracker issue for PEP 565 implementation .. [5] Tracker issue for PEP 565 implementation
(https://bugs.python.org/issue31975) (https://github.com/python/cpython/issues/76156)
.. [6] First python-dev discussion thread .. [6] IPython's ``DeprecationWarning`` auto-configuration
(https://mail.python.org/pipermail/python-dev/2017-November/150477.html)
.. [7] Second python-dev discussion thread
(https://mail.python.org/pipermail/python-dev/2017-November/150819.html)
.. [8] IPython's DeprecationWarning auto-configuration
(https://github.com/ipython/ipython/blob/6.2.x/IPython/core/interactiveshell.py#L619) (https://github.com/ipython/ipython/blob/6.2.x/IPython/core/interactiveshell.py#L619)
.. [9] ``warnings.hide_warnings`` API proposal .. [7] ``warnings.hide_warnings`` API proposal
(https://bugs.python.org/issue32229) (https://github.com/python/cpython/issues/76410)
* `First python-dev discussion thread
<https://mail.python.org/pipermail/python-dev/2017-November/150477.html>`__
* `Second python-dev discussion thread
<https://mail.python.org/pipermail/python-dev/2017-November/150819.html>`__
Copyright Copyright
========= =========
This document has been placed in the public domain. This document has been placed in the public domain.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End: