Merge branch 'main' into packaging-governance

Author: warsaw

.github/CODEOWNERS

@@ -642,6 +642,7 @@ peps/pep-0760.rst  @pablogsal @brettcannon
 peps/pep-0761.rst  @sethmlarson @hugovk
 peps/pep-0762.rst  @pablogsal @ambv @lysnikolaou @emilyemorehouse
 peps/pep-0763.rst  @dstufft
+peps/pep-0764.rst  @JelleZijlstra
 peps/pep-0765.rst  @iritkatriel @ncoghlan
 peps/pep-0766.rst  @warsaw
 peps/pep-0767.rst  @carljm
@@ -651,6 +652,7 @@ peps/pep-0770.rst  @sethmlarson @brettcannon
 peps/pep-0771.rst  @pradyunsg
 peps/pep-0772.rst  @warsaw @pradyunsg
 peps/pep-0773.rst  @zooba
+peps/pep-0774.rst  @savannahostrowski
 # ...
 peps/pep-0777.rst  @warsaw
 # ...

.github/PULL_REQUEST_TEMPLATE/Mark a PEP Final.md

@@ -9,6 +9,6 @@ If you're unsure about something, just leave it blank and we'll take a look.
 * [ ] Any substantial changes since the accepted version approved by the SC/PEP delegate
 * [ ] Pull request title in appropriate format (``PEP 123: Mark Final``)
 * [ ] ``Status`` changed to ``Final`` (and ``Python-Version`` is correct)
-* [ ] Canonical docs/spec linked with a ``canonical-doc`` directive 
+* [ ] Canonical docs/spec linked with a ``canonical-doc`` directive
       (or ``canonical-pypa-spec`` for packaging PEPs,
        or ``canonical-typing-spec`` for typing PEPs)

.pre-commit-config.yaml

@@ -14,9 +14,14 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
+      - id: end-of-file-fixer
+        name: "Ensure files end with a single newline"
       - id: mixed-line-ending
         name: "Normalize mixed line endings"
         args: [--fix=lf]
+      - id: trailing-whitespace
+        name: "Remove trailing whitespace"
+
       - id: file-contents-sorter
         name: "Sort codespell ignore list"
         files: '.codespell/ignore-words.txt'

check-peps.py

@@ -39,16 +39,13 @@
 ALL_HEADERS = (
     "PEP",
     "Title",
-    "Version",
-    "Last-Modified",
     "Author",
     "Sponsor",
     "BDFL-Delegate", "PEP-Delegate",
     "Discussions-To",
     "Status",
     "Type",
     "Topic",
-    "Content-Type",
     "Requires",
     "Created",
     "Python-Version",
@@ -132,16 +129,18 @@ def check_headers(lines: Sequence[str], /) -> MessageIterator:
     yield from _validate_pep_number(next(iter(lines), ""))
 
     found_headers = {}
+    found_header_lines: list[tuple[str, int]] = []
     line_num = 0
     for line_num, line in enumerate(lines, start=1):
         if line.strip() == "":
             headers_end_line_num = line_num
             break
         if match := HEADER_PATTERN.match(line):
             header = match[1]
+            found_header_lines.append((header, line_num))
             if header in ALL_HEADERS:
                 if header not in found_headers:
-                    found_headers[match[1]] = line_num
+                    found_headers[header] = None
                 else:
                     yield line_num, f"Must not have duplicate header: {header} "
             else:
@@ -151,11 +150,11 @@ def check_headers(lines: Sequence[str], /) -> MessageIterator:
 
     yield from _validate_required_headers(found_headers.keys())
 
-    shifted_line_nums = list(found_headers.values())[1:]
-    for i, (header, line_num) in enumerate(found_headers.items()):
+    shifted_line_nums = [line for _, line in found_header_lines[1:]]
+    for i, (header, line_num) in enumerate(found_header_lines):
         start = line_num - 1
         end = headers_end_line_num - 1
-        if i < len(found_headers) - 1:
+        if i < len(found_header_lines) - 1:
             end = shifted_line_nums[i] - 1
         remainder = "\n".join(lines[start:end]).removeprefix(f"{header}:")
         if remainder != "":
@@ -182,8 +181,6 @@ def _validate_header(header: str, line_num: int, content: str) -> MessageIterato
         yield from _validate_type(line_num, content)
     elif header == "Topic":
         yield from _validate_topic(line_num, content)
-    elif header == "Content-Type":
-        yield from _validate_content_type(line_num, content)
     elif header in {"Requires", "Replaces", "Superseded-By"}:
         yield from _validate_pep_references(line_num, content)
     elif header == "Created":
@@ -348,13 +345,6 @@ def _validate_topic(line_num: int, line: str) -> MessageIterator:
         yield line_num, "Topic must be sorted lexicographically"
 
 
-def _validate_content_type(line_num: int, line: str) -> MessageIterator:
-    """'Content-Type' must be 'text/x-rst'"""
-
-    if line != "text/x-rst":
-        yield line_num, "Content-Type must be 'text/x-rst'"
-
-
 def _validate_pep_references(line_num: int, line: str) -> MessageIterator:
     """`Requires`/`Replaces`/`Superseded-By` must be 'NNN' PEP IDs"""
 

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}/",
         }
 

