From 3e6630877dea0425b46ebfbf7eba1436d41d4a3e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 14 Apr 2024 16:35:25 +0300 Subject: [PATCH] Infra: Add directives to show warning banner for deprecated PEPs (#3682) Co-authored-by: C.A.M. Gerlach --- pep_sphinx_extensions/__init__.py | 3 ++ .../parsing/pep_banner_directive.py | 31 +++++++++++++++++++ peps/pep-0003.rst | 25 +++++---------- peps/pep-0009.rst | 26 +++------------- peps/pep-0042.rst | 20 +++--------- peps/pep-0103.rst | 29 ++++------------- peps/pep-0204.rst | 27 +++++++--------- peps/pep-0206.rst | 11 +------ peps/pep-0209.rst | 2 +- peps/pep-0210.rst | 9 +----- peps/pep-0211.rst | 4 +-- peps/pep-0215.rst | 2 +- peps/pep-0216.rst | 10 ++---- peps/pep-0220.rst | 2 +- peps/pep-0224.rst | 5 ++- peps/pep-0225.rst | 4 +-- peps/pep-0239.rst | 29 +++++++---------- peps/pep-0241.rst | 10 +----- peps/pep-0242.rst | 27 +++++++--------- peps/pep-0363.rst | 17 +++------- peps/pep-0426.rst | 26 ++++++---------- 21 files changed, 121 insertions(+), 198 deletions(-) diff --git a/pep_sphinx_extensions/__init__.py b/pep_sphinx_extensions/__init__.py index f3aaa8ea8..42d3069c9 100644 --- a/pep_sphinx_extensions/__init__.py +++ b/pep_sphinx_extensions/__init__.py @@ -75,6 +75,9 @@ def setup(app: Sphinx) -> dict[str, bool]: "canonical-pypa-spec", pep_banner_directive.CanonicalPyPASpecBanner) app.add_directive( "canonical-typing-spec", pep_banner_directive.CanonicalTypingSpecBanner) + app.add_directive("rejected", pep_banner_directive.RejectedBanner) + app.add_directive("superseded", pep_banner_directive.SupersededBanner) + app.add_directive("withdrawn", pep_banner_directive.WithdrawnBanner) # Register event callbacks app.connect("builder-inited", _update_config_for_builder) # Update configuration values for builder used diff --git a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py index 00e6af504..fa1475787 100644 --- a/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py +++ b/pep_sphinx_extensions/pep_processor/parsing/pep_banner_directive.py @@ -125,3 +125,34 @@ class CanonicalTypingSpecBanner(PEPBanner): admonition_class = nodes.attention css_classes = ["canonical-typing-spec", "sticky-banner"] + + +class DeprecatedBanner(PEPBanner): + """Generic admonition for deprecated PEPs.""" + + admonition_class = nodes.warning + admonition_pre_template = "{link_content}" + admonition_pre_text = "This PEP has been deprecated." + css_classes = ["sticky-banner", "deprecated"] + + +class RejectedBanner(DeprecatedBanner): + """Insert an admonition for rejected PEPs.""" + + admonition_pre_text = "This PEP has been rejected." + css_classes = ["sticky-banner", "deprecated", "rejected"] + + +class SupersededBanner(PEPBanner): + """Insert an admonition for superseded PEPs.""" + + admonition_pre_template = "This PEP has been superseded by :pep:`{link_content}`." + admonition_pre_text = "This PEP has been superseded." + css_classes = ["sticky-banner", "deprecated", "superseded"] + + +class WithdrawnBanner(PEPBanner): + """Insert an admonition for withdrawn PEPs.""" + + admonition_pre_text = "This PEP has been withdrawn." + css_classes = ["sticky-banner", "deprecated", "withdrawn"] diff --git a/peps/pep-0003.rst b/peps/pep-0003.rst index 185f1adfa..e7b8f3146 100644 --- a/peps/pep-0003.rst +++ b/peps/pep-0003.rst @@ -3,27 +3,16 @@ Title: Guidelines for Handling Bug Reports Author: Jeremy Hylton Status: Withdrawn Type: Process -Content-Type: text/x-rst Created: 25-Sep-2000 Post-History: - -Introduction -============ - -This PEP contained guidelines for handling bug reports in the Python -bug tracker. It has been replaced by the Developer's Guide -description of issue triaging at - -:: - - https://docs.python.org/devguide/triaging.html - -Guidelines for people submitting Python bugs are at - -:: - - http://docs.python.org/bugs.html +.. withdrawn:: + This PEP contained guidelines for handling bug reports in the Python + bug tracker. It has been replaced by the + `Developer's Guide description of issue triaging + `_. + Guidelines for people submitting Python bugs are `in the Python docs + `__. Original Guidelines =================== diff --git a/peps/pep-0009.rst b/peps/pep-0009.rst index 107ed077d..255d6b749 100644 --- a/peps/pep-0009.rst +++ b/peps/pep-0009.rst @@ -1,25 +1,20 @@ PEP: 9 Title: Sample Plaintext PEP Template -Version: $Revision$ -Last-Modified: $Date$ Author: Barry Warsaw Status: Withdrawn Type: Process -Content-Type: text/x-rst Created: 14-Aug-2001 Post-History: Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/2YMHVPRDWGQLA5A2FKXE2JMLM2HQEEGW/ +.. withdrawn:: + As of 05-Jan-2016, this PEP is officially deprecated and replaced + by :pep:`12`. All PEPs should now use the reStructuredText format + described by :pep:`12`, and plaintext PEPs will no longer be + accepted. :: - Update - - As of 05-Jan-2016, this PEP is officially deprecated and replaced - by PEP 12. All PEPs should now use the reStructuredText format - described by PEP 12, and plaintext PEPs will no longer be - accepted. - Abstract This PEP provides a boilerplate or sample template for creating @@ -225,14 +220,3 @@ Resolution: https://mail.python.org/archives/list/python-dev@python.org/thread/2 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: diff --git a/peps/pep-0042.rst b/peps/pep-0042.rst index 23beb2b93..a03367584 100644 --- a/peps/pep-0042.rst +++ b/peps/pep-0042.rst @@ -1,18 +1,15 @@ PEP: 42 Title: Feature Requests -Version: $Revision$ -Last-Modified: $Date$ Author: Jeremy Hylton Status: Withdrawn Type: Process -Content-Type: text/x-rst Created: 12-Sep-2000 Post-History: - -.. note:: This PEP has been `withdrawn as obsolete`_. +.. withdrawn:: + This PEP has been `withdrawn as obsolete`_. All new feature requests should either go to the `Python bug tracker`_ - for very simple requests or the `python-ideas`_ mailing list for + for very simple requests or the `Ideas Discourse category`_ for everything else. The rest of this document is retained for historical purposes only. @@ -332,13 +329,6 @@ Building and Installing http://bugs.python.org/issue588756 -.. _`Python bug tracker`: https://bugs.python.org -.. _`python-ideas`: https://mail.python.org/mailman/listinfo/python-ideas +.. _`Python bug tracker`: https://github.com/python/cpython/issues +.. _`Ideas Discourse category`: https://discuss.python.org/c/ideas/6 .. _`withdrawn as obsolete`: https://github.com/python/peps/pull/108#issuecomment-249603204 - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - End: diff --git a/peps/pep-0103.rst b/peps/pep-0103.rst index c92469adc..9de515582 100644 --- a/peps/pep-0103.rst +++ b/peps/pep-0103.rst @@ -1,24 +1,19 @@ PEP: 103 Title: Collecting information about git -Version: $Revision$ -Last-Modified: $Date$ Author: Oleg Broytman Status: Withdrawn Type: Informational -Content-Type: text/x-rst Created: 01-Jun-2015 Post-History: 12-Sep-2015 -Withdrawal -========== +.. withdrawn:: + This PEP was withdrawn as it's too generic and doesn't really deals + with Python development. It is no longer updated. -This PEP was withdrawn as it's too generic and doesn't really deals -with Python development. It is no longer updated. + The content was moved to `Python Wiki`_. Make further updates in the + wiki. -The content was moved to `Python Wiki`_. Make further updates in the -wiki. - -.. _`Python Wiki`: https://wiki.python.org/moin/Git + .. _`Python Wiki`: https://wiki.python.org/moin/Git Abstract ======== @@ -1076,15 +1071,3 @@ 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: - vim: set fenc=us-ascii tw=70 : diff --git a/peps/pep-0204.rst b/peps/pep-0204.rst index cd7a7efcf..ab5d3bf27 100644 --- a/peps/pep-0204.rst +++ b/peps/pep-0204.rst @@ -3,11 +3,21 @@ Title: Range Literals Author: Thomas Wouters Status: Rejected Type: Standards Track -Content-Type: text/x-rst Created: 14-Jul-2000 Python-Version: 2.0 Post-History: +.. rejected:: + After careful consideration, and a period of meditation, this + proposal has been rejected. The open issues, as well as some + confusion between ranges and slice syntax, raised enough questions + for Guido not to accept it for Python 2.0, and later to reject the + proposal altogether. The new syntax and its intentions were deemed + not obvious enough. + + [ TBD: Guido, amend/confirm this, please. Preferably both; this + is a PEP, it should contain *all* the reasons for rejection + and/or reconsideration, for future reference. ] Introduction ============ @@ -270,21 +280,6 @@ Open issues made private functions? -Rejection -========= - -After careful consideration, and a period of meditation, this -proposal has been rejected. The open issues, as well as some -confusion between ranges and slice syntax, raised enough questions -for Guido not to accept it for Python 2.0, and later to reject the -proposal altogether. The new syntax and its intentions were deemed -not obvious enough. - -[ TBD: Guido, amend/confirm this, please. Preferably both; this -is a PEP, it should contain *all* the reasons for rejection -and/or reconsideration, for future reference. ] - - Copyright ========= diff --git a/peps/pep-0206.rst b/peps/pep-0206.rst index cfd19ba75..9c5ef35da 100644 --- a/peps/pep-0206.rst +++ b/peps/pep-0206.rst @@ -1,14 +1,12 @@ PEP: 206 Title: Python Advanced Library -Version: $Revision$ -Last-Modified: $Date$ Author: A.M. Kuchling Status: Withdrawn Type: Informational -Content-Type: text/x-rst Created: 14-Jul-2000 Post-History: +.. withdrawn:: Introduction ============ @@ -119,10 +117,3 @@ Acknowledgements The PEP is based on an earlier draft PEP by Moshe Zadka, titled "2.0 Batteries Included." - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - End: diff --git a/peps/pep-0209.rst b/peps/pep-0209.rst index c91a15f0a..1ef758002 100644 --- a/peps/pep-0209.rst +++ b/peps/pep-0209.rst @@ -3,11 +3,11 @@ Title: Multi-dimensional Arrays Author: Paul Barrett , Travis Oliphant Status: Withdrawn Type: Standards Track -Content-Type: text/x-rst Created: 03-Jan-2001 Python-Version: 2.2 Post-History: +.. withdrawn:: Abstract ======== diff --git a/peps/pep-0210.rst b/peps/pep-0210.rst index 68d1b49a9..526e3b9ec 100644 --- a/peps/pep-0210.rst +++ b/peps/pep-0210.rst @@ -3,15 +3,8 @@ Title: Decoupling the Interpreter Loop Author: David Ascher Status: Rejected Type: Standards Track -Content-Type: text/x-rst Created: 15-Jul-2000 Python-Version: 2.1 Post-History: - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - End: +.. rejected:: diff --git a/peps/pep-0211.rst b/peps/pep-0211.rst index da2358ba2..548026bc0 100644 --- a/peps/pep-0211.rst +++ b/peps/pep-0211.rst @@ -3,14 +3,12 @@ Title: Adding A New Outer Product Operator Author: Greg Wilson Status: Rejected Type: Standards Track -Content-Type: text/x-rst Created: 15-Jul-2000 Python-Version: 2.1 Post-History: -.. note:: - +.. rejected:: The approach in the later :pep:`465` was eventually accepted in lieu of this PEP. The :pep:`Rejected Ideas <465#rejected-alternatives-to-adding-a-new-operator>` diff --git a/peps/pep-0215.rst b/peps/pep-0215.rst index bdcdcf11f..df51b07ea 100644 --- a/peps/pep-0215.rst +++ b/peps/pep-0215.rst @@ -3,12 +3,12 @@ Title: String Interpolation Author: Ka-Ping Yee Status: Superseded Type: Standards Track -Content-Type: text/x-rst Created: 24-Jul-2000 Python-Version: 2.1 Post-History: Superseded-By: 292 +.. superseded:: 292 Abstract ======== diff --git a/peps/pep-0216.rst b/peps/pep-0216.rst index 497fc135c..92ee2b20b 100644 --- a/peps/pep-0216.rst +++ b/peps/pep-0216.rst @@ -1,19 +1,15 @@ PEP: 216 Title: Docstring Format Author: Moshe Zadka -Status: Rejected +Status: Withdrawn Type: Informational -Content-Type: text/x-rst Created: 31-Jul-2000 Post-History: Superseded-By: 287 -Notice -====== - -This PEP is rejected by the author. It has been superseded by PEP -287. +.. withdrawn:: + This PEP is withdrawn by the author. It has been superseded by :pep:`287`. Abstract diff --git a/peps/pep-0220.rst b/peps/pep-0220.rst index 9d9a47609..7b1aca80c 100644 --- a/peps/pep-0220.rst +++ b/peps/pep-0220.rst @@ -3,10 +3,10 @@ Title: Coroutines, Generators, Continuations Author: Gordon McMillan Status: Rejected Type: Informational -Content-Type: text/x-rst Created: 14-Aug-2000 Post-History: +.. rejected:: Abstract ======== diff --git a/peps/pep-0224.rst b/peps/pep-0224.rst index 2c7cd0a1f..00e128ebf 100644 --- a/peps/pep-0224.rst +++ b/peps/pep-0224.rst @@ -3,11 +3,13 @@ Title: Attribute Docstrings Author: Marc-André Lemburg Status: Rejected Type: Standards Track -Content-Type: text/x-rst Created: 23-Aug-2000 Python-Version: 2.1 Post-History: +.. rejected:: + This PEP has been rejected. + See :ref:`224-rejection` for more information. Introduction ============ @@ -173,6 +175,7 @@ docstring attribute and apply the above logic to it. Besides generating a docstring for an otherwise undocumented attribute there is no breakage. +.. _224-rejection: Comments from our BDFL ====================== diff --git a/peps/pep-0225.rst b/peps/pep-0225.rst index b66aadee8..f9a46bf9e 100644 --- a/peps/pep-0225.rst +++ b/peps/pep-0225.rst @@ -4,14 +4,12 @@ Author: Huaiyu Zhu , Gregory Lielens Status: Rejected Type: Standards Track -Content-Type: text/x-rst Created: 19-Sep-2000 Python-Version: 2.1 Post-History: -.. note:: - +.. rejected:: The approach in the later :pep:`465` was eventually accepted in lieu of this PEP. The :pep:`Rejected Ideas <465#rejected-alternatives-to-adding-a-new-operator>` diff --git a/peps/pep-0239.rst b/peps/pep-0239.rst index b56f4d89b..09417174c 100644 --- a/peps/pep-0239.rst +++ b/peps/pep-0239.rst @@ -1,15 +1,24 @@ PEP: 239 Title: Adding a Rational Type to Python -Version: $Revision$ -Last-Modified: $Date$ Author: Christopher A. Craig , Moshe Zadka Status: Rejected Type: Standards Track -Content-Type: text/x-rst Created: 11-Mar-2001 Python-Version: 2.2 Post-History: 16-Mar-2001 +.. rejected:: + This PEP is rejected. The needs outlined in the rationale section + have been addressed to some extent by the acceptance of :pep:`327` + for decimal arithmetic. Guido also noted, "Rational arithmetic + was the default 'exact' arithmetic in ABC and it did not work out as + expected". See the python-dev discussion on 17 June 2005 [1]_. + + *Postscript:* With the acceptance of :pep:`3141`, "A Type Hierarchy + for Numbers", a 'Rational' numeric abstract base class was added + with a concrete implementation in the 'fractions' module. + + Abstract ======== @@ -21,20 +30,6 @@ support such a type. This PEP suggests no literals for rational numbers; that is left for :pep:`another PEP <240>`. -BDFL Pronouncement -================== - -This PEP is rejected. The needs outlined in the rationale section -have been addressed to some extent by the acceptance of :pep:`327` -for decimal arithmetic. Guido also noted, "Rational arithmetic -was the default 'exact' arithmetic in ABC and it did not work out as -expected". See the python-dev discussion on 17 June 2005 [1]_. - -*Postscript:* With the acceptance of :pep:`3141`, "A Type Hierarchy -for Numbers", a 'Rational' numeric abstract base class was added -with a concrete implementation in the 'fractions' module. - - Rationale ========= diff --git a/peps/pep-0241.rst b/peps/pep-0241.rst index e82b2267b..a33fe4826 100644 --- a/peps/pep-0241.rst +++ b/peps/pep-0241.rst @@ -5,11 +5,11 @@ Discussions-To: distutils-sig@python.org Status: Superseded Type: Standards Track Topic: Packaging -Content-Type: text/x-rst Created: 12-Mar-2001 Post-History: `19-Mar-2001 `__ Superseded-By: 314 +.. superseded:: 314 Introduction ============ @@ -256,11 +256,3 @@ Copyright ========= This document has been placed in the public domain. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - End: diff --git a/peps/pep-0242.rst b/peps/pep-0242.rst index 92f383470..5c6d5df13 100644 --- a/peps/pep-0242.rst +++ b/peps/pep-0242.rst @@ -1,13 +1,22 @@ PEP: 242 Title: Numeric Kinds Author: Paul F. Dubois -Status: Rejected +Status: Withdrawn Type: Standards Track -Content-Type: text/x-rst Created: 17-Mar-2001 Python-Version: 2.2 Post-History: 17-Apr-2001 +.. withdrawn:: + This PEP has been closed by the author. The kinds module will not + be added to the standard library. + + There was no opposition to the proposal but only mild interest in + using it, not enough to justify adding the module to the standard + library. Instead, it will be made available as a separate + distribution item at the Numerical Python site. At the next + release of Numerical Python, it will no longer be a part of the + Numeric distribution. Abstract ======== @@ -217,20 +226,6 @@ Open Issues No open issues have been raised at this time. -Rejection -========= - -This PEP has been closed by the author. The kinds module will not -be added to the standard library. - -There was no opposition to the proposal but only mild interest in -using it, not enough to justify adding the module to the standard -library. Instead, it will be made available as a separate -distribution item at the Numerical Python site. At the next -release of Numerical Python, it will no longer be a part of the -Numeric distribution. - - Copyright ========= diff --git a/peps/pep-0363.rst b/peps/pep-0363.rst index 477e1b0ea..2b0630e4e 100644 --- a/peps/pep-0363.rst +++ b/peps/pep-0363.rst @@ -1,14 +1,14 @@ PEP: 363 Title: Syntax For Dynamic Attribute Access -Version: $Revision$ -Last-Modified: $Date$ Author: Ben North Status: Rejected Type: Standards Track -Content-Type: text/x-rst Created: 29-Jan-2007 Post-History: 12-Feb-2007 +.. rejected:: + This PEP has been rejected. + See :ref:`363-rejection` for more information. Abstract ======== @@ -172,6 +172,8 @@ of c.180 additional lines in the core code, and c.100 additional lines of tests. It is available as sourceforge patch #1657573 [1]_. +.. _363-rejection: + Mailing Lists Discussion ======================== @@ -249,12 +251,3 @@ 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: diff --git a/peps/pep-0426.rst b/peps/pep-0426.rst index 84b72a68c..7427d5e42 100644 --- a/peps/pep-0426.rst +++ b/peps/pep-0426.rst @@ -1,7 +1,5 @@ PEP: 426 Title: Metadata for Python Software Packages 2.0 -Version: $Revision$ -Last-Modified: $Date$ Author: Alyssa Coghlan , Daniel Holth , Donald Stufft @@ -10,7 +8,6 @@ Discussions-To: distutils-sig@python.org Status: Withdrawn Type: Informational Topic: Packaging -Content-Type: text/x-rst Requires: 440, 508, 518 Created: 30-Aug-2012 Post-History: 14-Nov-2012, 05-Feb-2013, 07-Feb-2013, 09-Feb-2013, @@ -18,19 +15,16 @@ Post-History: 14-Nov-2012, 05-Feb-2013, 07-Feb-2013, 09-Feb-2013, 21-Dec-2013 Replaces: 345 - -PEP Withdrawal -============== - -The ground-up metadata redesign proposed in this PEP has been withdrawn in -favour of the more modest proposal in :pep:`566`, which retains the basic -Key:Value format of previous metadata versions, but also defines a standardised -mechanism for translating that format to nested JSON-compatible data structures. - -Some of the ideas in this PEP (or the related :pep:`459`) may still be considered -as part of later proposals, but they will be handled in a more incremental -fashion, rather than as a single large proposed change with no feasible -migration plan. +.. withdrawn:: + The ground-up metadata redesign proposed in this PEP has been withdrawn in + favour of the more modest proposal in :pep:`566`, which retains the basic + Key:Value format of previous metadata versions, but also defines a standardised + mechanism for translating that format to nested JSON-compatible data structures. + + Some of the ideas in this PEP (or the related :pep:`459`) may still be considered + as part of later proposals, but they will be handled in a more incremental + fashion, rather than as a single large proposed change with no feasible + migration plan. Abstract