[Python-Dev] Breaking undocumented API

[Nick Coghlan]

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