On Wed, Jun 12, 2013 at 10:18 AM, Nathaniel Smith <n...@pobox.com> wrote:
> On Wed, Jun 12, 2013 at 1:28 PM, Matthew Brett <matthew.br...@gmail.com> > wrote: > > On Wed, Jun 12, 2013 at 1:10 PM, Nathaniel Smith <n...@pobox.com> wrote: > >> Personally I think that overloading np.empty is horribly ugly, will > >> continue confusing newbies and everyone else indefinitely, and I'm > >> 100% convinced that we'll regret implementing such a warty interface > >> for something that should be so idiomatic. (Unfortunately I got busy > >> and didn't actually say this in the previous thread though.) > > > > Maybe you could unpack this, as I seem to remember this was the option > > with the most support previously. > > Indeed it was, which is why I brought it up :-). > > I'm not sure what more there is to unpack, though. It's just... > offensive to every sense of API design I have, I don't know how to > explain more than I have. I speculate that it's only attraction is > that it showed up at the end of a 50 email thread and offered the > promise of ending things, but I don't know. > > Well, here's maybe another way of getting at the ugliness. > > Here's the current doc page listing all the options for creating an > array -- a very useful reference, esp. while learning: > http://docs.scipy.org/doc/numpy/reference/routines.array-creation.html > > Now imagine a new version of this page, if we add 'filled'. There will > be a list at the top with functions named: > empty > filled > ones > zeros > It's immediately obvious what all of these things do, and how they > differ from each other, and in which situation you might want each, > just from the names, even before you read the one-line synopses. Even > more so if you know about the existence of np.fill(). The synopses for > 'ones' and 'zeros' don't even have to change, they already use the > word 'filled' to describe what they do. It all just works. > > Now imagine a different new version of this page, if we overload > 'empty' to add a fill= option. I don't even know how we document that > on this page. The list will remain: > empty > ones > zeros > So there will be no clue there how you get an array filled with NaNs > or whatever, or even any hint that it's possible. Then there's the > prose on the right. Right now the synopsis for 'empty' is: > Return a new array of given shape and type, without initializing entries. > I guess we change this to > Return a new array of given shape and type, without initializing > entries, OR return a new array of given shape and type, with values > initialized to some specific value. > ? IMO probably the single best criterion for judging whether your API > is good, is whether you can write clean and pretty docs for it. This > fails that test horribly... > > We probably should advertise the ndarray constructor more, and > possibly make it more generally useful, but the current situation for > better or worse is that we've spent many years telling people that > it's a weird low-level thing that they shouldn't use. (I didn't even > know how it worked until 10 minutes ago!) Adding this functionality > there means it'll still be hidden away, so it's not a great solution > to the 'filled' problem, and it doesn't really move us any closer to > having a coherent story on when you should use the ndarray constructor > either. > > So IMO the best (least bad) solution on offer is still to just add a > 'filled' function, and live with the np.ma inconsistency. > > But then what do you call the ma version of the new `filled` and `filled_like` functions? Presumably they should be implemented as part of the pull request. Warren > -n > _______________________________________________ > NumPy-Discussion mailing list > NumPy-Discussion@scipy.org > http://mail.scipy.org/mailman/listinfo/numpy-discussion >
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
