[Python-Dev] Breaking undocumented API

[Łukasz Langa]

Am 11.11.2010 23:15, schrieb Nick Coghlan:
> 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).

+1

I like this approach *very much*. Let me elaborate:

1. The community knows, understands and accepts _names as private. We 
need to have _names for private functions and constants because we can 
change or remove those in later versions. It's very explicit: when the 
user complains "What, you removed _foo?" we can say "Yes, it was 
considered an implementation detail *from the start*." And it's hard to 
beat that argument. It was private from the start. You knew that because 
the name you called specifies that.  If we would be now to proclaim 
__all__ as a decisive point on what's private and what's not, it makes 
lives of all Python programmers (I mean the users as well) more complicated.

2. That being said, having help() mark non-underscored names which 
aren't included in __all__ as private is a good idea, too [1].  I'm a 
heavy user of interactive API discovery using dir() and help() and this 
would be definitely welcome. And even for those who don't use those 
tools, this feature can expose inconsistencies between documentation and 
code.

3. "import name as _name" or "from x.y import z as _z" is just bad form. 
There may be valid exceptions but imagine if that would be the default 
way to do it. Uglier than nights of November.

4. This is why I think considering all imports as private (unless 
they're in __all__) is a fine example of "practicability beats purity". 
We could try to conceive a way to expose this information 
programatically but that's not so important at the moment.

[1] As Hrvoje Niksic wrote here: 
http://mail.python.org/pipermail/python-dev/2010-November/105533.html

-- 
Best regards,
Łukasz Langa