[Python-Dev] Breaking undocumented API

[Guido van Rossum]

On Thu, Nov 18, 2010 at 4:16 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> On Thu, Nov 18, 2010 at 7:22 AM, Georg Brandl <g.brandl at gmx.net> wrote:
>> 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.

Not so fast. The feature's meaning has clearly evolved.

> 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.

Let's live with a little ambiguity. There are more shades of gray here
than you can imagine. I like gray.

-- 
--Guido van Rossum (python.org/~guido)