[C++-sig] Re: boost::python docstrings

[David Abrahams]

Daniel Holth <dholth at fastmail.fm> writes:

> On Sun, 2003-07-13 at 16:17, David Abrahams wrote:
>> a(b,c):
>> foo?
>> There's so much information missing I doubt anyone is going to
>> understand your question.
>
> Whoops, sorry.  Second try:
>
> I'm working on a Python extension that controls xmms.  It's written in
> pure C++ and boost::python.  This is an excerpt from 'pydoc xmms':
>
> Python Library Documentation: module xmms
>
> NAME
>     xmms
>
> ...
>
>   |  get_playlist_file(...)
>   |      Return the filename of a playlist item.
>   |  
>   |  get_playlist_time(...)
>   |      Return length (milliseconds) of a playlist item
>   |  
>   |  get_playlist_title(...)
>   |      Return the title of a playlist item.
>
> ...
>
> This is an excerpt from 'pydoc urllib':
>   |  get_user_passwd(self, host, realm, clear_cache=0) 
>   |
>   |  http_error_301(self, url, fp, errcode, errmsg, headers, data=None)
>   |      Error 301 -- also relocated (permanently).
>
>
> Notice how the Python module (urllib) has its argument list in the pydoc
> documentation like so: get_user_passwd(self, host, realm,
> clear_cache=0), while the boost::python module (or __builtins__, for
> that matter) is presented as functionname(...).

Well, Python has a lot more to go on when introspecting about a pure
Python function than about a callable "extension function" object.

> My question:  Is there an argument to .def() that will tell pydoc what
> to put in place of the ... in e.g. get_playlist_file(...).

Well, http://www.boost.org/libs/python/doc/v2/args.html ought to
work, but I'm pretty sure it doesn't.  If you can tell us what
information pydoc uses to format that info we might be able to help.

[Nicodemus, I think pyste should take an option to generate
"args(...)" for those people who want to use keywords in their
function calls]

> The alternative, taken by __builtins__, is to phrase the docstring as
> methodcall(example) -> result
>
> Second Question
> ---------------
> I'm also writing an xmms plugin, under the latest Debian Linux, i386,
> that runs Python code but I get errors about internal Python symbols not
> being found when I try to import other Python modules (like time).  Can
> someone point me to an existing project that includes a dynamically
> loaded Python embedding?

I don't know what you mean by "a dynamically loaded Python
embedding?", but this sounds like a question for comp.lang.python to
me anyway.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com