[Python-Dev] Breaking undocumented API

Guido van Rossum guido at python.org
Tue Nov 9 00:47:03 CET 2010


On Mon, Nov 8, 2010 at 3:26 PM, Bobby Impollonia <bobbyi at gmail.com> wrote:
> On Mon, Nov 8, 2010 at 2:07 PM, Raymond Hettinger
> <raymond.hettinger at gmail.com> wrote:
>>
>> On Nov 8, 2010, at 11:58 AM, Brett Cannon wrote:
>>
>>> I think we need to, as a group, decide how to handle undocumented APIs
>>> that don't have a leading underscore: they get treated just the same
>>> as the documented APIs, or are they private regardless and thus we can
>>> change them at our whim?
>>
>> To start with, it doesn't hurt for a maintainer to add an __all__ entry and to only document the parts of the API we think need to be exposed.  That way, we can at least declare the parts that are intended to be public on a go-forward basis.
>
> This does hurt because anyone who was relying on "import *" to get a
> name which is now omitted from __all__ is going to upgrade and find
> their program failing with NameErrors. This is a backwards compatible
> change and shouldn't happen without a deprecation warning first.

Given that import * is generally frowned upon you can't make a blanket
statement like this without referring to the specifics of the name
being considered for removal. In fact, for any proposed change the
risk and reward need to be weighed properly. If the risk is "someone's
code could break if they used some undocumented API" it is useful to
estimate the probability that this would happen and that somebody
would care (rather than just fixing their code and moving on). Many
factors go into such an estimate. Just one example would be if we knew
of usage of the offending name in code that could reasonably be
assumed to be widely copied or distributed -- in such cases we should
move very carefully indeed no matter how "officially undocumented"
something is.

I don't want to go into the specifics of the trace module (even if I
wrote it, it's too long ago to remember, nor can I recall using it)
but I do want to warn about the dangers of applying simplifying rules
mindlessly.

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


More information about the Python-Dev mailing list