[Python-Dev] Breaking undocumented API (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Thu Nov 18 13:16:35 CET 2010

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

More information about the Python-Dev mailing list