[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
period?
> 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