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

Nick Coghlan ncoghlan at gmail.com
Wed Nov 17 14:30:25 CET 2010

On Wed, Nov 17, 2010 at 11:21 PM, Fred Drake <fdrake at acm.org> wrote:

2010/11/17 Michael Foord <fuzzyman at voidspace.org.uk>:

So -1 on splitting Python development style guide into multiple documents. I don't think that the publicness or API stability promises of the standard library are part of a style guide.  They're an essential part of the library documentation.  They aren't a guide for 3rd-party code, and are specific to the standard library. If we can't come up with something reasonable for the standard library, we certainly shouldn't be making recommendations on the matter for 3rd party code.  If we do come up with something reasonable, we can recommend it to others later (once field-proven), and without duplication.  (Possibly by referring to the standard library documentation, and possibly by refactoring.  That's not important until we have something, though.)

Would it make people happier if we left PEP 7 and PEP 8 alone, and put the clarification of what constitutes a "public API" into PEP 5 instead? PEP 5 currently the deprecation policy for language constructs, it would be easy enough to extend it to all public APIs.

The library documentation is not the right place for quibbling about what constitutes a public API when using other means than the library documentation to find APIs to call.

Cheers, Nick.

-- Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Python-Dev mailing list