[Numpy-discussion] numpy.filled, again

[Warren Weckesser]

On Wed, Jun 12, 2013 at 10:18 AM, Nathaniel Smith <njs at pobox.com> wrote:

> On Wed, Jun 12, 2013 at 1:28 PM, Matthew Brett <matthew.brett at gmail.com>
> wrote:
> > On Wed, Jun 12, 2013 at 1:10 PM, Nathaniel Smith <njs at 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 at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20130612/868e0ba8/attachment.html>