[Python-Dev] docstrings, help(), and __name__

[David Abrahams]

I've recently been implementing docstring support for Boost.Python
extension classes (and in particular, their methods). I have a callable
type which wraps all C++ functions and member functions -- it basically
looks like a minimal subset of Python's function type, with a tp_descr_get
slot which does the same thing that funcobject.c's func_descr_get() does:

    static PyObject *
    function_descr_get(PyObject *func, PyObject *obj, PyObject *type_)
    {
        if (obj == Py_None)
            obj = NULL;
        return PyMethod_New(func, obj, type_);
    }

So I just recently added a descriptor for the "__doc__" string attribute,
and I thought I'd try help() on one of these methods:

*****************************************************************
Failure in example: help(X)
from line #2 of __main__
Exception raised:
Traceback (most recent call last):
  File "doctest.py", line 430, in _run_examples_inner
    compileflags, 1) in globs
  File "<string>", line 1, in ?
  File "c:\tools\python-2.2.1\lib\site.py", line 279, in __call__
    return pydoc.help(*args, **kwds)
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 1510, in __call__
    self.help(request)
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 1546, in help
    else: doc(request, 'Help on %s:')
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 1341, in doc
    pager(title % (desc + suffix) + '\n\n' + text.document(thing, name))
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 268, in document
    if inspect.isclass(object): return apply(self.docclass, args)
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 1093, in docclass
    lambda t: t[1] == 'method')
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 1035, in spill
    name, mod, object))
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 269, in document
    if inspect.isroutine(object): return apply(self.docroutine, args)
  File "c:\tools\python-2.2.1\lib\pydoc.py", line 1116, in docroutine
    realname = object.__name__
AttributeError: 'Boost.Python.function' object has no attribute '__name__'
*****************************************************************

It seems I'm breaking some protocol. It's easy enough to add a '__name__'
attribute to my function objects, but I'd like to be sure that I'm adding
everything I really /should/ add. Just how much like a regular Python
function does my function have to be in order to make the help system (and
other standard systems with such expectations) happy?

TIA,
Dave

-----------------------------------------------------------
           David Abrahams * Boost Consulting
dave@boost-consulting.com * http://www.boost-consulting.com