<p dir="ltr">On 20 Mar 2013 17:11, "Warren Weckesser" <<a href="mailto:warren.weckesser@gmail.com">warren.weckesser@gmail.com</a>> wrote:<br>
><br>
><br>
><br>
> On Fri, Mar 15, 2013 at 4:39 PM, Nathaniel Smith <<a href="mailto:njs@pobox.com">njs@pobox.com</a>> wrote:<br>
>><br>
>> On Fri, Mar 15, 2013 at 6:47 PM, Warren Weckesser<br>
>> <<a href="mailto:warren.weckesser@gmail.com">warren.weckesser@gmail.com</a>> wrote:<br>
>> > Hi all,<br>
>> ><br>
>> > In a recent scipy pull request (<a href="https://github.com/scipy/scipy/pull/459">https://github.com/scipy/scipy/pull/459</a>), I<br>
>> > ran into the problem of ufuncs automatically generating a signature in the<br>
>> > docstring using arguments such as 'x' or 'x1, x2'.  scipy.special has a lot<br>
>> > of ufuncs, and for most of them, there are much more descriptive or<br>
>> > conventional argument names than 'x'.  For now, we will include a nicer<br>
>> > signature in the added docstring, and grudgingly put up with the one<br>
>> > generated by the ufunc.  In the long term, it would be nice to be able to<br>
>> > disable the automatic generation of the signature.  I submitted a pull<br>
>> > request to numpy to allow that: <a href="https://github.com/numpy/numpy/pull/3149">https://github.com/numpy/numpy/pull/3149</a><br>
>> ><br>
>> > Comments on the pull request would be appreciated.<br>
>><br>
>> The functionality seems obviously useful, but adding a magic public<br>
>> attribute to all ufuncs seems like a somewhat clumsy way to expose it?<br>
>> Esp. since ufuncs are always created through the C API, including<br>
>> docstring specification, but this can only be set at the Python level?<br>
>> Maybe it's the best option but it seems worth taking a few minutes to<br>
>> consider alternatives.<br>
><br>
><br>
><br>
> 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.<br>
><br>
><br>
>><br>
>> Brainstorming:<br>
>><br>
>> - If the first line of the docstring starts with "<funcname>(" and<br>
>> ends with ")", then that's a signature and we skip adding one (I think<br>
>> sphinx does something like this?) Kinda magic and implicit, but highly<br>
>> backwards compatible.<br>
>><br>
>> - Declare that henceforth, the signature generation will be disabled<br>
>> by default, and go through and add a special marker like<br>
>> "__SIGNATURE__" to all the existing ufunc docstrings, which gets<br>
>> replaced (if present) by the automagically generated signature.<br>
>><br>
>> - Give ufunc arguments actual names in general, that work for things<br>
>> like kwargs, and then use those in the automagically generated<br>
>> signature. This is the most work, but it would mean that people don't<br>
>> have to remember to update their non-magic signatures whenever numpy<br>
>> adds a new feature like out= or where=, and would make the docstrings<br>
>> actually accurate, which right now they aren't:<br>
>><br>
><br>
> 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.</p>
<p dir="ltr">Certainly it would be nice for ufunc argument handling to better match python argument handling! Just needs someone willing to do the work... *cough* ;-)</p>
<p dir="ltr">-n</p>
<p dir="ltr">>> In [7]: np.add.__doc__.split("\n")[0]<br>
>> Out[7]: 'add(x1, x2[, out])'<br>
>><br>
>> In [8]: np.add(x1=1, x2=2)<br>
>> ValueError: invalid number of arguments<br>
>><br>
>> - Allow some special syntax to describe the argument names in the<br>
>> docstring: "__ARGNAMES__: a b\n" -> "add(a, b[, out])"<br>
>><br>
>> - Something else...<br>
>><br>
>> -n<br>
>> _______________________________________________<br>
>> NumPy-Discussion mailing list<br>
>> <a href="mailto:NumPy-Discussion@scipy.org">NumPy-Discussion@scipy.org</a><br>
>> <a href="http://mail.scipy.org/mailman/listinfo/numpy-discussion">http://mail.scipy.org/mailman/listinfo/numpy-discussion</a><br>
><br>
><br>
><br>
> _______________________________________________<br>
> NumPy-Discussion mailing list<br>
> <a href="mailto:NumPy-Discussion@scipy.org">NumPy-Discussion@scipy.org</a><br>
> <a href="http://mail.scipy.org/mailman/listinfo/numpy-discussion">http://mail.scipy.org/mailman/listinfo/numpy-discussion</a><br>
><br>
</p>