[Python-Dev] Re: [PEP 224] Attribute Docstrings

[Ka-Ping Yee]

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