[Numpy-discussion] Rename arguments to np.clip and np.put

Allan Haldane allanhaldane at gmail.com
Tue Mar 31 10:54:53 EDT 2015

On 03/30/2015 07:16 PM, Jaime Fernández del Río wrote:
> On Mon, Mar 30, 2015 at 3:59 PM, Allan Haldane <allanhaldane at gmail.com
> <mailto:allanhaldane at gmail.com>> wrote:
>     Hello everyone,
>     What does the list think of renaming the arguments of np.clip and np.put
>     to match those of ndarray.clip/put? Currently the signatures are
>         np.clip(a, a_min, a_max, out=None)
>         ndarray.clip(a, min=None, max=None, out=None)
>         np.put(a, ind, v, mode='raise')
>         ndarray.put(indices, values, mode='raise')
>     (The docstring for ndarray.clip is incorrect, too).
>     I suggest the signatures might be changed to this:
>         np.clip(a, min=None, max=None, out=None, **kwargs)
>         np.put(a, indices, values, mode='raise')
>     We can still take care of the old argument names for np.clip using
>     **kwards, while showing a deprecation warning. I think that would be
>     fully back-compatible. Note this makes np.clip more flexible as only one
>     of min or max are needed now, just like ndarray.clip.
>     np.put is trickier to keep back-compatible as it has two positional
>     arguments. Someone who called `np.put(a, v=0, ind=1)` would be in
>     trouble with this change, although I didn't find anyone on github doing
>     so. I suppose to maintain back-compatibility we could make indices and
>     values keyword args, and use the same kwargs trick as in np.clip, but
>     that might be confusing since they're both required args.
> Ideally we would want the signature to show as you describe it in the
> documentation, but during the deprecation period be something like e.g.
> np.put(a, indices=None, values=None, mode='raise', **kwargs)
> Not sure if that is even possible, maybe with functools.update_wrapper?
> Jaime

In Python 3 the __signature__ attribute does exactly what we want.
IPython 3.0.0 has also backported this for its docstrings internally for
Python 2. But that still leaves out Python 2 users who don't read
docstrings in IPython3+.

functools.update_wrapper uses the inspect module (as does IPython), and
the inspect module looks up func.func_code.co_varnames which is a
readonly python internals object, so that doesn't work.

How about making indices/value be keyword args, use __signature__ to
take care of Python 3, and then add a note in the docstring for Python 2
users that they are only temporarily keyword args during the deprecation

>     Any opinions or suggestions?
>     Allan
>     _______________________________________________
>     NumPy-Discussion mailing list
>     NumPy-Discussion at scipy.org <mailto:NumPy-Discussion at scipy.org>
>     http://mail.scipy.org/mailman/listinfo/numpy-discussion
> -- 
> (\__/)
> ( O.o)
> ( > <) Este es Conejo. Copia a Conejo en tu firma y ayúdale en sus
> planes de dominación mundial.
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion

More information about the NumPy-Discussion mailing list