On Wed, Jun 12, 2013 at 10:18 AM, Nathaniel Smith <njs@pobox.com> wrote:
On Wed, Jun 12, 2013 at 1:28 PM, Matthew Brett <matthew.brett@gmail.com> wrote:
On Wed, Jun 12, 2013 at 1:10 PM, Nathaniel Smith <njs@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.
Another idea (also imperfect): call the new functions `filledwith` and `filledwith_like`. Not as concise as `filled`, but the meaning is still clear, and it avoids the clash with `ma.filled`. Warren
-n _______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion