PEP 565: Fix footnotes (#2741)
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
Hugo van Kemenade
GitHub
parent
f74f32b030
commit
7f4e764885
57
pep-0565.rst
57
pep-0565.rst
|
|
@ -14,14 +14,14 @@ 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
|
||||
``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), 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:
|
||||
``DeprecationWarning`` markedly less effective at its primary intended purpose:
|
||||
providing advance notice of breaking changes in APIs (whether in CPython, the
|
||||
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
|
||||
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.
|
||||
|
||||
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 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
|
||||
``__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,
|
||||
module=self.user_ns.get("__name__"))
|
||||
|
|
@ -215,8 +215,8 @@ 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_].
|
||||
A reference implementation is available in the PR [4]_ linked from the
|
||||
related tracker issue for this PEP [5]_.
|
||||
|
||||
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
|
||||
|
|
@ -229,7 +229,7 @@ early access to the ``re`` module.
|
|||
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 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
|
||||
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.
|
||||
|
||||
This PEP does not solve all known problems with the current approach to handling
|
||||
|
|
@ -289,7 +289,7 @@ deprecation warnings. Most notably:
|
|||
variable.
|
||||
* 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
|
||||
(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).
|
||||
* When software has been factored out into support modules, but those modules
|
||||
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
|
||||
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
|
||||
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,
|
||||
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
|
||||
operation, while easily making them visible when testing.
|
||||
|
||||
|
|
@ -347,32 +347,21 @@ References
|
|||
(https://github.com/python/cpython/pull/4458)
|
||||
|
||||
.. [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
|
||||
(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
|
||||
.. [6] IPython's ``DeprecationWarning`` auto-configuration
|
||||
(https://github.com/ipython/ipython/blob/6.2.x/IPython/core/interactiveshell.py#L619)
|
||||
|
||||
.. [9] ``warnings.hide_warnings`` API proposal
|
||||
(https://bugs.python.org/issue32229)
|
||||
.. [7] ``warnings.hide_warnings`` API proposal
|
||||
(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
|
||||
=========
|
||||
|
||||
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue