Meta: Document the PEPs API

.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 @@ def write_pep0(
  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,17 +30,20 @@
 ".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",
 # PEP files
 "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 @@
 
 # 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_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/*