[Numpy-discussion] numpy.filled, again

Nathaniel Smith njs@pobox....
Wed Jun 12 09:18:31 CDT 2013


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.

-n


More information about the NumPy-Discussion mailing list