diff --git a/pep-0565.rst b/pep-0565.rst index ee7a0b0e4..9082e2d3d 100644 --- a/pep-0565.rst +++ b/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 + `__ + +* `Second python-dev discussion thread + `__ 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: