[Python-Dev] Breaking undocumented API

[Guido van Rossum]

On Fri, Nov 12, 2010 at 1:49 AM, Hrvoje Niksic <hrvoje.niksic at avl.com> wrote:
> On 11/11/2010 11:24 PM, Greg Ewing wrote:
>>
>> Nick Coghlan wrote:
>>
>>>  My personal opinion is that we should be trying to get the standard
>>>  library to the point where __all__ definitions are unnecessary - if a
>>>  name isn't in __all__, it should start with an underscore (and if that
>>>  is true, then the __all__ definition becomes effectively redundant).
>>
>> What about names imported from other modules that are used by
>> the module, but not intended for re-export? How would you
>> prevent them from turning up in help() etc. without using
>> __all__?
>
> import foo as _foo
>
> I believe I am not the only one who finds that practice ugly,

Agreed.

> but I find it
> just as ugly to underscore-ize every non-public helper function. __all__ is
> there for a reason, let's use it.  Maybe help() could automatically ignore
> stuff not in __all__, or display it but warn the user of non-public
> identifiers?

No, I like all non-public functions, constants, classes and variables
(but excluding imported modules) to start with _.

You'd still need __all__ to make "import *" do the right thing, but
the reader of the source code should not have to look up every name in
__all__ to find whether it is supposed to be public or private. Plus,
the same convention should carry over to methods and other class
attributes, where you don't have __all__.

If help() is broken we should fix it. (I'm not very happy with it
myself anyway, I rarely use it.)

Note that __all__ was originally invented to give "from package import
*" a well-defined meaning when the package included submodules that
might not have been loaded yet. Using it for other export control
(while a good idea) could be considered "newfangled". :-)

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