Hi, On Fri, Apr 5, 2013 at 8:31 PM, <josef.p...@gmail.com> wrote: > On Fri, Apr 5, 2013 at 10:47 PM, Matthew Brett <matthew.br...@gmail.com> > wrote: >> Hi, >> >> On Fri, Apr 5, 2013 at 7:39 PM, <josef.p...@gmail.com> wrote: >>> On Fri, Apr 5, 2013 at 9:50 PM, Matthew Brett <matthew.br...@gmail.com> >>> wrote: >>>> Hi, >>>> >>>> On Fri, Apr 5, 2013 at 4:27 PM, <josef.p...@gmail.com> wrote: >>>>> On Fri, Apr 5, 2013 at 6:09 PM, Matthew Brett <matthew.br...@gmail.com> >>>>> wrote: >>>>>> Hi, >>>>>> >>>>>> On Fri, Apr 5, 2013 at 12:53 PM, Ralf Gommers <ralf.gomm...@gmail.com> >>>>>> wrote: >>>>>>> >>>>>>> >>>>>>> >>>>>>> On Fri, Apr 5, 2013 at 9:21 PM, Matthew Brett <matthew.br...@gmail.com> >>>>>>> wrote: >>>>>>>> >>>>>>>> Hi, >>>>>>>> >>>>>>>> On Fri, Apr 5, 2013 at 3:09 PM, Ralf Gommers <ralf.gomm...@gmail.com> >>>>>>>> wrote: >>>>>>>> > >>>>>>>> > >>>>>>>> > >>>>>>>> > On Fri, Apr 5, 2013 at 5:13 PM, Matthew Brett >>>>>>>> > <matthew.br...@gmail.com> >>>>>>>> > wrote: >>>>>>>> >> >>>>>>>> >> Hi, >>>>>>>> >> >>>>>>>> >> On Fri, Apr 5, 2013 at 2:20 AM, Sebastian Berg >>>>>>>> >> <sebast...@sipsolutions.net> wrote: >>>>>>>> >> > Hey >>>> <snip> >>>>>>>> >> 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 >>>>>>>> >> >>>>>>>> >> ? >>>>>>>> > >>>>>>>> > >>>>>>>> > A very strong -1 from me. Now we're talking about deprecation >>>>>>>> > warnings >>>>>>>> > and a >>>>>>>> > backwards compatibility break after all. I thought we agreed that >>>>>>>> > this >>>>>>>> > was a >>>>>>>> > very bad idea, so why are you proposing it now? >>>>>>>> > >>>>>>>> > Here's how I see it: deprecation of "order" is a no go. Therefore we >>>>>>>> > have >>>>>>>> > two choices here: >>>>>>>> > 1. Simply document the current "order" keyword better and leave it at >>>>>>>> > that. >>>>>>>> > 2. Add a "layout" (or "index_order") keyword, and live with both >>>>>>>> > "order" >>>>>>>> > and >>>>>>>> > "layout" keywords forever. >>>>>>>> > >>>>>>>> > (2) is at least as confusing as (1), more work and poor design. >>>>>>>> > Therefore I >>>>>>>> > propose to go with (1). >>>>>>>> >>>>>>>> You are saying that deprecation of 'order' at any stage in the next 10 >>>>>>>> years of numpy's lifetime is a no go? >>>>>>> >>>>>>> >>>>>>> For something like this? Yes. >>>>>> >>>>>> You are saying I think that I am wrong in thinking this is an >>>>>> important change that will make numpy easier to explain and use in the >>>>>> long term. >>>>>> >>>>>> You'd probably expect me to disagree, and I do. I think I am right in >>>>>> thinking the change is important - I've tried to make that case in >>>>>> this thread, as well as I can. >>>>>> >>>>>>>> I think that is short-sighted and I think it will damage numpy. >>>>>>> >>>>>>> >>>>>>> It will damage numpy to be conservative and not change a name for a >>>>>>> little >>>>>>> bit of clarity for some people that avoids reading the docs maybe a >>>>>>> little >>>>>>> more carefully? There's a lot of things that can damage numpy, but this >>>>>>> isn't even close in my book. Too few developers, continuous backwards >>>>>>> compatibility issues, faster alternative libraries surpassing numpy - >>>>>>> that's >>>>>>> the kind of thing that causes damage. >>>>>> >>>>>> We're talked about consensus on this list. Of course it can be very >>>>>> hard to achieve. >>>>> >>>>> So far the consensus is that the documentation needs improvement. >>>> >>>> The only thing all of the No camp agree with is documentation >>>> improvement, I think that's fair. >>>> >>>>> After that ??? >>>> >>>> Well I think we have: >>>> >>>> Flat-no - the change not important, almost any cost is too high >>> >>> It's not *any* cost, this goes deep and wide, it's one of the basic >>> concepts of numpy that you want to rename. >> >> The proposal I last made was to change the default name to 'layout' >> after some period to be agreed - say - P - with suitable warning in >> the docstring up until that time, and after, and leave 'order' as an >> alias forever. >> >> The only problem I can see with this, is that if someone, after period >> P, does not read the docstring, and uses 'layout' instead of 'order', >> then they will find that their code is not backwards compatible with >> versions of numpy of greater age than P. They can fix this, forever, >> by reverting to 'order'. That's certainly not zero cost, but it's not >> much cost either, and the cost will depend on P. > > You edit large parts of the numpy tutorial and explanations,
We agree that these concepts need to be clarified in the explanations. For the docs, we would first add the keyword as an alias and note it so. > you add a second keyword to (rough guess) 10 functions and > a similar number of methods (even wilder guess), the methods > are in C, so you have to change it both on the c and the python > level. I'm OK to do the code changes, I don't think that's a concern at the moment. If I don't or can't do the code changes then of course it won't happen. > Two keywords will confuse users for a long time > (and which one is in the tutorial documentation) 'order' until expiry of 'P' (with note of planned switch). Then 'layout', with 'order' noted as a backwards compatible alias. I think the alternative keyword will help rather than confuse, and that the confusion is likely to come from using 'order' in the sense of 'layout' - but - hey - you know that already. > I'm just guessing and I have no idea about the c-level. I haven't done this kind of thing before - I imagine it must be fairly straightforward, but if not, then any information about that would be useful to the discussion. Cheers, Matthew _______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
