On Wed, Nov 17, 2010 at 2:34 AM, <exar...@twistedmatrix.com> wrote: > I don't think it belongs only in PEP 8 (that's "a style guide" you're > referring to, correct?). It needs to be front and center. This is > information that every single user of the stdlib needs in order to use the > stdlib correctly. > > Imagine trying to use a dictionary without knowing about alphabetical > ordering. Or driving a car without knowing what lane markers indicate.
The definition of the public/private policy in all its gory detail should be in PEP 8 as Guido suggests. The library documentation may then contain a note about the difference in compatibility guarantees for public and private APIs, say that any interface and behaviour documented in the manual qualifies as public, then point readers to PEP 8 for the precise details. A similar note could be placed in the C API documentation (with a reference to the detailed policy in PEP 7, perhaps REsTify'ing that PEP in the process in order to link directly to the naming convention section). Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