pep_sphinx_extensions/tests/pep_lint/test_headers.py

@@ -253,30 +253,6 @@ def test_validate_topic(line: str, expected_warnings: set):
     assert found_warnings == expected_warnings
 
 
-def test_validate_content_type_valid():
-    warnings = [
-        warning for (_, warning) in check_peps._validate_content_type(1, "text/x-rst")
-    ]
-    assert warnings == [], warnings
-
-
-@pytest.mark.parametrize(
-    "line",
-    [
-        "text/plain",
-        "text/markdown",
-        "text/csv",
-        "text/rtf",
-        "text/javascript",
-        "text/html",
-        "text/xml",
-    ],
-)
-def test_validate_content_type_invalid(line: str):
-    warnings = [warning for (_, warning) in check_peps._validate_content_type(1, line)]
-    assert warnings == ["Content-Type must be 'text/x-rst'"], warnings
-
-
 @pytest.mark.parametrize(
     "line",
     [

pep_sphinx_extensions/tests/pep_lint/test_pep_lint.py

@@ -12,33 +12,30 @@ def test_with_fake_pep():
     warnings = list(check_peps.check_peps(PEP_9002, content))
     assert warnings == [
         (1, "PEP must begin with the 'PEP:' header"),
+        (6, "Must not have invalid header: Version"),
         (9, "Must not have duplicate header: Sponsor "),
         (10, "Must not have invalid header: Horse-Guards"),
+        (15, "Must not have invalid header: Content-Type"),
         (1, "Must have required header: PEP"),
         (1, "Must have required header: Type"),
         (
             1,
-            "Headers must be in PEP 12 order. Correct order: Title, Version, "
-            "Author, Sponsor, BDFL-Delegate, Discussions-To, Status, Topic, "
-            "Content-Type, Requires, Created, Python-Version, Post-History, "
-            "Resolution",
+            "Headers must be in PEP 12 order. Correct order: Title, Author, "
+            "Sponsor, BDFL-Delegate, Discussions-To, Status, Topic, Requires, "
+            "Created, Python-Version, Post-History, Resolution",
         ),
         (4, "Author continuation lines must end with a comma"),
         (5, "Author line must not be over-indented"),
         (7, "Python-Version major part must be 1, 2, or 3: 4.0"),
-        (
-            8,
-            "Sponsor entries must begin with a valid 'Name': "
-            r"'Sponsor:\nHorse-Guards: Parade'",
-        ),
+        (8, "Sponsor entries must begin with a valid 'Name': ''"),
+        (9, "Sponsor entries must begin with a valid 'Name': ''"),
         (11, "Created must be a 'DD-mmm-YYYY' date: '1-Jan-1989'"),
         (12, "Delegate entries must begin with a valid 'Name': 'Barry!'"),
         (13, "Status must be a valid PEP status"),
         (14, "Topic must not contain duplicates"),
         (14, "Topic must be properly capitalised (Title Case)"),
         (14, "Topic must be for a valid sub-index"),
         (14, "Topic must be sorted lexicographically"),
-        (15, "Content-Type must be 'text/x-rst'"),
         (16, "PEP references must be separated by comma-spaces (', ')"),
         (17, "Discussions-To must be a valid thread URL or mailing list"),
         (18, "Post-History must be a 'DD-mmm-YYYY' date: '2-Feb-2000'"),

pep_sphinx_extensions/tests/peps/pep-9000.rst

@@ -1,6 +1,6 @@
 PEP: 9000
 Title: Test with authors with email addresses
-Author: Francis Fussyreverend <[email protected]>, 
+Author: Francis Fussyreverend <[email protected]>,
         Javier Soulfulcommodore <[email protected]>
 Created: 20-Apr-2022
 Status: Draft

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/"
      }
    }