[Doc-SIG] __all__, and how it relates to doc tools

[Tim Peters]

[Tim]
>> Well, every time you or I test pydoc under Windows, the first
>> thing we do is type "random" at it.

[Ping]
> ...why, because "random" has those weird bound methods at the
> top-level that used to throw pydoc for a loop?  :)

Na, it's that when pydoc was busted completely on Windows, I shouted out to
Guido "hey, bring up the pydoc GUI and search for a module".  "Which module?"
"Doesn't matter -- pick one at random."  "OK, I pick random."  Now it's a
ritual <wink>.

> ...
> I should note that pydoc *did* try both of those things already.
> In a previous incarnation, pydoc avoided top-level names beginning
> with _, but Guido was unhappy that it did this at the module level
> and not at the class level, so i changed it.

Changed it to what?  To avoid them at both levels, or to avoid them at
neither?  I expect he intended the former, not the latter.  Names that both
begin and end with (at least) two underscores don't count as "beginning with
'_'" for this purpose, though (as you said but I snipped, things like
__init__ and __getstate__ are potentially interesting to end users).

> In an even earlier incarnation, pydoc only displayed names listed
> in __all__, and so many things were missing from the output that
> it wasn't useful any more (e.g. errors in httplib, useful functions
> in cgi, constants like keyword.kwlist).  Perhaps if the value of
> __all__ were different (or if it's changed in the past couple of
> weeks) it would be okay, but at the moment it just hides too much.

__all__ is supposed to list all and only the "public" names in the module.
When it doesn't, that's a bug to be fixed in the module.  I agree there are
lots of bugs.  In the meantime, it would be better to suppress names that
pass

    name[:1] == "_" and not name[:2] == "__" == name[-2:]

That would, e.g., expose httplib's error classes, but suppress its internal
state-machine constants (_CS_IDLE etc) and non-user-callable methods (like
HTTPConnection._set_hostport).  Longer term, we should fix __all__ or get rid
of it; the former is better, because the latter leaves us documenting
accidental exports (like httplib.mimetools) forever; but the former is also
real work.