From 3b7aea6253c718462c37f2bee29b0ee4c8e61e2c Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 16 Nov 2023 22:26:45 +0100 Subject: [PATCH 1/2] Update DLPack content to address unsupported use cases --- spec/draft/design_topics/data_interchange.rst | 16 ++++++++++++++++ src/array_api_stubs/_draft/creation_functions.py | 9 +++++++++ 2 files changed, 25 insertions(+) diff --git a/spec/draft/design_topics/data_interchange.rst b/spec/draft/design_topics/data_interchange.rst index 8686042c8..2520a93ed 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -84,3 +84,19 @@ page gives a high-level specification for data exchange in Python using DLPack. are recommended to do so using the same syntax and semantics as outlined below. They are not required to return an array object from ``from_dlpack`` which conforms to this standard. + +Non-supported use cases +----------------------- + +Use of DLPack requires that the data can be represented by a strided, in-memory +layout on a single device. This covers usage by a large range of, but not all, +known and possible array libraries. Use cases that are not supported by DLPack +include: + +- Distributed arrays, i.e., the data residing on multiple nodes or devices, +- Sparse arrays, i.e., sparse representations where a data value (typically + zero) is implicit. + +There may be other reasons why it is not possible or desirable for an +implementation to materialize the array as strided data in memory. In such +cases, the implementation may raise a `BufferError` in the `__dlpack__` method. diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py index 5e2bb44e6..6713cc7aa 100644 --- a/src/array_api_stubs/_draft/creation_functions.py +++ b/src/array_api_stubs/_draft/creation_functions.py @@ -232,6 +232,15 @@ def from_dlpack(x: object, /) -> array: :class: note The returned array may be either a copy or a view. See :ref:`data-interchange` for details. + + Raises + ------ + BufferError + The ``__dlpack__`` method on the input array may raise ``BufferError`` + when the data cannot be exported as DLPack (e.g., incompatible dtype or + strides). It may also raise other errors when export fails for other + reasons (e.g., not enough memory available to materialize the data). + ``from_dlpack`` must propagate such exceptions. """ From 0f228309d6143522a5f555b90c9426ce2b6a3810 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 17 Nov 2023 12:10:14 +0100 Subject: [PATCH 2/2] Extend the description of errors when DLPack cannot be supported --- spec/draft/design_topics/data_interchange.rst | 5 ++++- src/array_api_stubs/_draft/creation_functions.py | 15 ++++++++++----- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/spec/draft/design_topics/data_interchange.rst b/spec/draft/design_topics/data_interchange.rst index 2520a93ed..3b3040672 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -99,4 +99,7 @@ include: There may be other reasons why it is not possible or desirable for an implementation to materialize the array as strided data in memory. In such -cases, the implementation may raise a `BufferError` in the `__dlpack__` method. +cases, the implementation may raise a `BufferError` in the `__dlpack__` or +`__dlpack_device__` method. In case an implementation is never able to export +its array data via DLPack, it may omit `__dlpack__` and `__dlpack_device__` +completely, and hence `from_dlpack` may raise an `AttributeError`. diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py index 6713cc7aa..69733a646 100644 --- a/src/array_api_stubs/_draft/creation_functions.py +++ b/src/array_api_stubs/_draft/creation_functions.py @@ -236,11 +236,16 @@ def from_dlpack(x: object, /) -> array: Raises ------ BufferError - The ``__dlpack__`` method on the input array may raise ``BufferError`` - when the data cannot be exported as DLPack (e.g., incompatible dtype or - strides). It may also raise other errors when export fails for other - reasons (e.g., not enough memory available to materialize the data). - ``from_dlpack`` must propagate such exceptions. + The ``__dlpack__`` and ``__dlpack_device__`` methods on the input array + may raise ``BufferError`` when the data cannot be exported as DLPack + (e.g., incompatible dtype or strides). It may also raise other errors + when export fails for other reasons (e.g., not enough memory available + to materialize the data). ``from_dlpack`` must propagate such + exceptions. + AttributeError + If the ``__dlpack__`` and ``__dlpack_device__`` methods are not present + on the input array. This may happen for libraries that are never able + to export their data with DLPack. """