[Doc-SIG] __all__, and how it relates to doc tools
Tim Peters
tim.one@home.com
Thu, 19 Apr 2001 03:41:53 -0400
[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.