[Python-Dev] PEPs shouldn't be considered docs (original) (raw)

Benjamin Peterson benjamin at python.org
Fri Oct 11 16:10:03 CEST 2013

2013/10/11 Ned Batchelder <ned at nedbatchelder.com>:

I wanted to teach a co-worker about "from future import absoluteimport" today, so I thought I'd point them at the docs. The page for "future" starts with a bunch of internal details that almost no one needs to know. There's a table at the end that mentions the actual importable names, including "absoluteimport", but says nothing about then except to link to a PEP.

The absolute imports PEP has no simple description of what it does. Like many PEPs, it's mostly a summary of the debate around the design of the feature. The closest the PEP comes to describing the behavior of "absoluteimport" is this parenthetical: For the second problem, it is proposed that all import statements be absolute by default (searching sys.path only) with special syntax (leading dots) for accessing package-relative imports. And notice: that sentence describes it as a "proposal." I'd like to suggest that we not consider PEPs to be documentation. If a PEP has a good succinct description of how something works, then let's copy that text into the documentation at an appropriate place. If a PEP doesn't have such a description, then all the more reason not to send readers there.

+1 The writing required to specificy and adovocate a feature are usually quite different from that needed to document it. PEPs also get out of date rather quickly.

-- Regards, Benjamin

More information about the Python-Dev mailing list