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

[Guido van Rossum]

> 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?

It's hard to say.  The pydoc code makes up protocols as it goes.  I
think __name__ is probably the only one you're missing in practice.

--Guido van Rossum (home page: http://www.python.org/~guido/)