Skip to content

PEP 565: Fix footnotes #2741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 4, 2022
Merged

PEP 565: Fix footnotes #2741

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a4b5e7b
PEP 565: Fix footnotes
hugovk Jul 28, 2022
3e09c60
PEP 565: Fix footnotes
hugovk Jul 28, 2022
09f2db0
PEP 565: Fix footnotes
hugovk Jul 28, 2022
aa707c8
PEP 565: Consistently format DeprecationWarning
hugovk Jul 28, 2022
a1a0d48
PEP 565: Replace BPO links with GitHub
hugovk Jul 28, 2022
8abea8c
PEP 565: Remove redundant emacs metadata
hugovk Jul 28, 2022
d08f7be
PEP 565: Make hyperlinks
hugovk Jul 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 22 additions & 33 deletions pep-0565.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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__"))
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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)
.. [6] IPython's ``DeprecationWarning`` auto-configuration
(https://github.com/ipython/ipython/blob/6.2.x/IPython/core/interactiveshell.py#L619)

.. [7] Second python-dev discussion thread
(https://mail.python.org/pipermail/python-dev/2017-November/150819.html)
.. [7] ``warnings.hide_warnings`` API proposal
(https://github.com/python/cpython/issues/76410)

.. [8] IPython's DeprecationWarning auto-configuration
(https://github.com/ipython/ipython/blob/6.2.x/IPython/core/interactiveshell.py#L619)
* `First python-dev discussion thread
<https://mail.python.org/pipermail/python-dev/2017-November/150477.html>`__

.. [9] ``warnings.hide_warnings`` API proposal
(https://bugs.python.org/issue32229)
* `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: