[Python-Dev] PEP 376

Stephen J. Turnbull stephen at xemacs.org
Thu Jul 2 05:44:57 CEST 2009


Tarek Ziadé writes:
 > On Wed, Jul 1, 2009 at 1:44 PM, Paul Moore<p.f.moore at gmail.com> wrote:

 > > General rule - don't document (and commit yourself to) any
 > > internal details that the user can't access from the public
 > > API. It just makes backward compatibility harder to maintain.
 > 
 > The purpose is to provide this documentation to third-party
 > projects that want to implement a packaging system on the top of
 > these classes.

That's a judgment you must make.  However, Paul's opinion seems to be
that it is internal, and not needed by third-parties who are working
"on the top" of these classes.  If upon consideration you agree, you
should take those "details" out of the PEP proper.  If you disagree,
you should promote them to the "official"/public API.

The point of a PEP is not to construct a duck; it is to explain what
"quack" means.

 > Maybe this should be removed from the PEP and but into another
 > document targeted to developers ?

Yes.  In the reference implementation (aka prototype), which should
have its own documentation as usual.  The reference implementation for
the PEP shows *how* these things can be done.  It must do that, or the
PEP has no force.  However, the reference implementation need not be
"industrial strength"; the actual implementation that eventually goes
into the stdlib may very well be an optimized and enhanced version
with many data structures and algorithms that differ from the
reference implementation.

Another general principle: even in the draft PEP, say "is", not "will
be".  If you're wrong, and that won't work; if it's insufficiently
precise; if you find a more elegant way to express the solution; if
you simply haven't thought carefully about something yet; if, for
whatever reason, you may need to change the PEP, then you change it in
the next draft.  That's why we have a review cycle, so you can change
it.  If you yourself have a question, or the draft is incomplete at
some point, then you can explain in a note (either a footnote or
parentheses).  You can even mark a whole section as "speculative" (eg,
"nothing in this section has been implemented yet, so everything is
subject to change").  But a rule should be stated as a rule, and
precisely, so that reviewers can criticize it accurately.

If you're uncomfortable saying "is", then maybe that part of the draft
isn't ready for public review yet.  On the other hand, you can use the
reviewers' knowledge here: write "A is B", then as a note "(In some
cases A is actually C, and this should be treated specially.  But
how?)"



More information about the Python-Dev mailing list