[Tutor] How to use introspection to discover parameters?

[David]

Please help me understand the following (I have python 2.6.2) ...

Because I want to write nice docstrings, I read PEP257 where it says:
"The one-line docstring should NOT be a "signature" reiterating the
function/method parameters (which can be obtained by introspection)."

I am understanding this sentence to mean: don't put function parameters in my
own docstrings, because they are readily obtained some other way. This other
way is apparently called "introspection", but how to actually do it is a
mystery that I cannot find documented. If the following guess is wrong, I will
be grateful if someone would just show a simple example of how this is done.

If I was to attempt a guess: does it just mean using the help() builtin in the
interpreter? I know about help() from books and tutorials. In the packaged html
python docs though, use of help() is hardly described and never associated with
the word "introspection".

My reasoning for this guess is explained in the rest of this email, which sets
out what I have tried before asking here:

I searched the installed html docs for "introspection".
I disregard most hits as too specific, except these:

	On Page 2. "Defining new types" it says:
	"An application can use the introspection API ..."

	and under Glossary it says, in the docstring entry:
	"Since [the docstring] is available via introspection, it is the
	canonical place for documentation of the object."

So I find no clue there how to do "introspection" to obtain function/method
parameters, except that there is an API for it, somewhere.

I googled and found various, eg:
http://www.ibm.com/developerworks/library/l-pyint/index.html
It also does not explain how to do "introspection" to obtain function/method
parameters.

Next, I tried looking somewhere arbitrary in the python libraries hoping to see
PEP257-compliant practice.I think that I need to find some code that is written
in python, not C, because PEP257 also says: "docstring [with parameters] is
only appropriate for C functions (such as built-ins), where introspection is
not possible."

I arbitrarily choose the "logging" module:

>>> import logging
>>> logging.__file__
'/usr/lib/python2.6/logging/__init__.pyc'

> ls -1 /usr/lib/python2.6/logging/*.py
/usr/lib/python2.6/logging/config.py
/usr/lib/python2.6/logging/handlers.py
/usr/lib/python2.6/logging/__init__.py

so I assume the "logging" module is not written in C, and therefore will
contain suitable examples. And I try this:

>>> help(logging.log)
Help on function log in module logging:

log(level, msg, *args, **kwargs)
    Log 'msg % args' with the integer severity 'level' on the root logger.

>>> logging.log.__doc__
"\n    Log 'msg % args' with the integer severity 'level' on the root
logger.\n    "
>>>

So I look at that and guess: is PEP257 actually attempting to say
"dont reiterate the function/method parameters in the docstring, because help()
displays them in line 3 of its output".
If it does mean this, it would be a lot clearer if it just said so!

A related question:
help() seems to do the introspection for me. Does python allow me to do it in
my own code? Specifically, how might I write my own function to mimic line 3 of
help(), appearing like so:

>>> my_function(logging.log)
"log(level, msg, *args, **kwargs)"

If I knew how to do that, it might help me understand how to do "introspection"
better.

One last thing. When looking for answers, I found this page which seems related:
http://stackoverflow.com/questions/2536879/python-introspection-how-to-get-varnames-of-class-methods

There is a comment by S Lott who possibly is the author of "Building Skills In
Python": "Please ... explain why you need introspection and why you can't
simply read the source."

Ummm ... I'm not sure what to make of that!! Because I've read that this
instrospection thing is supposed to be an important feature of Python.
Clarifications welcome :)