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