[Python-Dev] Breaking undocumented API

[exarkun at twistedmatrix.com]

On 03:48 pm, guido at python.org wrote:
>On Tue, Nov 16, 2010 at 7:16 AM, Alexander Belopolsky
><alexander.belopolsky at gmail.com> wrote:
>>What this thread has shown is that there is no consensus on what
>>public names are and what rules should be followed when changing names
>>that can be imported from a module.  I have opened an issue at
>>http://bugs.python.org/issue10434 to address this.  My vote is to
>>adopt the definition spelled out in the language reference, copy it to
>>the library manual and add some discussion of the deprecation
>>policies.
>
>Hm. Apart from the specific semantics assigned by the language to
>single and double leading (and trailing) underscores, I still think
>this belongs in a style guide, not in the library manual. When reading
>the library manual, one should always assume that undocumented
>features are subject to change at any time.

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.

No matter how many times we discuss this policy on this list (I know 
it's come up here before), the majority of python users still won't 
learn about it.

PEP 8 isn't nearly visible enough, either.  Whatever the rule is, it 
needs to be presented with the information itself.  If the rule is that 
things not documented in the library manual have no compatibility 
guarantees, then all of the means of getting documentation *other* than 
looking at the library manual need to indicate this somehow 
(alternatively, the information shouldn't be duplicated, but I doubt 
I'll convince anyone of that).

Here's a stupid proposal.  What if the top of pydoc output said (for 
stdlib modules only) "The library manual is the canonical reference. 
Refer to it before using APIs you find in this documentation."  Still 
inconvenient, but inconvenient is better than secret/impossible.

Jean-Paul