On Oct 11, 2013, at 07:24 AM, Ned Batchelder wrote:

I'd like to suggest that we not consider PEPs to be documentation.

Absolutely +1. That was never the intention behind PEPs. -Barry

On 11 Oct 2013 21:25, "Ned Batchelder" 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

...

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

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: 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@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com