From 8e5eba6cc4accd03d8660027f1dabca1e6f4c680 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 14 Jul 2024 15:54:42 +0200 Subject: [PATCH 1/9] Document the PEPs API --- peps/conf.py | 5 ++++- peps/contents.rst | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/peps/conf.py b/peps/conf.py index d23763b3430..6a98837eafa 100644 --- a/peps/conf.py +++ b/peps/conf.py @@ -30,7 +30,7 @@ ".rst": "pep", } -# List of patterns (relative to source dir) to ignore when looking for source files. +# List of patterns (relative to source dir) to include when looking for source files. include_patterns = [ # Required for Sphinx "contents.rst", @@ -38,9 +38,12 @@ "pep-????.rst", # PEP ancillary files "pep-????/*.rst", + # PEPs API + "api/*.rst", # Documentation "docs/*.rst", ] +# And to ignore when looking for source files. exclude_patterns = [ # PEP Template "pep-0012/pep-NNNN.rst", diff --git a/peps/contents.rst b/peps/contents.rst index d791f08f809..5d5c23ee3a6 100644 --- a/peps/contents.rst +++ b/peps/contents.rst @@ -15,4 +15,5 @@ This is an internal Sphinx page; please go to the :doc:`PEP Index `. :caption: PEP Table of Contents (needed for Sphinx): pep-* + api/* topic/* From 74d521432c178cbc4f1ef6d28d945e25f7368b57 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 14 Jul 2024 16:00:19 +0200 Subject: [PATCH 2/9] Format conf.py with Black --- .pre-commit-config.yaml | 10 +++++----- peps/conf.py | 19 ++++++++++--------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9ebe7b8dcf8..da6e98e9755 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -12,7 +12,7 @@ default_stages: [commit] repos: # General file checks and fixers - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v4.6.0 hooks: - id: mixed-line-ending name: "Normalize mixed line endings" @@ -43,17 +43,17 @@ repos: name: "Check YAML" - repo: https://github.com/psf/black-pre-commit-mirror - rev: 24.1.1 + rev: 24.4.2 hooks: - id: black name: "Format with Black" args: - '--target-version=py39' - '--target-version=py310' - files: 'pep_sphinx_extensions/tests/.*' + files: '^(peps/conf\.py|pep_sphinx_extensions/tests/.*)$' - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.2.1 + rev: v0.5.1 hooks: - id: ruff name: "Lint with Ruff" @@ -89,7 +89,7 @@ repos: # Manual codespell check - repo: https://github.com/codespell-project/codespell - rev: v2.2.6 + rev: v2.3.0 hooks: - id: codespell name: "Check for common misspellings in text files" diff --git a/peps/conf.py b/peps/conf.py index 6a98837eafa..9a747aa8fa1 100644 --- a/peps/conf.py +++ b/peps/conf.py @@ -54,14 +54,14 @@ # Intersphinx configuration intersphinx_mapping = { - 'python': ('https://docs.python.org/3/', None), - 'packaging': ('https://packaging.python.org/en/latest/', None), - 'typing': ('https://typing.readthedocs.io/en/latest/', None), - 'trio': ('https://trio.readthedocs.io/en/latest/', None), - 'devguide': ('https://devguide.python.org/', None), - 'py3.11': ('https://docs.python.org/3.11/', None), - 'py3.12': ('https://docs.python.org/3.12/', None), - 'py3.13': ('https://docs.python.org/3.13/', None), + "python": ("https://docs.python.org/3/", None), + "packaging": ("https://packaging.python.org/en/latest/", None), + "typing": ("https://typing.readthedocs.io/en/latest/", None), + "trio": ("https://trio.readthedocs.io/en/latest/", None), + "devguide": ("https://devguide.python.org/", None), + "py3.11": ("https://docs.python.org/3.11/", None), + "py3.12": ("https://docs.python.org/3.12/", None), + "py3.13": ("https://docs.python.org/3.13/", None), } intersphinx_disabled_reftypes = [] @@ -89,4 +89,5 @@ html_baseurl = "https://peps.python.org" # to create the CNAME file gettext_auto_build = False # speed-ups -templates_path = [os.fspath(_PSE_PATH / "pep_theme" / "templates")] # Theme template relative paths from `confdir` +# Theme template relative paths from `confdir` +templates_path = [os.fspath(_PSE_PATH / "pep_theme" / "templates")] From 2b110f3f21a88ecc4a5843f3b1e65f85ba624b53 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 14 Jul 2024 16:04:22 +0200 Subject: [PATCH 3/9] fixup! Document the PEPs API --- peps/contents.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/peps/contents.rst b/peps/contents.rst index 5d5c23ee3a6..d791f08f809 100644 --- a/peps/contents.rst +++ b/peps/contents.rst @@ -15,5 +15,4 @@ This is an internal Sphinx page; please go to the :doc:`PEP Index `. :caption: PEP Table of Contents (needed for Sphinx): pep-* - api/* topic/* From 937678823246e3f7e8664b48936a6786629376f8 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 14 Jul 2024 18:35:57 +0200 Subject: [PATCH 4/9] fixup! Document the PEPs API --- .../pep_zero_generator/writer.py | 7 ++ peps/api/index.rst | 64 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 peps/api/index.rst diff --git a/pep_sphinx_extensions/pep_zero_generator/writer.py b/pep_sphinx_extensions/pep_zero_generator/writer.py index f8232d0ceb0..e0507cc7f29 100644 --- a/pep_sphinx_extensions/pep_zero_generator/writer.py +++ b/pep_sphinx_extensions/pep_zero_generator/writer.py @@ -169,6 +169,13 @@ def write_pep0( self.emit_newline() self.emit_newline() + self.emit_title("API") + self.emit_text( + "The `PEPS API `__ is a JSON file of metadata about " + "all the published PEPs. :doc:`Read more here `." + ) + self.emit_newline() + # PEPs by category self.emit_title("Index by Category") meta, info, provisional, accepted, open_, finished, historical, deferred, dead = _classify_peps(peps) diff --git a/peps/api/index.rst b/peps/api/index.rst new file mode 100644 index 00000000000..a39b3a468ed --- /dev/null +++ b/peps/api/index.rst @@ -0,0 +1,64 @@ +PEPs API +======== + +There is a read-only API of published PEPs available at: + +* https://peps.python.org/api/peps.json + +The structure is like: + +.. code-block:: json + + { + "0": { + "number": 0, + "title": "Index of Python Enhancement Proposals (PEPs)", + "authors": "The PEP Editors", + "discussions_to": null, + "status": "Active", + "type": "Informational", + "topic": "", + "created": "13-Jul-2000", + "python_version": null, + "post_history": null, + "resolution": null, + "requires": null, + "replaces": null, + "superseded_by": null, + "url": "https://peps.python.org/pep-0000/" + }, + "1": { + "number": 1, + "title": "PEP Purpose and Guidelines", + "authors": "Barry Warsaw, Jeremy Hylton, David Goodger, Alyssa Coghlan", + "discussions_to": null, + "status": "Active", + "type": "Process", + "topic": "", + "created": "13-Jun-2000", + "python_version": null, + "post_history": "21-Mar-2001, 29-Jul-2002, 03-May-2003, 05-May-2012, 07-Apr-2013", + "resolution": null, + "requires": null, + "replaces": null, + "superseded_by": null, + "url": "https://peps.python.org/pep-0001/" + }, + "2": { + "number": 2, + "title": "Procedure for Adding New Modules", + "authors": "Brett Cannon, Martijn Faassen", + "discussions_to": null, + "status": "Active", + "type": "Process", + "topic": "", + "created": "07-Jul-2001", + "python_version": null, + "post_history": "07-Jul-2001, 09-Mar-2002", + "resolution": null, + "requires": null, + "replaces": null, + "superseded_by": null, + "url": "https://peps.python.org/pep-0002/" + } + } From 8a4e1cce158ef311c3f3647665495bd62678d78e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 14 Jul 2024 18:36:25 +0200 Subject: [PATCH 5/9] Revert "fixup! Document the PEPs API" This reverts commit 2b110f3f21a88ecc4a5843f3b1e65f85ba624b53. --- peps/contents.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/peps/contents.rst b/peps/contents.rst index d791f08f809..5d5c23ee3a6 100644 --- a/peps/contents.rst +++ b/peps/contents.rst @@ -15,4 +15,5 @@ This is an internal Sphinx page; please go to the :doc:`PEP Index `. :caption: PEP Table of Contents (needed for Sphinx): pep-* + api/* topic/* From 7cf4fa526ef610ee4038857069fda2d739f21ddb Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 15 Jul 2024 07:33:17 +0200 Subject: [PATCH 6/9] Use PEPs 8, 484 and 622 as representative examples --- peps/api/index.rst | 66 +++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/peps/api/index.rst b/peps/api/index.rst index a39b3a468ed..f649c23800c 100644 --- a/peps/api/index.rst +++ b/peps/api/index.rst @@ -10,55 +10,55 @@ The structure is like: .. code-block:: json { - "0": { - "number": 0, - "title": "Index of Python Enhancement Proposals (PEPs)", - "authors": "The PEP Editors", + "8": { + "number": 8, + "title": "Style Guide for Python Code", + "authors": "Guido van Rossum, Barry Warsaw, Alyssa Coghlan", "discussions_to": null, "status": "Active", - "type": "Informational", + "type": "Process", "topic": "", - "created": "13-Jul-2000", + "created": "05-Jul-2001", "python_version": null, - "post_history": null, + "post_history": "05-Jul-2001, 01-Aug-2013", "resolution": null, "requires": null, "replaces": null, "superseded_by": null, - "url": "https://peps.python.org/pep-0000/" + "url": "https://peps.python.org/pep-0008/" }, - "1": { - "number": 1, - "title": "PEP Purpose and Guidelines", - "authors": "Barry Warsaw, Jeremy Hylton, David Goodger, Alyssa Coghlan", - "discussions_to": null, - "status": "Active", - "type": "Process", - "topic": "", - "created": "13-Jun-2000", - "python_version": null, - "post_history": "21-Mar-2001, 29-Jul-2002, 03-May-2003, 05-May-2012, 07-Apr-2013", - "resolution": null, + "484": { + "number": 484, + "title": "Type Hints", + "authors": "Guido van Rossum, Jukka Lehtosalo, Łukasz Langa", + "discussions_to": "python-dev@python.org", + "status": "Final", + "type": "Standards Track", + "topic": "typing", + "created": "29-Sep-2014", + "python_version": "3.5", + "post_history": "16-Jan-2015, 20-Mar-2015, 17-Apr-2015, 20-May-2015, 22-May-2015", + "resolution": "https://mail.python.org/pipermail/python-dev/2015-May/140104.html", "requires": null, "replaces": null, "superseded_by": null, - "url": "https://peps.python.org/pep-0001/" + "url": "https://peps.python.org/pep-0484/" }, - "2": { - "number": 2, - "title": "Procedure for Adding New Modules", - "authors": "Brett Cannon, Martijn Faassen", - "discussions_to": null, - "status": "Active", - "type": "Process", + "622": { + "number": 622, + "title": "Structural Pattern Matching", + "authors": "Brandt Bucher, Daniel F Moisset, Tobias Kohn, Ivan Levkivskyi, Guido van Rossum, Talin", + "discussions_to": "python-dev@python.org", + "status": "Superseded", + "type": "Standards Track", "topic": "", - "created": "07-Jul-2001", - "python_version": null, - "post_history": "07-Jul-2001, 09-Mar-2002", + "created": "23-Jun-2020", + "python_version": "3.10", + "post_history": "23-Jun-2020, 08-Jul-2020", "resolution": null, "requires": null, "replaces": null, - "superseded_by": null, - "url": "https://peps.python.org/pep-0002/" + "superseded_by": "634", + "url": "https://peps.python.org/pep-0622/" } } From 94daba8d084549611eaa8880197482cdafdac089 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 15 Jul 2024 23:32:06 -0600 Subject: [PATCH 7/9] Add a pseudo-schema Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- peps/api/index.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/peps/api/index.rst b/peps/api/index.rst index f649c23800c..6750219b02e 100644 --- a/peps/api/index.rst +++ b/peps/api/index.rst @@ -7,6 +7,32 @@ There is a read-only API of published PEPs available at: The structure is like: +.. code-block:: json + + { + "": { + "number": integer, + "title": string, + "authors": string, + "discussions_to": string | null, + "status": "Accepted" | "Active" | "Deferred" | "Draft" | "Final" | "Provisional" | "Rejected" | "Superseded" | "Withdrawn", + "type": "Informational" | "Process" | "Standards Track", + "topic": "governance" | "packaging" | "release" | "typing" | "", + "created": string, + "python_version": string | null, + "post_history": string, + "resolution": string | null, + "requires": string | null, + "replaces": string | null, + "superseded_by": string | null, + "url": string + }, + +Date values are formatted as DD-MMM-YYYY, +and multiple dates are combied in a comma-separated list. + +For example: + .. code-block:: json { From d3d30754890edd01eacf4471b86ba56f3535aee1 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 16 Jul 2024 08:58:27 +0300 Subject: [PATCH 8/9] Add missing bracket, fix typo --- peps/api/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/api/index.rst b/peps/api/index.rst index 6750219b02e..fb483275bea 100644 --- a/peps/api/index.rst +++ b/peps/api/index.rst @@ -27,9 +27,10 @@ The structure is like: "superseded_by": string | null, "url": string }, + } Date values are formatted as DD-MMM-YYYY, -and multiple dates are combied in a comma-separated list. +and multiple dates are combined in a comma-separated list. For example: From d393bbc4dc77f162a3591eec9527eee8ad2f3c4e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 16 Jul 2024 17:24:49 +0300 Subject: [PATCH 9/9] Mark pseudo-JSON as JavaScript so it can be parsed by Sphinx --- peps/api/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/api/index.rst b/peps/api/index.rst index fb483275bea..46516f4150b 100644 --- a/peps/api/index.rst +++ b/peps/api/index.rst @@ -7,7 +7,7 @@ There is a read-only API of published PEPs available at: The structure is like: -.. code-block:: json +.. code-block:: javascript { "": {