[Python-Dev] Breaking undocumented API

[Nick Coghlan]

On Wed, Nov 17, 2010 at 2:34 AM,  <exarkun at 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   |   ncoghlan at gmail.com   |   Brisbane, Australia