[Python-Dev] Breaking undocumented API

[Guido van Rossum]

On Tue, Nov 16, 2010 at 8:34 AM,  <exarkun at twistedmatrix.com> wrote:
> 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.

That depends on what methods you're imagining "every single user" is
using to find out what the API *is*.

In my experience there are many ways people do this:

- by reading the source

- by reading the official docs

- by trial and error

- inspection of objects (e.g. dir())

- using help()

- by reading pydoc output collected on some website (or local disk)

- by following tutorials

- by reading books containing reference documentation generated by 3rd
party authors

Most people do several of those things. (Personally, I learned about
many APIs by creating them. But I'm probably an exception. :-)

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

Agreed. And adding a disclaimer to help() or pydoc output won't make
much of a difference, I expect.

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

Assuming people actually read the disclaimers.

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

Personally I think it would be sufficient if the disclaimer was at the
top of the library reference itself. That's certainly enough from a
legalistic "I told you so" POV and I doubt that we'll be able to move
the POV of what people actually use...

-- 
--Guido van Rossum (python.org/~guido)