2013/10/11 Ned Batchelder <n...@nedbatchelder.com>: > 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.
+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 _______________________________________________ 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/archive%40mail-archive.com
