[Python-Dev] PEPs shouldn't be considered docs

[Nick Coghlan]

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>