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@gmail.com <mailto:allanhaldane@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@scipy.org <mailto:NumPy-Discussion@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@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion