[Cython] buffer syntax vs. memory view syntax

[Stefan Behnel]

Dag Sverre Seljebotn, 07.05.2012 19:10:
> On 05/07/2012 07:00 PM, Stefan Behnel wrote:
>> mark florisson, 07.05.2012 18:28:
>>> On 7 May 2012 17:00, Dag Sverre Seljebotn wrote:
>>>> On 05/07/2012 04:16 PM, Stefan Behnel wrote:
>>>>> Stefan Behnel, 07.05.2012 15:04:
>>>>>> Dag Sverre Seljebotn, 07.05.2012 13:48:
>>>>>>> BTW, with the coming of memoryviews, me and Mark talked about just
>>>>>>> deprecating the "mytype[...]" meaning buffers, and rather treat it as
>>>>>>> np.ndarray, array.array etc. being some sort of "template types". That
>>>>>>> is,
>>>>>>> we disallow "object[int]" and require some special declarations in the
>>>>>>> relevant pxd files.
>>>>>>
>>>>>> Hmm, yes, it's unfortunate that we have two different types of syntax
>>>>>> now,
>>>>>> one that declares the item type before the brackets and one that
>>>>>> declares it afterwards.
>>>>>
>>>>> I actually think this merits some more discussion. Should we consider the
>>>>> buffer interface syntax deprecated and focus on the memory view syntax?
>>>>
>>>> I think that's the very-long-term intention. Then again, it may be too
>>>> early
>>>> to really tell yet, we just need to see how the memory views play out in
>>>> real life and whether they'll be able to replace np.ndarray[double] among
>>>> real users. We don't want to shove things down users throats.
>>>>
>>>> But the use of the trailing-[] syntax needs some cleaning up. Me and Mark
>>>> agreed we'd put this proposal forward when we got around to it:
>>>>
>>>>   - Deprecate the "object[double]" form, where [dtype] can be stuck on any
>>>> extension type
>>>>
>>>>   - But, do NOT (for the next year at least) deprecate np.ndarray[double],
>>>> array.array[double], etc. Basically, there should be a magic flag in
>>>> extension type declarations saying "I can be a buffer".
>>>>
>>>> For one thing, that is sort of needed to open up things for templated cdef
>>>> classes/fused types cdef classes, if that is ever implemented.
>>>
>>> Deprecating is definitely a good start.
>>
>> Then the first step on that road is to rework the documentation so that it
>> pushes users into going for memory views instead of the plain buffer syntax.
> 
> -1, premature.

Ok, fine. Then we should at least put them next to each other in the NumPy
docs and explain a) what the differences are and b) which one users should
choose for use cases X, Y and Z.

The docs should also make it clear that using "np.ndarray" is only useful
for making code work with CPython < 2.6 (and maybe some other cases where
NumPy's C-API is leveraged internally), but that this declaration has the
drawback of making code less versatile, e.g. because it will *not* work
with memoryviews and other kinds of buffers but only plain NumPy arrays.
Currently, it basically tells people that statically typed NumPy arrays are
the only way to get things working.

If it's known to be likely that something will become less important or
even deprecated at some point in the future, it's best to make users aware
by adapting the documentation ASAP, so that less impacted code gets written
in the meantime.

Stefan