<div dir="ltr"><div>Yes, the underlying gory details should be spelled out of course but if it is also modifying/adding to API then it is best to sound the horn and invite zombies to take a stab at it. Often people arrive with interesting use-cases that you wouldn't have thought about. <br></div><div><br></div><div>And I am very familiar with the pushback feeling you are having right now, probably internally shouting "where have you been all this time you slackers?". As you might have seen me asking questions here and Cython lists, when I am done with some new feature over SciPy, it is also going to be a very very long and tiring process. I am really not looking forward to it :-)  but I guess it is part of the deal. Maybe I can give some comfort that if more people start to flock over that means it has morphed into a finished product so people can shoot. But, I honestly thought this was a new NEP, that's a mistake on my part. </div><div><br></div><div>For the like, typeof and other candidates, by esoteric I mean foreign enough to most users. We already have a nice candidate I think; ehm... "dispatch" or "dispatch_like" or something like that, nobody sober enough would confuse this with any other. And since this won't be typed in daily usage, or so I understood, 
I guess 

it is ok to make it verbose. But still take it as an initial guess and feel free to dismiss.<br></div><div><br></div><div>I still would be in a platonic love with 
"numpy.DIY"

or "numpy.hermes" namespace with a nice "bring your own _array_function_" service. <br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Aug 13, 2020 at 4:16 PM Peter Andreas Entschev <<a href="mailto:peter@entschev.com">peter@entschev.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Ilhan,<br>
<br>
Thanks, that does clarify things.<br>
<br>
I think the main point -- and correct me here if I'm still wrong -- is<br>
that we want the NEP to have some very clear example of when/why/how<br>
to use it, preferably as early in the text as possible, maybe just<br>
below the Abstract, in a Motivation and Scope section, as the NEP<br>
Template [6] pointed out to by Ralf earlier suggests. That is a<br>
totally valid ask, and I'll try to address it as soon as possible<br>
(hopefully today or tomorrow).<br>
<br>
To the point of whether NEPs are to be read by users, I normally don't<br>
expect users to be required to read and understand those NEPs other<br>
than by pure curiosity. If we need them to do so, then there's<br>
definitely a big problem in the API. This may sound counterintuitive<br>
with what I said before about the "like=" name, but that's really the<br>
piece of the NumPy API that I with a somewhat reasonable understand of<br>
arrays don't quite get or like, for instance "asarray" and "like"<br>
sound exactly the same thing, but they're not in the NumPy context,<br>
and on the other hand it's quite difficult to find a reasonable name<br>
to clarify that. And once more, I do like the "typeof=" suggestion<br>
more than "like=" to be perfectly honest, I'm just afraid it could be<br>
mistaken by the "dtype=" keyword somehow and thus still not solve the<br>
clarity problem. Going back to users reading NEPs or not, I would<br>
really expect that the docstring from the function is sufficiently<br>
clear to keep users off of it, but still give them an understanding of<br>
why that exists, the current docstring is in [9], please do comment on<br>
it if you have ideas of how to make it more accessible to users.<br>
<br>
You also mentioned you'd like that the name is as esoteric as<br>
possible, do you have any suggestions for an esoteric name that is<br>
hopefully unambiguous too? Naming has definitely been very much on the<br>
table since the NEP was written, but the consensus was more that<br>
"like=" is reasonably similar enough in both application and the name<br>
itself to "empty_like" and derived functions, that's why we just stuck<br>
to it.<br>
<br>
Best,<br>
Peter<br>
<br>
[9] <a href="https://github.com/numpy/numpy/pull/16935/files#diff-e5969453e399f2d32519d305b2582da9R16-R22" rel="noreferrer" target="_blank">https://github.com/numpy/numpy/pull/16935/files#diff-e5969453e399f2d32519d305b2582da9R16-R22</a><br>
<br>
On Thu, Aug 13, 2020 at 3:43 PM Ilhan Polat <<a href="mailto:ilhanpolat@gmail.com" target="_blank">ilhanpolat@gmail.com</a>> wrote:<br>
><br>
> To maybe lighten up the discussion a bit and to make my outsider confusion more tangible, let me start by apologizing for diving head first without weighing the past luggage :-) I always forget how much effort goes into these things and for outsiders like me, it's a matter of dipping the finger and tasting it just before starting to complain how much salt is missing etc. What I was mentioning about NEPs wasn't only related specifically to this one by the way. It's the generic feeling that I have.<br>
><br>
> First let me start what I mean by NumPy users and downstreamers distinction. This is very much related to how data-science and huge-array users are magnetizing every tool out there in the Python world which is fine though the majority of number-crunchers have nothing to do with any of GPU/Parallelism/ClusterUsage etc. Hence when I mention NumPy users, think of people who use NumPy as its own right with no duck-typing and nothing related to subclassing. Just straightforward array creation and lots of ops on these arrays. For those people (I'm one of them), this option brings in a keyword that we would never use. And it gets into many major functions (linspace and others mentioned somewhere). So it has a very appealing name but has nothing to do with me in an already very crowded namespace and keyword catalogue. That's basically a UX issue to be addressed (under the assumption that users like me are the majority). Either making its name as esoteric as possible so I naturally stay away from it or I don't see it. This has absolutely nothing to do with looking down on the downstream libraries. They are flat-out amazing and the more we can support them the merrier.<br>
><br>
> Using yet another metaphor, I was hoping that NumPy would have a loading dock for heavy duty deliveries for downstream projects or specialized array creations and won't disturb the regular customer entrance. Because if I look at this page <a href="https://numpy.org/doc/stable/referenc/routines.array-creation.html" rel="noreferrer" target="_blank">https://numpy.org/doc/stable/referenc/routines.array-creation.html</a>, there are a lot of functions and I think most of them are candidates to gain this keyword.  I wish I can comment on a viable alternative but I really cannot understand the _array_xxxx_ discussions since they fly way over my head no matter how many times I tried. So that's why I naively mentioned the "np.astypedarray" or "np.asarray_but_not_numpy_array" or whatever. Now I see that it is even more complicated and I generated extra noise. So you can just ignore my previous suggestions. Except that I want to draw attention to the UX problem and I'd like to leave it at that.<br>
><br>
> The other point is about the NEP stuff. I think I need to elaborate. If the NEPs are meant for internal NumPy discussions, then by all means, crank up the pointer*-meter to 11 and dive into it, totally fine with me. But if you also want to get feedback from outside, then probably a few lines of code examples for mere mortals would go a long way. Also it would make the discussion much more streamlined in my humble opinion. What I was trying to get at was that almost all NEPs read like a legal document that I want to agree as soon as possible. Because they often come without any or minimal amount of code in it. In NEP35 for example, there are nice code blocks in function dispatching but I guess it's not meant for me. Because it is only decorating asarray with some black magic happening there somehow (I guess). So I can't even comprehend what the proposition would mean for the regular, friendly, anti-duck users. But I am pretty sure it is about dispatching something because the word is repeated ~20 times :-)  Thus the feedback would be limited. That was also what I meant there. But again I totally understand the complexity of these issues. So I'm not expecting to understand all details of NumPy machinery in a single NEP.<br>
><br>
> But anyways, hope this clarifies a few things that I failed to convey in my previous mail.<br>
> ilhan<br>
><br>
><br>
><br>
> On Thu, Aug 13, 2020 at 2:23 PM Ralf Gommers <<a href="mailto:ralf.gommers@gmail.com" target="_blank">ralf.gommers@gmail.com</a>> wrote:<br>
>><br>
>> Thanks for raising these concerns Ilhan and Juan, and for answering Peter. Let me give my perspective as well.<br>
>><br>
>> To start with, this is not specifically about Peter's NEP and PR. NEP 35 simply follows the pattern set by previous PRs, and given its tight scope is less difficult to understand than other NEPs on such technical topics. Peter has done a lot of things right, and is close to the finish line.<br>
>><br>
>><br>
>> On Thu, Aug 13, 2020 at 12:02 PM Peter Andreas Entschev <<a href="mailto:peter@entschev.com" target="_blank">peter@entschev.com</a>> wrote:<br>
>>><br>
>>><br>
>>> > I think, arriving to an agreement would be much faster if there is an executive summary of who this is intended for and what the regular usage is. Because with no offense, all I see is "dispatch", "_array_function_" and a lot of technical details of which I am absolutely ignorant.<br>
>>><br>
>>> This is what I intended to do in the Usage Guidance [2] section. Could<br>
>>> you elaborate on what more information you'd want to see there? Or is<br>
>>> it just a matter of reorganizing the NEP a bit to try and summarize<br>
>>> such things right at the top?<br>
>><br>
>><br>
>> We adapted the NEP template [6] several times last year to try and improve this. And specified in there as well that NEP content set to the mailing list should only contain the sections: Abstract, Motivation and Scope, Usage and Impact, and Backwards compatibility. This to ensure we fully understand the "why" and "what" before the "how". Unfortunately that template and procedure hasn't been exercised much yet, only in NEP 38 [7] and partially in NEP 41 [8].<br>
>><br>
>> If we have long-time maintainers of SciPy (Ilhan and myself), scikit-image (Juan) and CuPy (Leo, on the PR review) all saying they don't understand the goals, relevance, target audience, or how they're supposed to use a new feature, that indicates that the people doing the writing and having the discussion are doing something wrong at a very fundamental level.<br>
>><br>
>> At this point I'm pretty disappointed in and tired of how we write and discuss NEPs on technical topics like dispatching, dtypes and the like. People literally refuse to write down concrete motivations, goals and non-goals, code that's problematic now and will be better/working post-NEP and usage examples before launching into extensive discussion of the gory details of the internals. I'm not sure what to do about it. Completely separate API and behavior proposals from implementation proposals? Make separate "API" and "internals" teams with the likes of Juan, Ilhan and Leo on the API team which then needs to approve every API change in new NEPs? Offer to co-write NEPs if someone is willing but doesn't understand how to go about it? Keep the current structure/process but veto further approvals until NEP authors get it right?<br>
>><br>
>> I want to make an exception for merging the current NEP, for which the plan is to merge it as experimental to try in downstream PRs and get more experience. That does mean that master will be in an unreleasable state by the way, which is unusual and it'd be nice to get Chuck's explicit OK for that. But after that, I think we need a change here. I would like to hear what everyone thinks is the shape that change should take - any of my above suggestions, or something else?<br>
>><br>
>><br>
>>><br>
>>> > Finally as a minor point, I know we are mostly (ex-)academics but this necessity of formal language on NEPs is self-imposed (probably PEPs are to blame) and not quite helping. It can be a bit more descriptive in my external opinion.<br>
>>><br>
>>> TBH, I don't really know how to solve that point, so if you have any<br>
>>> specific suggestions, that's certainly welcome. I understand the<br>
>>> frustration for a reader trying to understand all the details, with<br>
>>> many being only described in NEP-18 [3], but we also strive to avoid<br>
>>> rewriting things that are written elsewhere, which would also<br>
>>> overburden those who are aware of what's being discussed.<br>
>>><br>
>>><br>
>>> > I also share Ilhan’s concern (and I mentioned this in a previous NEP discussion) that NEPs are getting pretty inaccessible. In a sense these are difficult topics and readers should be expected to have *some* familiarity with the topics being discussed, but perhaps more effort should be put into the context/motivation/background of a NEP before accepting it. One way to ensure this might be to require a final proofreading step by someone who has not been involved at all in the discussions, like peer review does for papers.<br>
>><br>
>><br>
>> Some variant of this proposal would be my preference.<br>
>><br>
>> Cheers,<br>
>> Ralf<br>
>><br>
>>><br>
>>> [1] <a href="https://github.com/numpy/numpy/issues/14441#issuecomment-529969572" rel="noreferrer" target="_blank">https://github.com/numpy/numpy/issues/14441#issuecomment-529969572</a><br>
>>> [2] <a href="https://numpy.org/neps/nep-0035-array-creation-dispatch-with-array-function.html#usage-guidance" rel="noreferrer" target="_blank">https://numpy.org/neps/nep-0035-array-creation-dispatch-with-array-function.html#usage-guidance</a><br>
>>> [3] <a href="https://numpy.org/neps/nep-0018-array-function-protocol.html" rel="noreferrer" target="_blank">https://numpy.org/neps/nep-0018-array-function-protocol.html</a><br>
>>> [4] <a href="https://numpy.org/neps/nep-0000.html#nep-workflow" rel="noreferrer" target="_blank">https://numpy.org/neps/nep-0000.html#nep-workflow</a><br>
>>> [5] <a href="https://mail.python.org/pipermail/numpy-discussion/2019-October/080176.html" rel="noreferrer" target="_blank">https://mail.python.org/pipermail/numpy-discussion/2019-October/080176.html</a><br>
>><br>
>><br>
>> [6] <a href="https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst" rel="noreferrer" target="_blank">https://github.com/numpy/numpy/blob/master/doc/neps/nep-template.rst</a><br>
>> [7] <a href="https://github.com/numpy/numpy/blob/master/doc/neps/nep-0038-SIMD-optimizations.rst" rel="noreferrer" target="_blank">https://github.com/numpy/numpy/blob/master/doc/neps/nep-0038-SIMD-optimizations.rst</a><br>
>> [8] <a href="https://github.com/numpy/numpy/blob/master/doc/neps/nep-0041-improved-dtype-support.rst" rel="noreferrer" target="_blank">https://github.com/numpy/numpy/blob/master/doc/neps/nep-0041-improved-dtype-support.rst</a><br>
>><br>
>><br>
>>><br>
>>><br>
>>><br>
>>> On Thu, Aug 13, 2020 at 3:44 AM Juan Nunez-Iglesias <<a href="mailto:jni@fastmail.com" target="_blank">jni@fastmail.com</a>> wrote:<br>
>>> ><br>
>>> > I’ve generally been on the “let the NumPy devs worry about it” side of things, but I do agree with Ilhan that `like=` is confusing and `typeof=` would be a much more appropriate name for that parameter.<br>
>>> ><br>
>>> > I do think library writers are NumPy users and so I wouldn’t really make that distinction, though. Users writing their own analysis code could very well be interested in writing code using numpy functions that will transparently work when the input is a CuPy array or whatever.<br>
>>> ><br>
>>> > I also share Ilhan’s concern (and I mentioned this in a previous NEP discussion) that NEPs are getting pretty inaccessible. In a sense these are difficult topics and readers should be expected to have *some* familiarity with the topics being discussed, but perhaps more effort should be put into the context/motivation/background of a NEP before accepting it. One way to ensure this might be to require a final proofreading step by someone who has not been involved at all in the discussions, like peer review does for papers.<br>
>>> ><br>
>>> > Food for thought.<br>
>>> ><br>
>>> > Juan.<br>
>>> ><br>
>>> > On 13 Aug 2020, at 9:24 am, Ilhan Polat <<a href="mailto:ilhanpolat@gmail.com" target="_blank">ilhanpolat@gmail.com</a>> wrote:<br>
>>> ><br>
>>> > For what is worth, as a potential consumer in SciPy, it really doesn't say anything (both in NEP and the PR) about how the regular users of NumPy will benefit from this. If only and only 3rd parties are going to benefit from it, I am not sure adding a new keyword to an already confusing function is the right thing to do.<br>
>>> ><br>
>>> > Let me clarify,<br>
>>> ><br>
>>> > - This is already a very (I mean extremely very) easy keyword name to confuse with ones_like, zeros_like and by its nature any other interpretation. It is not signalling anything about the functionality that is being discussed. I would seriously consider reserving such obvious names for really obvious tasks. Because you would also expect the shape and ndim would be mimicked by the "like"d argument but it turns out it is acting more like "typeof=" and not "like=" at all. Because if we follow the semantics it reads as "make your argument asarray like the other thing" but it is actually doing, "make your argument an array with the other thing's type" which might not be an array after all.<br>
>>> ><br>
>>> > - Again, if this is meant for downstream libraries (because that's what I got out of the PR discussion, cupy, dask, and JAX were the only examples I could read) then hiding it in another function and writing with capital letters "this is not meant for numpy users" would be a much more convenient way to separate the target audience and regular users. numpy.astypedarray([[some data], [...]], type_of=x) or whatever else it may be would be quite clean and to the point with no ambiguous keywords.<br>
>>> ><br>
>>> > I think, arriving to an agreement would be much faster if there is an executive summary of who this is intended for and what the regular usage is. Because with no offense, all I see is "dispatch", "_array_function_" and a lot of technical details of which I am absolutely ignorant.<br>
>>> ><br>
>>> > Finally as a minor point, I know we are mostly (ex-)academics but this necessity of formal language on NEPs is self-imposed (probably PEPs are to blame) and not quite helping. It can be a bit more descriptive in my external opinion.<br>
>><br>
>> _______________________________________________<br>
>> NumPy-Discussion mailing list<br>
>> <a href="mailto:NumPy-Discussion@python.org" target="_blank">NumPy-Discussion@python.org</a><br>
>> <a href="https://mail.python.org/mailman/listinfo/numpy-discussion" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/numpy-discussion</a><br>
><br>
> _______________________________________________<br>
> NumPy-Discussion mailing list<br>
> <a href="mailto:NumPy-Discussion@python.org" target="_blank">NumPy-Discussion@python.org</a><br>
> <a href="https://mail.python.org/mailman/listinfo/numpy-discussion" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/numpy-discussion</a><br>
_______________________________________________<br>
NumPy-Discussion mailing list<br>
<a href="mailto:NumPy-Discussion@python.org" target="_blank">NumPy-Discussion@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/numpy-discussion" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/numpy-discussion</a><br>
</blockquote></div>