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

Nick Coghlan ncoghlan at gmail.com
Sat Oct 12 01:29:50 CEST 2013

On 11 Oct 2013 21:25, "Ned Batchelder" <ned at nedbatchelder.com> wrote:

I wanted to teach a co-worker about "from future import absolute_import" 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 "absolute_import", 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 "absolute_import" 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. A link to the PEP is appropriate as a "see also" in the docs, but we shouldn't pretend that a PEP addresses the needs of people new to the feature.

Aside from PEPs that describe development practices and versioned interoperability standards, this is already the case.

The only major deviation from this practice was the import system, and that was because it was such an incoherent organically grown mess in CPython prior to the importlib migration in Python 3.3 that nobody was prepared to take on the task of writing the reference docs. Providing the missing reference docs for the import system was one of the conditions placed on the introduction of namespace packages in PEP 420.

There's no grand policy change or clarification needed here, it's just another consequence of the fact that the import system isn't documented properly in versions prior to 3.3.

Cheers, Nick.

--Ned.

Python-Dev mailing list Python-Dev at python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20131012/0eafedb0/attachment.html>

More information about the Python-Dev mailing list