Infra: Use a list of authors in peps.json (#4226)

pep_sphinx_extensions/pep_zero_generator/parser.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import dataclasses
+from collections.abc import Iterable, Sequence
 from email.parser import HeaderParser
 from pathlib import Path
 
@@ -121,6 +122,11 @@ def __lt__(self, other: PEP) -> bool:
     def __eq__(self, other):
         return self.number == other.number
 
+    @property
+    def _author_names(self) -> Iterable[str]:
+        """An iterator of the authors' full names."""
+        return (author.full_name for author in self.authors)
+
     @property
     def shorthand(self) -> str:
         """Return reStructuredText tooltip for the PEP type and status."""
@@ -138,19 +144,19 @@ def details(self) -> dict[str, str | int]:
             "title": self.title,
             # a tooltip representing the type and status
             "shorthand": self.shorthand,
-            # the author list as a comma-separated with only last names
-            "authors": ", ".join(author.full_name for author in self.authors),
+            # the comma-separated list of authors
+            "authors": ", ".join(self._author_names),
             # The targeted Python-Version (if present) or the empty string
             "python_version": self.python_version or "",
         }
 
     @property
-    def full_details(self) -> dict[str, str | int]:
+    def full_details(self) -> dict[str, str | int | Sequence[str]]:
         """Returns all headers of the PEP as a dict."""
         return {
             "number": self.number,
             "title": self.title,
-            "authors": ", ".join(author.full_name for author in self.authors),
+            "authors": ", ".join(self._author_names),
             "discussions_to": self.discussions_to,
             "status": self.status,
             "type": self.pep_type,
@@ -162,6 +168,8 @@ def full_details(self) -> dict[str, str | int]:
             "requires": self.requires,
             "replaces": self.replaces,
             "superseded_by": self.superseded_by,
+            # extra non-header keys for use in ``peps.json``
+            "author_names": tuple(self._author_names),
             "url": f"https://peps.python.org/pep-{self.number:0>4}/",
         }
 

peps/api/index.rst

@@ -1,17 +1,17 @@
 PEPs API
 ========
 
-There is a read-only API of published PEPs available at:
+There is a read-only JSON document of every published PEP available at
+https://peps.python.org/api/peps.json.
 
-* https://peps.python.org/api/peps.json
+Each PEP is represented as a JSON object, keyed by the PEP number.
+The structure of each JSON object is as follows:
 
-The structure is like:
-
-.. code-block:: javascript
+.. code-block:: typescript
 
    {
      "<PEP number>": {
-       "number": integer,
+       "number": integer,  // always identical to <PEP number>
        "title": string,
        "authors": string,
        "discussions_to": string | null,
@@ -25,67 +25,80 @@ The structure is like:
        "requires": string | null,
        "replaces": string | null,
        "superseded_by": string | null,
+       "author_names": Array<string>,
        "url": string
      },
    }
 
 Date values are formatted as DD-MMM-YYYY,
 and multiple dates are combined in a comma-separated list.
 
-For example:
+A selection of example PEPs are shown here,
+illustrating some of the possible values for each field:
 
 .. code-block:: json
 
    {
-     "8": {
-       "number": 8,
-       "title": "Style Guide for Python Code",
-       "authors": "Guido van Rossum, Barry Warsaw, Alyssa Coghlan",
+     "12": {
+       "number": 12,
+       "title": "Sample reStructuredText PEP Template",
+       "authors": "David Goodger, Barry Warsaw, Brett Cannon",
        "discussions_to": null,
        "status": "Active",
        "type": "Process",
        "topic": "",
-       "created": "05-Jul-2001",
+       "created": "05-Aug-2002",
        "python_version": null,
-       "post_history": "05-Jul-2001, 01-Aug-2013",
+       "post_history": "`30-Aug-2002 <https://mail.python.org/archives/list/[email protected]/thread/KX3AS7QAY26QH3WIUAEOCCNXQ4V2TGGV/>`__",
        "resolution": null,
        "requires": null,
        "replaces": null,
        "superseded_by": null,
-       "url": "https://peps.python.org/pep-0008/"
+       "author_names": [
+        "David Goodger",
+        "Barry Warsaw",
+        "Brett Cannon"
+       ],
+       "url": "https://peps.python.org/pep-0012/"
      },
-     "484": {
-       "number": 484,
-       "title": "Type Hints",
-       "authors": "Guido van Rossum, Jukka Lehtosalo, Łukasz Langa",
-       "discussions_to": "[email protected]",
+     "160": {
+       "number": 160,
+       "title": "Python 1.6 Release Schedule",
+       "authors": "Fred L. Drake, Jr.",
+       "discussions_to": null,
        "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",
+       "type": "Informational",
+       "topic": "release",
+       "created": "25-Jul-2000",
+       "python_version": "1.6",
+       "post_history": null,
+       "resolution": null,
        "requires": null,
        "replaces": null,
        "superseded_by": null,
-       "url": "https://peps.python.org/pep-0484/"
+       "author_names": [
+        "Fred L. Drake, Jr."
+       ],
+       "url": "https://peps.python.org/pep-0160/"
      },
-     "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",
+     "3124": {
+       "number": 3124,
+       "title": "Overloading, Generic Functions, Interfaces, and Adaptation",
+       "authors": "Phillip J. Eby",
+       "discussions_to": "python-3000@python.org",
+       "status": "Deferred",
        "type": "Standards Track",
        "topic": "",
-       "created": "23-Jun-2020",
-       "python_version": "3.10",
-       "post_history": "23-Jun-2020, 08-Jul-2020",
+       "created": "28-Apr-2007",
+       "python_version": null,
+       "post_history": "30-Apr-2007",
        "resolution": null,
-       "requires": null,
-       "replaces": null,
-       "superseded_by": "634",
-       "url": "https://peps.python.org/pep-0622/"
+       "requires": "3107, 3115, 3119",
+       "replaces": "245, 246",
+       "superseded_by": null,
+       "author_names": [
+        "Phillip J. Eby"
+       ],
+       "url": "https://peps.python.org/pep-3124/"
      }
    }