[Python-Dev] Breaking undocumented API

[Greg Ewing]

Steven D'Aprano wrote:
> By the way, did you intend to send this off-list?

No, I didn't realise I hadn't sent it to the list.

If you don't document them, I won't use them, because I won't
know if it's one of these don't-ask-don't-tell pseudo-public
functions or something private that's accidentally been given
a non-underscore name.

> Greg Ewing wrote:

>> Also it means that help() wouldn't show me documentation for
>> the support functions, which is a bad thing if they really are
>> intended for public use.
> 
> I don't see why... if you import the module, and call help(module), they 
> will show up as normal.

If the module has an __all__ list, then help(module) will only
show functions included in that list. So your pseudo-public
functions would not show up in it. Without some other reason to
suspect their existence, I would probably never find them.

-- 
Greg