[Python-Dev] Re: [PEP 224] Attribute Docstrings
Ka-Ping Yee
ping@lfw.org
Tue, 29 Aug 2000 15:43:23 -0500 (CDT)
On Tue, 29 Aug 2000, Christian Tanzer wrote:
> Triple quoted strings work -- that's what I'm constantly using. The
> downside is, that the docstrings either contain spurious white space
> or it messes up the layout of the code (if you start subsequent lines
> in the first column).
The "inspect" module (see http://www.lfw.org/python/) handles this nicely.
Python 1.5.2 (#4, Jul 21 2000, 18:28:23) [C] on sunos5
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import inspect
>>> class Foo:
... """First line.
... Second line.
... An indented line.
... Some more text."""
...
>>> inspect.getdoc(Foo)
'First line.\012Second line.\012 An indented line.\012Some more text.'
>>> print _
First line.
Second line.
An indented line.
Some more text.
>>>
I suggested "inspect.py" for the standard library quite some time ago
(long before the feature freeze, and before ascii.py, which has since
made it in). MAL responded pretty enthusiastically
(http://www.python.org/pipermail/python-dev/2000-July/013511.html).
Could i request a little more feedback from others?
It's also quite handy for other purposes. It can get the source
code for a given function or class:
>>> func = inspect.getdoc
>>> inspect.getdoc(func)
'Get the documentation string for an object.'
>>> inspect.getfile(func)
'inspect.py'
>>> lines, lineno = inspect.getsource(func)
>>> print string.join(lines)
def getdoc(object):
"""Get the documentation string for an object."""
if not hasattr(object, "__doc__"):
raise TypeError, "arg has no __doc__ attribute"
if object.__doc__:
lines = string.split(string.expandtabs(object.__doc__), "\n")
margin = None
for line in lines[1:]:
content = len(string.lstrip(line))
if not content: continue
indent = len(line) - content
if margin is None: margin = indent
else: margin = min(margin, indent)
if margin is not None:
for i in range(1, len(lines)): lines[i] = lines[i][margin:]
return string.join(lines, "\n")
And it can get the argument spec for a function:
>>> inspect.getargspec(func)
(['object'], None, None, None)
>>> apply(inspect.formatargspec, _)
'(object)'
Here's a slightly more challenging example:
>>> def func(a, (b, c), (d, (e, f), (g,)), h=3): pass
...
>>> inspect.getargspec(func)
(['a', ['b', 'c'], ['d', ['e', 'f'], ['g']], 'h'], None, None, (3,))
>>> apply(inspect.formatargspec, _)
'(a, (b, c), (d, (e, f), (g,)), h=3)'
>>>
-- ?!ng