Module documentation

[Tony Burrows]

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?

Tony

[Rene Pijlman]

Tony Burrows:

With something like Java I can find the syntax of a method call with no
problems, how do I do the same with Python?
The basic syntax is just the name, with parameters in brakcets:

object.method(par1, par2, ...)

This is explained in the documentation, of course.
how do I find out what parameters are needed and what they represent?

This is documented in the library reference:
http://docs.python.org/modindex.html

You can also query the module for its docstrings:

import os
help(os) ....help(os.utime)

Help on built-in function utime in module nt:
....

[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

[Tony Burrows]

On Sun, 26 Mar 2006 17:19:35 +0200, Rene Pijlman wrote:

Tony Burrows:

With something like Java I can find the syntax of a method call with no
problems, how do I do the same with Python?

The basic syntax is just the name, with parameters in brakcets:

object.method(par1, par2, ...)

This is explained in the documentation, of course.

how do I find out what parameters are needed and what they represent?

This is documented in the library reference:
http://docs.python.org/modindex.html

You can also query the module for its docstrings:

import os
help(os) ...help(os.utime)

Help on built-in function utime in module nt:
...

Wow! Thanks for that, I didn't know about the help command. The problem
was that things like MySQLdb wasn't in the link you give (or at least, I
couldn't find it - though poking around did take me to the database
section and there it was).

Tony

[Bruno Desthuilliers]

Tony Burrows a écrit :

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?

In the python shell, typing 'help(<symbol>)' should get you started most
of the time.

[Georg Brandl]

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?

In case of extension modules and libraries not in the Python standard library,
they should have a documentation somewhere too.

And if they are implemented in Python, just look at the source to understand
how the methods work.

Georg

[msoulier]

Bruno Desthuilliers wrote:

In the python shell, typing 'help(<symbol>)' should get you started most
of the time.

And honestly, it should work all of the time. If it doesn't, file a bug
report. I can't stand it when that doesn't work. Some of us don't do
all of our work with a browser handy, and a net connection.

Mike