From d2d6d71319a437b55e2aa0887cce5aeb0243b564 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Wed, 17 Jul 2024 08:04:03 +0300 Subject: [PATCH] Meta: Document the PEPs API (#3864) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- .pre-commit-config.yaml | 10 +- .../pep_zero_generator/writer.py | 7 ++ peps/api/index.rst | 91 +++++++++++++++++++ peps/conf.py | 24 +++-- peps/contents.rst | 1 + 5 files changed, 118 insertions(+), 15 deletions(-) create mode 100644 peps/api/index.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9ebe7b8dc..da6e98e97 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/pep_sphinx_extensions/pep_zero_generator/writer.py b/pep_sphinx_extensions/pep_zero_generator/writer.py index f8232d0ce..e0507cc7f 100644 --- a/pep_sphinx_extensions/pep_zero_generator/writer.py +++ b/pep_sphinx_extensions/pep_zero_generator/writer.py @@ -169,6 +169,13 @@ class PEPZeroWriter: 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 000000000..46516f415 --- /dev/null +++ b/peps/api/index.rst @@ -0,0 +1,91 @@ +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:: javascript + + { + "": { + "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 combined in a comma-separated list. + +For example: + +.. code-block:: json + + { + "8": { + "number": 8, + "title": "Style Guide for Python Code", + "authors": "Guido van Rossum, Barry Warsaw, Alyssa Coghlan", + "discussions_to": null, + "status": "Active", + "type": "Process", + "topic": "", + "created": "05-Jul-2001", + "python_version": null, + "post_history": "05-Jul-2001, 01-Aug-2013", + "resolution": null, + "requires": null, + "replaces": null, + "superseded_by": null, + "url": "https://peps.python.org/pep-0008/" + }, + "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-0484/" + }, + "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": "23-Jun-2020", + "python_version": "3.10", + "post_history": "23-Jun-2020, 08-Jul-2020", + "resolution": null, + "requires": null, + "replaces": null, + "superseded_by": "634", + "url": "https://peps.python.org/pep-0622/" + } + } diff --git a/peps/conf.py b/peps/conf.py index d23763b34..9a747aa8f 100644 --- a/peps/conf.py +++ b/peps/conf.py @@ -30,7 +30,7 @@ source_suffix = { ".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 @@ include_patterns = [ "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", @@ -51,14 +54,14 @@ nitpicky = True # 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 = [] @@ -86,4 +89,5 @@ html_permalinks = False # handled in the PEPContents transform 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")] diff --git a/peps/contents.rst b/peps/contents.rst index d791f08f8..5d5c23ee3 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/*