[Python-Dev] Breaking undocumented API

[Michael Foord]

On 17/11/2010 11:45, Nick Coghlan wrote:
> 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.

+1

Have we agreed the policy though?

> 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.
>

+1

This sounds like the right approach to me.

All the best,

Michael
> 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.
>


-- 

http://www.voidspace.org.uk/

READ CAREFULLY. By accepting and reading this email you agree,
on behalf of your employer, to release me from all obligations
and waivers arising from any and all NON-NEGOTIATED agreements,
licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
confidentiality, non-disclosure, non-compete and acceptable use
policies (”BOGUS AGREEMENTS”) that I have entered into with your
employer, its partners, licensors, agents and assigns, in
perpetuity, without prejudice to my ongoing rights and privileges.
You further represent that you have the authority to release me
from any BOGUS AGREEMENTS on behalf of your employer.