Meta: Document the PEPs API (#3864)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

.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"

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 <api/peps.json>`__ is a JSON file of metadata about "
+                "all the published PEPs. :doc:`Read more here <api/index>`."
+            )
+            self.emit_newline()
+
         # PEPs by category
         self.emit_title("Index by Category")
         meta, info, provisional, accepted, open_, finished, historical, deferred, dead = _classify_peps(peps)

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
+
+   {
+     "<PEP number>": {
+       "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/"
+     }
+   }

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),
+    "python": ("https://docs.python.org/3/", None),
-    'packaging': ('https://packaging.python.org/en/latest/', None),
+    "packaging": ("https://packaging.python.org/en/latest/", None),
-    'typing': ('https://typing.readthedocs.io/en/latest/', None),
+    "typing": ("https://typing.readthedocs.io/en/latest/", None),
-    'trio': ('https://trio.readthedocs.io/en/latest/', None),
+    "trio": ("https://trio.readthedocs.io/en/latest/", None),
-    'devguide': ('https://devguide.python.org/', None),
+    "devguide": ("https://devguide.python.org/", None),
-    'py3.11': ('https://docs.python.org/3.11/', None),
+    "py3.11": ("https://docs.python.org/3.11/", None),
-    'py3.12': ('https://docs.python.org/3.12/', None),
+    "py3.12": ("https://docs.python.org/3.12/", None),
-    'py3.13': ('https://docs.python.org/3.13/', 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")]

peps/contents.rst

@@ -15,4 +15,5 @@ This is an internal Sphinx page; please go to the :doc:`PEP Index <pep-0000>`.
    :caption: PEP Table of Contents (needed for Sphinx):
 
    pep-*
+   api/*
    topic/*