On Mon, Nov 8, 2010 at 3:26 PM, Bobby Impollonia <bob...@gmail.com> wrote: > On Mon, Nov 8, 2010 at 2:07 PM, Raymond Hettinger > <raymond.hettin...@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) _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
