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

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Tue Nov 16 17:34:54 CET 2010

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

More information about the Python-Dev mailing list