The PEPs in this repo are published automatically on the web at
https://www.python.org/dev/peps/. To learn more about the purpose of
PEPs and how to go about writing a PEP, please start reading at PEP 1
(pep-0001.txt in this repo). Note that PEP 0, the index PEP, is
now automatically generated, and not committed to the repo.
See the Contributing Guidelines.
Original PEP source should be wri
B81A
tten in reStructuredText format,
which is a constrained version of plaintext, and is described in
PEP 12. Older PEPs were often written in a more mildly restricted
plaintext format, as described in PEP 9. The pep2html.py
processing and installation script knows how to produce the HTML
for either PEP format.
For processing reStructuredText format PEPs, you need the docutils
package, which is available from PyPI.
If you have pip, pip install docutils should install it.
PEP 0 is automatically generated based on the metadata headers in other
PEPs. The script handling this is genpepindex.py, with supporting
libraries in the pep0 directory.
Please don't commit changes with reStructuredText syntax errors that cause PEP
generation to fail, or result in major rendering defects relative to what you
intend. To check building the HTML output for your PEP (for example, PEP 12)
using the current default docutils-based system, run the pep2html.py script
with your PEP source file as its argument; e.g. for PEP 12,
python pep2html.py pep-0012.rstIf you're on a system with make, you can instead execute, e.g.,
make pep-0012.rstTo generate HTML for all the PEPs, run the script/make without a PEP
file argument.
By default, this will output a file (e.g. pep-0012.html) in the root
directory, which you can view to see the HTML output of your PEP.
Note that the custom CSS stylesheet is not used by default, so
the PEP will look rather plain, but all the basic formatting produced by the
reStructuredText syntax in your source file should be visible.
You can also view your PEP locally with the Sphinx-based builder, which will show the PEP exactly as it will appear on the preview of the new rendering system proposed in PEP 676; see Rendering PEPs with Sphinx for details.
Finally, you can check for and fix common linting and spelling issues, either on-demand or automatically as you commit, with our pre-commit suite. See the Contributing Guide for details.
python.org includes its own helper modules to render PEPs as HTML, with suitable links back to the source pages in the version control repository.
These can be found at https://github.com/python/pythondotorg/tree/main/peps
When making changes to the PEP management process that may impact python.org's rendering pipeline:
- Clone the python.org repository from https://github.com/python/pythondotorg/
- Get set up for local python.org development as per https://pythondotorg.readthedocs.io/install.html#manual-setup
- Adjust
PEP_REPO_PATHinpydotorg/settings/local.pyto refer to your local clone of the PEP repository - Run
./manage.py generate_pep_pagesas described in https://pythondotorg.readthedocs.io/pep_generation.html
There is a Sphinx-rendered version of the PEPs at https://python.github.io/peps/
(updated on every push to main).
Warning: This version is not, and should not be taken to be, a canonical source for PEPs whilst it remains in preview (please report any rendering bugs). The canonical source for PEPs remains https://www.python.org/dev/peps/
See the build documentation for full step by step instructions on how to install, build and view the rendered PEPs with Sphinx.
In summary, after installing the dependencies (preferably in a virtual environment) with:
python -m pip install -r requirements.txtYou can build the PEPs with sphinx by running, if your system has make:
make sphinxOtherwise, execute the build.py script directly:
python build.pyThe output HTML can be found under the build directory.
For details on the command-line options to the build.py script, run:
python build.py --help