[Python-Dev] Breaking undocumented API

[Nick Coghlan]

On Fri, Nov 12, 2010 at 4:16 AM, Steven D'Aprano <steve at pearwood.info> wrote:
> Another couple of objections to getting rid of __all__:
>
> If you're proxying modules or built-ins, you may not be able to use a
> _private name, but you may not want import * to pick up your proxies.
>
> I find it annoying to see this:
>
> import module as _module
> _module.func()
>
> (instead of import module and merely leaving module out of __all__)

That gets us back to dir() and help() giving the wrong impression of
the module's public API though.

The issue I have is that the current policy (public APIs may or may
not be in all, private APIs may or may not be prefixed by a leading
underscore) makes it impossible to reliably extract a module's public
API programmatically.

If we instead adopt the explicit policy that private APIs are:
- imported modules (with the exception of os.path)
- any names starting with a leading underscore

Then we get the 3 API tiers you describe: core public API in __all__,
other public functions and globals without leading underscores,
private API with leading underscores (or imported modules).

We could even add two additional functions to the inspect module (e.g.
getpublicnames() and getimportstarnames()) which applied the relevant
filtering rules.

Cheers,
Nick.

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