[Numpy-discussion] defining a NumPy API standard?

[Charles R Harris]

On Sat, Jun 1, 2019 at 10:12 AM Marten van Kerkwijk <
m.h.vankerkwijk at gmail.com> wrote:

> Hi Ralf,
>
> Despite sharing Nathaniel's doubts about the ease of defining the numpy
> API and the likelihood of people actually sticking to a limited subset of
> what numpy exposes, I quite like the actual things you propose to do!
>
> But my liking it is for reasons that are different from your stated ones:
> I think the proposed actions are likely to benefit greatly  both for users
> (like Bill above) and current and prospective developers.  To me, it seems
> almost as a side benefit (if a very nice one) that it might help other
> projects to share an API; a larger benefit may come from tapping into the
> experience of other projects in thinking about what are the true  basic
> functions/method that one should have.
>

I generally agree with this. The most useful aspect of this exercise is
likely to be clarifying NumPy for its own developers, and maybe offering a
guide to future simplification. Trying to put something together that
everyone agrees to as an official standard would be a big project and, as
Nathaniel points out, would involve an enormous amount of work, much time,
and doubtless many arguments.  What might be a less ambitious exercise
would be identifying commonalities in the current numpy-like languages.
That would have the advantage of feedback from actual user experience, and
would be more like a lessons learned document that would be helpful to
others.


> More concretely, to address Nathaniel's (very reasonable) worry about
> ending up wasting a lot of time, I think it may be good to identify smaller
> parts, each of which are useful on their own.
>
> In this respect, I think an excellent place to start might be something
> you are planning already anyway: update the user documentation. Doing this
> will necessarily require thinking about, e.g., what `ndarray` methods and
> properties are actually fundamental, as you only want to focus on a few.
> With that in place, one could then, as you suggest, reorganize the
> reference documentation to put those most important properties up front,
> and ones that we really think are mistakes at the bottom, with explanations
> of why we think so and what the alternative is. Also for the reference
> documentation, it would help to group functions more logically.
>

I keep thinking duck type. Or in this case, duck type lite.


> The above could lead to three next steps, all of which I think would be
> useful. First, for (prospective) developers as well as for future
> maintenance, I think it would be quite a large benefit if we (slowly but
> surely) rewrote code that implements the less basic functionality in terms
> of more basic functions (e.g., replace use of `array.fill(...)` or
> `np.copyto(array, ...)` with `array[...] =`).
>
>
I've had similar thoughts.


> Second, we could update Nathaniel's NEP about distinct properties duck
> arrays might want to mimic/implement.
>
>
Yes.


> Third, we could actual implementing the logical groupings identified in
> the code base (and describing them!). Currently, it is a mess: for the C
> files, I typically have to grep to even find where things are done, and
> while for the functions defined in python files that is not necessary, many
> have historical rather than logical groupings (looking at you,
> `from_numeric`!), and even more descriptive ones like `shape_base` are
> split over `lib` and `core`. I think it would help everybody if we went to
> a python-like layout, with a true core and libraries such as polynomial,
> fft, ma, etc.
>
> Anyway, re-reading your message, I realize the above is not really what
> you wrote about, so perhaps this is irrelevant...
>
>
Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20190601/c4eca86f/attachment-0001.html>