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. For the most part, the non-underscored parts of the API shouldn't be changed "at our whim". Some sense needs to be applied to the decision. Google's code search is great for showing how people actually have used a module in real world code. If that shows that people are accessing and/or changing an attribute, it probably needs to remain exposed. In the absence of a code search, good guesses can be made about what someone might reasonably and usefully be accessing (i.e. glob0 isn't likely). The goal is to improve the standard library while minimizing breakage, and that will involve trade-offs depending on what is being changed. IIRC, we've been trying to get away from deprecations because they're so disruptive. For example, when the pprint rewrite is finally ready, if there is an incompatible API change, I expect that a new clean class will be offered, but that the old will be left in-place so that tons of existing code won't break). Likewise, with the unittest clean-ups, I'm expecting that Michael will introduce aliases when fixing-up mis-named methods, rather than break code that uses the existing names. my-two-cents, Raymond _______________________________________________ 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
