[C++-sig] Boost.Python.function.__signatures__

[Nick Rasmussen]

On Wed, 20 Jul 2005, Ralf W. Grosse-Kunstleve wrote:

> --- Nick Rasmussen <nick at ilm.com> wrote:
> > If better docstrings is what you're after, why not just prepend the function
> > signature (either optionally or automatically) to the docstring. That way the
> > help() mechanism will give you the list of all the the overloads like you're
> > looking for even for functions where the docstring wasn't explictly
> > specified, and no change to python is needed.
> 
> That's an interesting idea. I can think of a couple of issues, though:
> 
> - Quite often the signatures are unwieldy, e.g. (this is not made up):
> 
>     max(scitbx::af::versa<double, scitbx::af::flex_grid<scitbx::af::small<long,
> 10ul> > >)
>     max(scitbx::af::versa<float, scitbx::af::flex_grid<scitbx::af::small<long,
> 10ul> > >)
>     max(scitbx::af::versa<long, scitbx::af::flex_grid<scitbx::af::small<long,
> 10ul> > >)
>     max(scitbx::af::versa<int, scitbx::af::flex_grid<scitbx::af::small<long,
> 10ul> > >)
>     max(scitbx::af::versa<unsigned long,
> scitbx::af::flex_grid<scitbx::af::small<long, 10ul> > >)
> 
>   It may be hard to find where the real documentation starts.
>   Maybe appending is better?

Not to over-complicate matters, but perhaps it'd be best to do something like:

int foo(int x) {}
...
     .def("foo",&foo,"foo(x) -> value\nC++ signature: " + signature())

where signature() is an indicator to .def as a place to substitute in the C++
signature, resulting in pydoc showing:

    foo(...)
        foo(x) -> value
        C++ signature: foo(int) -> int

   
and make:

     .def("foo",&foo) // no docstring

and:
     .def("foo",&foo,signature())

be equivalent, resulting in:

    foo(...)
        foo(int) -> int

That way people with existing docstrings will have help() output remain unchanged.
If you want to insert the signature into your docstring you have the choice of
how to use it, and for people that haven't put docstrings on their code, they
at least get some info in their docstrings.

> - I guess currently the docstrings are static. They'd have to become dynamic.
>   This seems to be a bigger project. I think we'd need a volunteer.

I'm not sure what you mean by dynamic, the docstrings are constructed
at .def time via src/object/function.cpp:

void function::add_to_namespace(
    object const& name_space, char const* name_, object const& attribute, char const* doc)
{
    add_to_namespace(name_space, name_, attribute);
    if (doc != 0)
    {
        object attr_copy(attribute);
        if (PyObject_HasAttrString(attr_copy.ptr(), "__doc__") && attr_copy.attr("__doc__")) {
            attr_copy.attr("__doc__") += "\n\n";
            attr_copy.attr("__doc__") += doc;
        }
        else
            attr_copy.attr("__doc__") = doc;
    }
}

I'm sure we already know the signature at that point.

-nick