Skip to content

Commit d2d6d71

Browse files
hugovkAA-Turner
hugovk
and
AA-Turner
authored
Meta: Document the PEPs API (#3864)
Co-authored-by: Adam Turner <[email protected]>
1 parent 7eed7f6 commit d2d6d71

File tree

5 files changed

+118
-15
lines changed

5 files changed

+118
-15
lines changed

‎.pre-commit-config.yaml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ default_stages: [commit]
1212
repos:
1313
# General file checks and fixers
1414
- repo: https://github.com/pre-commit/pre-commit-hooks
15-
rev: v4.5.0
15+
rev: v4.6.0
1616
hooks:
1717
- id: mixed-line-ending
1818
name: "Normalize mixed line endings"
@@ -43,17 +43,17 @@ repos:
4343
name: "Check YAML"
4444

4545
- repo: https://github.com/psf/black-pre-commit-mirror
46-
rev: 24.1.1
46+
rev: 24.4.2
4747
hooks:
4848
- id: black
4949
name: "Format with Black"
5050
args:
5151
- '--target-version=py39'
5252
- '--target-version=py310'
53-
files: 'pep_sphinx_extensions/tests/.*'
53+
files: '^(peps/conf\.py|pep_sphinx_extensions/tests/.*)$'
5454

5555
- repo: https://github.com/astral-sh/ruff-pre-commit
56-
rev: v0.2.1
56+
rev: v0.5.1
5757
hooks:
5858
- id: ruff
5959
name: "Lint with Ruff"
@@ -89,7 +89,7 @@ repos:
8989

9090
# Manual codespell check
9191
- repo: https://github.com/codespell-project/codespell
92-
rev: v2.2.6
92+
rev: v2.3.0
9393
hooks:
9494
- id: codespell
9595
name: "Check for common misspellings in text files"

‎pep_sphinx_extensions/pep_zero_generator/writer.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,13 @@ def write_pep0(
169169
self.emit_newline()
170170
self.emit_newline()
171171

172+
self.emit_title("API")
173+
self.emit_text(
174+
"The `PEPS API <api/peps.json>`__ is a JSON file of metadata about "
175+
"all the published PEPs. :doc:`Read more here <api/index>`."
176+
)
177+
self.emit_newline()
178+
172179
# PEPs by category
173180
self.emit_title("Index by Category")
174181
meta, info, provisional, accepted, open_, finished, historical, deferred, dead = _classify_peps(peps)

‎peps/api/index.rst

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
PEPs API
2+
========
3+
4+
There is a read-only API of published PEPs available at:
5+
6+
* https://peps.python.org/api/peps.json
7+
8+
The structure is like:
9+
10+
.. code-block:: javascript
11+
12+
{
13+
"<PEP number>": {
14+
"number": integer,
15+
"title": string,
16+
"authors": string,
17+
"discussions_to": string | null,
18+
"status": "Accepted" | "Active" | "Deferred" | "Draft" | "Final" | "Provisional" | "Rejected" | "Superseded" | "Withdrawn",
19+
"type": "Informational" | "Process" | "Standards Track",
20+
"topic": "governance" | "packaging" | "release" | "typing" | "",
21+
"created": string,
22+
"python_version": string | null,
23+
"post_history": string,
24+
"resolution": string | null,
25+
"requires": string | null,
26+
"replaces": string | null,
27+
"superseded_by": string | null,
28+
"url": string
29+
},
30+
}
31+
32+
Date values are formatted as DD-MMM-YYYY,
33+
and multiple dates are combined in a comma-separated list.
34+
35+
For example:
36+
37+
.. code-block:: json
38+
39+
{
40+
"8": {
41+
"number": 8,
42+
"title": "Style Guide for Python Code",
43+
"authors": "Guido van Rossum, Barry Warsaw, Alyssa Coghlan",
44+
"discussions_to": null,
45+
"status": "Active",
46+
"type": "Process",
47+
"topic": "",
48+
"created": "05-Jul-2001",
49+
"python_version": null,
50+
"post_history": "05-Jul-2001, 01-Aug-2013",
51+
"resolution": null,
52+
"requires": null,
53+
"replaces": null,
54+
"superseded_by": null,
55+
"url": "https://peps.python.org/pep-0008/"
56+
},
57+
"484": {
58+
"number": 484,
59+
"title": "Type Hints",
60+
"authors": "Guido van Rossum, Jukka Lehtosalo, Łukasz Langa",
61+
"discussions_to": "[email protected]",
62+
"status": "Final",
63+
"type": "Standards Track",
64+
"topic": "typing",
65+
"created": "29-Sep-2014",
66+
"python_version": "3.5",
67+
"post_history": "16-Jan-2015, 20-Mar-2015, 17-Apr-2015, 20-May-2015, 22-May-2015",
68+
"resolution": "https://mail.python.org/pipermail/python-dev/2015-May/140104.html",
69+
"requires": null,
70+
"replaces": null,
71+
"superseded_by": null,
72+
"url": "https://peps.python.org/pep-0484/"
73+
},
74+
"622": {
75+
"number": 622,
76+
"title": "Structural Pattern Matching",
77+
"authors": "Brandt Bucher, Daniel F Moisset, Tobias Kohn, Ivan Levkivskyi, Guido van Rossum, Talin",
78+
"discussions_to": "[email protected]",
79+
"status": "Superseded",
80+
"type": "Standards Track",
81+
"topic": "",
82+
"created": "23-Jun-2020",
83+
"python_version": "3.10",
84+
"post_history": "23-Jun-2020, 08-Jul-2020",
85+
"resolution": null,
86+
"requires": null,
87+
"replaces": null,
88+
"superseded_by": "634",
89+
"url": "https://peps.python.org/pep-0622/"
90+
}
91+
}

‎peps/conf.py

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -30,17 +30,20 @@
3030
".rst": "pep",
3131
}
3232

33-
# List of patterns (relative to source dir) to ignore when looking for source files.
33+
# List of patterns (relative to source dir) to include when looking for source files.
3434
include_patterns = [
3535
# Required for Sphinx
3636
"contents.rst",
3737
# PEP files
3838
"pep-????.rst",
3939
# PEP ancillary files
4040
"pep-????/*.rst",
41+
# PEPs API
42+
"api/*.rst",
4143
# Documentation
4244
"docs/*.rst",
4345
]
46+
# And to ignore when looking for source files.
4447
exclude_patterns = [
4548
# PEP Template
4649
"pep-0012/pep-NNNN.rst",
@@ -51,14 +54,14 @@
5154

5255
# Intersphinx configuration
5356
intersphinx_mapping = {
54-
'python': ('https://docs.python.org/3/', None),
55-
'packaging': ('https://packaging.python.org/en/latest/', None),
56-
'typing': ('https://typing.readthedocs.io/en/latest/', None),
57-
'trio': ('https://trio.readthedocs.io/en/latest/', None),
58-
'devguide': ('https://devguide.python.org/', None),
59-
'py3.11': ('https://docs.python.org/3.11/', None),
60-
'py3.12': ('https://docs.python.org/3.12/', None),
61-
'py3.13': ('https://docs.python.org/3.13/', None),
57+
"python": ("https://docs.python.org/3/", None),
58+
"packaging": ("https://packaging.python.org/en/latest/", None),
59+
"typing": ("https://typing.readthedocs.io/en/latest/", None),
60+
"trio": ("https://trio.readthedocs.io/en/latest/", None),
61+
"devguide": ("https://devguide.python.org/", None),
62+
"py3.11": ("https://docs.python.org/3.11/", None),
63+
"py3.12": ("https://docs.python.org/3.12/", None),
64+
"py3.13": ("https://docs.python.org/3.13/", None),
6265
}
6366
intersphinx_disabled_reftypes = []
6467

@@ -86,4 +89,5 @@
8689
html_baseurl = "https://peps.python.org" # to create the CNAME file
8790
gettext_auto_build = False # speed-ups
8891

89-
templates_path = [os.fspath(_PSE_PATH / "pep_theme" / "templates")] # Theme template relative paths from `confdir`
92+
# Theme template relative paths from `confdir`
93+
templates_path = [os.fspath(_PSE_PATH / "pep_theme" / "templates")]

‎peps/contents.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,5 @@ This is an internal Sphinx page; please go to the :doc:`PEP Index <pep-0000>`.
1515
:caption: PEP Table of Contents (needed for Sphinx):
1616

1717
pep-*
18+
api/*
1819
topic/*

0 commit comments

Comments
 (0)