API: Specify that DLPack should use BufferError

[seberg]

I would actually like MUST, but since most implementations currently don't actually give a BufferError, writing it as SHOULD instead.

First part of closing numpy/numpy#20742

[oleksandr-pavlyk]

@seberg I assume that this recommendation does not fix the namespace for the actual exception object, right?

[seberg]

BufferError is a python builtin.

[oleksandr-pavlyk]

While DLPack is a buffer conceptually, it is not the buffer as in Py_buffer. Why not introduce dedicated DLPackCreationError in array namespace?

Here is what I had in my POC:

Raises:
    DLPackCreationError: when array can be represented as
        DLPack tensor. This may happen when array was allocated
        on a partitioned sycl device, or its USM allocation is
        not bound to the platform default SYCL context.
    MemoryError: when host allocation to needed for `DLManagedTensor`
        did not succeed.
    ValueError: when array elements data type could not be represented
        in `DLManagedTensor`.

[seberg]

Because then we have to create a new class and put it somewhere? The standard bails on defining most errors, but having a BufferError was useful at least once (mpi4py can retry with the buffer protocol/__array_interface__).

BufferError seems decent for that, it signals the same thing as it does for the Python buffer interface: Export is not possible as requested. And it seems exceedingly unlikely that BufferError is triggered by something else during __dlpack__.

[kgryte]

Based on 11/3/2022 meeting, we are good moving forward with this PR.

[kgryte]

@seberg Removed a duplicated word. Otherwise, LGTM.

[kgryte]

This has received two approvals and was discussed in workgroup meetings. Will merge.