[Python-Dev] Breaking undocumented API (original) (raw)

Michael Foord fuzzyman at voidspace.org.uk
Wed Nov 17 12:57:17 CET 2010

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.

More information about the Python-Dev mailing list