[Python-Dev] Breaking undocumented API

[Alexander Belopolsky]

2010/11/11 Michael Foord <fuzzyman at voidspace.org.uk>:
..
>> You mean runtime automation, e.g. creating __all__ on the fly omitting
>> underscored names?
>>
> Writing code to generate a __all__ that duplicates the default behaviour
> seems redundant to me.
>

FWIW, I like having __all__ at the top of the module.  It feels like a
table of contents at the start of a chapter.  In some cases it may
also serve as an optimization when len(__all__) is much smaller than
len(__dict__).  I also don't like _ prefix to become an exclusive
means to express privateness.

I think the current definition of "public names" is a good one and
just needs to be made more visible in the docs.  If the module defines
__all__, that should be the ultimate answer to what is public in that
module.   (Users should learn to use help(module) instead of
dir(module) for API discovery.)   If __all__ is not defined in the
module, I think it is good to introduce it after a careful review of
what it should contain.  And __all__ should never contain names that
start with _.