Module documentation

[Paul Boddie]

Tony Burrows wrote:
> Just getting to grips with Python, a great language BUT
> With something like Java I can find the syntax of a method call with no
> problems, how do I do the same with Python?
>
> For example, using MySQLdb or SGMLParser I can see what the available
> methods are with dir, but how do I find out what parameters are needed and
> what they represent?

You can use the help function to get documentation on modules,
functions, classes and objects. For example:

import sgmllib
help(sgmllib) # gives lots of information on the entire module
help(sgmllib.SGMLParser) # gives information on the class
help(sgmllib.SGMLParser.__init__) # gives initialisation information

Unfortunately, because of the discrepancies between "old-style" and
"new-style" classes, you can't always get decent help on objects.
Consider this contrived example:

parser = sgmllib.SGMLParser() # you'd usually be using a subclass
help(parser) # gives information about "class instance(object)"

Compare this to what happens when you get help on a file object:

f = open("/etc/hosts")
help(f) # gives information about "class file(object)"

Personally, I feel that the whole "new-style" thing - making a class
which inherits from something called "object" (of all the names that
could have been chosen) - introduces a fair number of
implementation-level issues that should have been hidden at the level
of the language. I know that various other object-oriented languages
have "object" or "Object" as a root class, but it's a dubious
convention, unnecessary for the first seven or more years of Python's
public life, and perhaps a prime candidate for elimination in the
much-discussed-of-late Python 3000.

Paul