[Numpy-discussion] Add ability to disable the autogeneration of the function signature in a ufunc docstring.

[Warren Weckesser]

On Fri, Mar 15, 2013 at 4:39 PM, Nathaniel Smith <njs at pobox.com> wrote:

> On Fri, Mar 15, 2013 at 6:47 PM, Warren Weckesser
> <warren.weckesser at gmail.com> wrote:
> > Hi all,
> >
> > In a recent scipy pull request (https://github.com/scipy/scipy/pull/459),
> I
> > ran into the problem of ufuncs automatically generating a signature in
> the
> > docstring using arguments such as 'x' or 'x1, x2'.  scipy.special has a
> lot
> > of ufuncs, and for most of them, there are much more descriptive or
> > conventional argument names than 'x'.  For now, we will include a nicer
> > signature in the added docstring, and grudgingly put up with the one
> > generated by the ufunc.  In the long term, it would be nice to be able to
> > disable the automatic generation of the signature.  I submitted a pull
> > request to numpy to allow that: https://github.com/numpy/numpy/pull/3149
> >
> > Comments on the pull request would be appreciated.
>
> The functionality seems obviously useful, but adding a magic public
> attribute to all ufuncs seems like a somewhat clumsy way to expose it?
> Esp. since ufuncs are always created through the C API, including
> docstring specification, but this can only be set at the Python level?
> Maybe it's the best option but it seems worth taking a few minutes to
> consider alternatives.
>


Agreed;  exposing the flag as part of the public Python ufunc API is
unnecessary, since this is something that would rarely, if ever, be changed
during the life of the ufunc.



> Brainstorming:
>
> - If the first line of the docstring starts with "<funcname>(" and
> ends with ")", then that's a signature and we skip adding one (I think
> sphinx does something like this?) Kinda magic and implicit, but highly
> backwards compatible.
>
> - Declare that henceforth, the signature generation will be disabled
> by default, and go through and add a special marker like
> "__SIGNATURE__" to all the existing ufunc docstrings, which gets
> replaced (if present) by the automagically generated signature.
>
> - Give ufunc arguments actual names in general, that work for things
> like kwargs, and then use those in the automagically generated
> signature. This is the most work, but it would mean that people don't
> have to remember to update their non-magic signatures whenever numpy
> adds a new feature like out= or where=, and would make the docstrings
> actually accurate, which right now they aren't:
>
>
I'm leaning towards this option.  I don't know if there would still be a
need to disable the automatic generation of the docstring if it was good
enough.


In [7]: np.add.__doc__.split("\n")[0]
> Out[7]: 'add(x1, x2[, out])'
>
> In [8]: np.add(x1=1, x2=2)
> ValueError: invalid number of arguments
>
> - Allow some special syntax to describe the argument names in the
> docstring: "__ARGNAMES__: a b\n" -> "add(a, b[, out])"
>
> - Something else...
>
> -n
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20130320/4285137b/attachment.html>