[Numpy-discussion] Feedback on new argument positions for ma.dot and MaskedArray.dot

[Charles R Harris]

Hi All,

I'd like some feedback for the position of the `strict` and `out` arguments
for masked arrays. See gh-6653 <https://github.com/numpy/numpy/pull/6653>
for the PR in question.

Current status without #6652


1. ma.dot(a, b, strict=False) -- established
2. a.dot(b, out=None) -- new in 1.10


Note that 1. requires adding `out` to the end for backward compatibility.
OTOH, 2. is new(ish). We can either keep it compatible with ndarray.dot and
add `strict` to the end and have it incompatible with 1., or, slightly
changing it in 1.10.2, make it compatible with with 1. but incompatible
with ndarray. We will face the same sort of problem with adding newer
ndarray arguments other existing ma functions that have their own
specialized arguments, so having a policy up front will be helpful. My own
inclination here is to keep 1. and 2. compatible, and then perhaps at some
point following a future warning, make both `strict` and `out` keyword
arguments only. Another possiblitly is to make that transition immediate
for the method.

Thoughts?

Chuck

[Eric Firing]

Post by Charles R Harris
Hi All,
I'd like some feedback for the position of the `strict` and `out`
arguments for masked arrays. See gh-6653
<https://github.com/numpy/numpy/pull/6653> for the PR in question.
Current status without #6652
1. ma.dot(a, b, strict=False) -- established
2. a.dot(b, out=None) -- new in 1.10
Note that 1. requires adding `out` to the end for backward
compatibility. OTOH, 2. is new(ish). We can either keep it compatible
with ndarray.dot and add `strict` to the end and have it incompatible
with 1., or, slightly changing it in 1.10.2, make it compatible with
with 1. but incompatible with ndarray. We will face the same sort of
problem with adding newer ndarray arguments other existing ma functions
that have their own specialized arguments, so having a policy up front
will be helpful. My own inclination here is to keep 1. and 2.
compatible, and then perhaps at some point following a future warning,
make both `strict` and `out` keyword arguments only. Another possiblitly
is to make that transition immediate for the method.

I'm not sure about the best sequence, but I like the strategy of moving
to keyword-only arguments. It is good for readability, and for flexibility.

I also prefer that there be a single convention: either the "out" kwarg
is the end of the every signature, or it is the first kwarg in every
signature. It's a very special and unusual kwarg, so it should have a
standard location.

Eric

Post by Charles R Harris
Thoughts?
Chuck
_______________________________________________
NumPy-Discussion mailing list
https://mail.scipy.org/mailman/listinfo/numpy-discussion

[Nathaniel Smith]

Post by Eric Firing
I also prefer that there be a single convention: either the "out" kwarg

is the end of the every signature, or it is the first kwarg in every
signature. It's a very special and unusual kwarg, so it should have a
standard location.

For all ufuncs, out arguments come first immediately after in arguments, so
+1 for doing that for consistency.

-n

[Charles R Harris]

Post by Eric Firing

Post by Eric Firing
I also prefer that there be a single convention: either the "out" kwarg

is the end of the every signature, or it is the first kwarg in every
signature. It's a very special and unusual kwarg, so it should have a
standard location.
For all ufuncs, out arguments come first immediately after in arguments,
so +1 for doing that for consistency.

Agree that that is what to shoot for. The particular problem with `ma.dot`
is that it already has the `strict` argument where the new `out` argument
should go. I propose the following steps.


1. For backward compatibility, start by adding new arguments to the end
2. Later raise FutureWarning on positional arguments that are out of
place
3. Then make all but early arguments keyword only

Once we have keyword only for a while, it would be possible to add some
arguments back as positional arguments, but it might be best to keep them
as keyword only as suggested above.

For the current PR, this means that the dot method will have positional
arguments in a different order than ma.dot. Alternatively, out could be
made keyword only in both, although that would require fixing up some
tests. There is really no magical solution that avoids all difficulties
that I can see.

Unless a consensus develops otherwise, I will pursue step 1. and go for a
1.10.2rc tomorrow.

Chuck

[Nathaniel Smith]

On Mon, Nov 9, 2015 at 4:43 PM, Charles R Harris

Post by Charles R Harris

Post by Nathaniel Smith

Post by Eric Firing
I also prefer that there be a single convention: either the "out" kwarg
is the end of the every signature, or it is the first kwarg in every
signature. It's a very special and unusual kwarg, so it should have a
standard location.

For all ufuncs, out arguments come first immediately after in arguments,
so +1 for doing that for consistency.

Agree that that is what to shoot for. The particular problem with `ma.dot`
is that it already has the `strict` argument where the new `out` argument
should go. I propose the following steps.
1. For backward compatibility, start by adding new arguments to the end
2. Later raise FutureWarning on positional arguments that are out of place
3. Then make all but early arguments keyword only
Once we have keyword only for a while, it would be possible to add some
arguments back as positional arguments, but it might be best to keep them as
keyword only as suggested above.
For the current PR, this means that the dot method will have positional
arguments in a different order than ma.dot. Alternatively, out could be made
keyword only in both, although that would require fixing up some tests.
There is really no magical solution that avoids all difficulties that I can
see.
Unless a consensus develops otherwise, I will pursue step 1. and go for a
1.10.2rc tomorrow.

If we're adding it in a funny place to ma.dot now (the end of the
arglist) with the plan of changing it later, then why not make it
kwarg-only in ma.dot now to start with?

If this turns out to be annoying somehow then go ahead with whatever
as far I'm concerned -- I don't want to hold up 1.10.2 by trying to
micro-optimize the transition path for an obscure corner of np.ma :-).

-n