A problem with Python's help()

October 6, 2008

I mentioned in passing that when I am poking around an unfamiliar object (well, class), I usually reach first for dir() and only somewhat later try help(). There's several reasons for this, but one of them is that help() is overly verbose in a useless way.

The problem is that many objects have a lot of completely standard methods like __repr__, generally with absolutely no useful documentation text, and help() will gleefully tell you all about them (for an example of this, apply help() to itself). The more advanced an object is, the more such standard methods it will have (to implement all the protocols that make it a sequence object or whatever) and the more noise that help() produces.

(And it is a lot of noise; each such member produces two or three lines of output. This can add up very fast, especially if you use help() on a module that has a bunch of classes with a bunch of standard methods.)

There's only two interesting things about standard methods; first, what 'protocols' the object supports (is it a sequence object, a callable one, an iterable one, does it have a string value, etc), and second, does it do anything unusual for any of them. The first is directly obvious, and we can guess at the second by seeing if any of the standard methods have non-standard docstrings. Thus, help() would be more helpful if it did not report such generic standard methods individually, but instead condensed all of them into a single line of information about what the object supports.

(Note that writing better docstrings can't help the situation; at most it can drown the noise about standard methods in verbose signal.)


Comments on this page:

From 24.6.51.170 at 2008-10-13 01:39:06:

Sounds like a reasonable proposal for help(obj, verbose=False), especially given the protocol ABCs in 2.6+.

- Chris Leary

By cks at 2008-10-14 02:20:50:

Hopefully help() would default to non-verbose mode. I don't think that this would cause backwards compatibility issues, because I believe that help() is only useful for humans to start with.

Written on 06 October 2008.
« SSL certificate revocation doesn't work (for web browsers)
How we set up our iSCSI target servers »

Page tools: View Source, View Normal, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Mon Oct 6 01:22:25 2008
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.