[Numpy-discussion] Raveling, reshape order keyword unnecessarily confuses index and memory ordering

[Matthew Brett]

Hi,

On Fri, Apr 5, 2013 at 2:20 AM, Sebastian Berg
<sebastian at sipsolutions.net> wrote:
> Hey
>
> On Thu, 2013-04-04 at 14:20 -0700, Matthew Brett wrote:
>> Hi,
>>
>> On Tue, Apr 2, 2013 at 4:32 AM, Nathaniel Smith <njs at pobox.com> wrote:
>> <snip>
>> > Maybe we should go through and rename "order" to something more descriptive
>> > in each case, so we'd have
>> >   a.reshape(..., index_order="C")
>> >   a.copy(memory_order="F")
>> > etc.?
>>
>> I'd like to propose this instead:
>>
>> a.reshape(..., order="C")
>> a.copy(layout="F")
>>
>
> I actually like this, makes the point clearer that it has to do with
> memory layout and implies contiguity, plus it is short and from the
> numpy perspective copy, etc. are the ones that add additional info to
> "order" and not reshape (because IMO memory order is something new users
> should not worry about at first). A and K orders will still have their
> quirks with np.array and copy=True/False, but for many functions they
> are esoteric anyway.
>
> It will be one hell of a deprecation though, but I am +0.5 for adding an
> alias for now (maybe someone knows an even better name?), but I think
> that in this case, it probably really is better to wait with actual
> deprecation warnings for a few versions, since it touches a *lot* of
> code. Plus I think at the point of starting deprecation warnings (and
> best earlier) numpy should provide an automatic fixer script...
>
> The only counter point that remains for me is the difficulty of
> deprecation, since I think the new name idea is very clean. And this is
> unfortunately even more invasive then the index_order proposal.

I completely agree that we'd have to be gentle with the change.  The
problem we'd want to avoid is people innocently using 'layout' and
finding to their annoyance that the code doesn't work with other
people's numpy.

How about:

Step 1:  'order' remains as named keyword, layout added as alias,
comment on the lines of "layout will become the default keyword for
this option in later versions of numpy; please consider updating any
code that does not need to remain backwards compatible'.

Step 2: default keyword becomes 'layout' with 'order' as alias,
comment like "order is an alias for 'layout' to maintain backwards
compatibility with numpy <= 1.7.1', please update any code that does
not need to maintain backwards compatibility with these numpy
versions'

Step 3: Add deprecation warning for 'order', "order will be removed as
an alias in future versions of numpy"

Step 4: (distant future) Remove alias

?

Cheers,

Matthew