Wandering Thoughts archives


A problem with Python's help()

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.)

python/HelpProblem written at 01:22:25; Add Comment

Page tools: See As Normal.
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.