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, willIndeed it was, which is why I brought it up :-).

>> 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.

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

Warren

-n

_______________________________________________

NumPy-Discussion mailing list

NumPy-Discussion@scipy.org

http://mail.scipy.org/mailman/listinfo/numpy-discussion