[Python-Dev] Breaking undocumented API

[Nick Coghlan]

On Thu, Nov 18, 2010 at 7:22 AM, Georg Brandl <g.brandl at gmx.net> wrote:
> Am 17.11.2010 22:16, schrieb Éric Araujo:
>>> Excluding a builtin name from __all__ sounds like a perfectly sensible
>>> idea, so even if it wasn't deliberate, I'd say it qualifies as
>>> fortuitous :)
>>
>> But then, a tool that looks into __all__ to find for example what
>> objects to document will miss open.  I’d put open in __all__.
>
> So it comes down again to what we'd like __all__ to mean foremost:
> public API, or just a list for "import *"?

It's the list for star imports. This intended use case is borne out by
the description of the feature when it was first added to the language
back in 2.1:
http://docs.python.org/dev/whatsnew/2.1.html?highlight=__all__#other-changes-and-fixes

The public API (for documentation and introspection purposes) is any
name that doesn't start with an underscore and isn't an imported
module. If a tool is attempting to use __all__ as more than just the
list of names for star imports, I would call the tool buggy.

The use of the term "public names" in the language reference when
describing the semantics of __all__ is an unfortunate choice, but it
is used specifically in the context of talking about star imports and
clarifying which names they bring in without making any reference to
standards for documentation or deprecation policies.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia