[Python-Dev] Breaking undocumented API

[Ben Finney]

Bobby Impollonia <bobbyi at gmail.com> writes:

> On Mon, Nov 8, 2010 at 2:07 PM, Raymond Hettinger
> <raymond.hettinger at gmail.com> wrote:
> > 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.

It also introduces a (perhaps small, but clearly non-zero) maintenance
burden: the name of an object must be added, changed, and removed not
only where it is defined, but also in the ‘__all__’ entry.

This burden is avoided when using the spelling of the name itself as the
indicator for exposure in the API.

-- 
 \         “In any great organization it is far, far safer to be wrong |
  `\          with the majority than to be right alone.” —John Kenneth |
_o__)                                            Galbraith, 1989-07-28 |
Ben Finney