From e605ff22fb79910c550038f0867acc1cb5fa1119 Mon Sep 17 00:00:00 2001 From: tqchen Date: Thu, 11 Dec 2025 14:16:42 -0500 Subject: [PATCH 1/5] [DLPack] Update to include DLPack C Exchange API This PR updates to include dlpack C exchange api for fast exchange at c-extension level without going through python. --- spec/draft/design_topics/data_interchange.rst | 12 ++++++++++++ src/array_api_stubs/_draft/array_object.py | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/spec/draft/design_topics/data_interchange.rst b/spec/draft/design_topics/data_interchange.rst index 3b3040672..727dac34d 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -85,6 +85,18 @@ page gives a high-level specification for data exchange in Python using DLPack. below. They are not required to return an array object from ``from_dlpack`` which conforms to this standard. + +DLPack C Exchange API +--------------------- + +DLPack 1.3 introduces a C-level exchange API that can be used to speed up +data exchange between arrays at the C-extension level. This API is available via +the ``type(array_instance).__dlpack_c_exchange_api__`` attribute on the array type object. +For more details, see the `Python specification of DLPack `__ +We recommend consumer libraries to start first using the python level ``__dlpack__`` first which will covers +most cases, then start to use the C-level ``__dlpack_c_exchange_api__`` for performance critical cases. + + Non-supported use cases ----------------------- diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 144fb7457..6c882ca7c 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -17,6 +17,18 @@ class _array: + """ + Attributes + ---------- + __dlpack_c_exchange_api__: PyCapsule + An optional static array type attribute store in ``type(array_instance).__dlpack_c_exchange_api__`` + that can be used to retrieve the DLPack C-API exchange API struct in DLPack 1.3 or later to speed up + exchange of array data at the C extension level without going through Python-level exchange. + See :ref:`data-interchange` section for more details. + """ + # use None for placeholder + __dlpack_c_exchange_api__: PyCapsule = None + def __init__(self: array) -> None: """Initialize the attributes for the array object class.""" From fe57b42d89d6a279c105bb292932a4919aa8322c Mon Sep 17 00:00:00 2001 From: tqchen Date: Thu, 5 Mar 2026 12:00:02 -0500 Subject: [PATCH 2/5] address review comments --- spec/draft/API_specification/array_object.rst | 1 + spec/draft/design_topics/data_interchange.rst | 3 ++- src/array_api_stubs/_draft/array_object.py | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index e3c7e8ae6..97befe62c 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -273,6 +273,7 @@ Attributes array.shape array.size array.T + array.__dlpack_c_exchange_api__ ------------------------------------------------- diff --git a/spec/draft/design_topics/data_interchange.rst b/spec/draft/design_topics/data_interchange.rst index 727dac34d..60a45f0cf 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -92,8 +92,9 @@ DLPack C Exchange API DLPack 1.3 introduces a C-level exchange API that can be used to speed up data exchange between arrays at the C-extension level. This API is available via the ``type(array_instance).__dlpack_c_exchange_api__`` attribute on the array type object. +This is a static global object shared across all the array instances of the same type. For more details, see the `Python specification of DLPack `__ -We recommend consumer libraries to start first using the python level ``__dlpack__`` first which will covers +We recommend consumer libraries to start first using the Python-level ``__dlpack__`` first which will covers most cases, then start to use the C-level ``__dlpack_c_exchange_api__`` for performance critical cases. diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 6c882ca7c..573729ee0 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -21,7 +21,7 @@ class _array: Attributes ---------- __dlpack_c_exchange_api__: PyCapsule - An optional static array type attribute store in ``type(array_instance).__dlpack_c_exchange_api__`` + An optional static array type attribute stored in ``type(array_instance).__dlpack_c_exchange_api__`` that can be used to retrieve the DLPack C-API exchange API struct in DLPack 1.3 or later to speed up exchange of array data at the C extension level without going through Python-level exchange. See :ref:`data-interchange` section for more details. From 9f9cebfd98318eada8d88e17ab3b6300527980a3 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 6 Mar 2026 12:25:51 +0100 Subject: [PATCH 3/5] fix linter complaint --- src/array_api_stubs/_draft/array_object.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 573729ee0..6ec5b8cec 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -26,6 +26,7 @@ class _array: exchange of array data at the C extension level without going through Python-level exchange. See :ref:`data-interchange` section for more details. """ + # use None for placeholder __dlpack_c_exchange_api__: PyCapsule = None From b07236b017b58dc29c81934c486a8983e349ce58 Mon Sep 17 00:00:00 2001 From: tqchen Date: Fri, 6 Mar 2026 06:54:29 -0500 Subject: [PATCH 4/5] Update to property --- src/array_api_stubs/_draft/array_object.py | 33 +++++++++++++--------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 6ec5b8cec..2fee41ce7 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -17,19 +17,6 @@ class _array: - """ - Attributes - ---------- - __dlpack_c_exchange_api__: PyCapsule - An optional static array type attribute stored in ``type(array_instance).__dlpack_c_exchange_api__`` - that can be used to retrieve the DLPack C-API exchange API struct in DLPack 1.3 or later to speed up - exchange of array data at the C extension level without going through Python-level exchange. - See :ref:`data-interchange` section for more details. - """ - - # use None for placeholder - __dlpack_c_exchange_api__: PyCapsule = None - def __init__(self: array) -> None: """Initialize the attributes for the array object class.""" @@ -132,6 +119,26 @@ def T(self: array) -> array: Limiting the transpose to two-dimensional arrays (matrices) deviates from the NumPy et al practice of reversing all axes for arrays having more than two-dimensions. This is intentional, as reversing all axes was found to be problematic (e.g., conflicting with the mathematical definition of a transpose which is limited to matrices; not operating on batches of matrices; et cetera). In order to reverse all axes, one is recommended to use the functional ``permute_dims`` interface found in this specification. """ + + @property + def __dlpack_c_exchange_api__(self: array) -> PyCapsule: + """ + + An optional static array type attribute stored in ``type(array_instance).__dlpack_c_exchange_api__`` + that can be used to retrieve the DLPack C-API exchange API struct in DLPack 1.3 or later to speed up + exchange of array data at the C extension level without going through Python-level exchange. + See :ref:`data-interchange` section for more details. + + Returns + ------- + out: PyCapsule + The PyCapsule object containing the DLPack C-API exchange API struct. + + .. note:: + This is a static global object shared across all the array instances of the same type. + It can be queried through the ``type(array_instance).__dlpack_c_exchange_api__`` attribute. + """ + def __abs__(self: array, /) -> array: """ Calculates the absolute value for each element of an array instance. From fe9b3023a367ea476b52bca11cae86a0429231dc Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 6 Mar 2026 13:42:02 +0100 Subject: [PATCH 5/5] fix rendering issue, add one-line summary for new attribute --- src/array_api_stubs/_draft/array_object.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py index 2fee41ce7..785acdc52 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -119,10 +119,10 @@ def T(self: array) -> array: Limiting the transpose to two-dimensional arrays (matrices) deviates from the NumPy et al practice of reversing all axes for arrays having more than two-dimensions. This is intentional, as reversing all axes was found to be problematic (e.g., conflicting with the mathematical definition of a transpose which is limited to matrices; not operating on batches of matrices; et cetera). In order to reverse all axes, one is recommended to use the functional ``permute_dims`` interface found in this specification. """ - @property def __dlpack_c_exchange_api__(self: array) -> PyCapsule: """ + Object containing the DLPack C-API exchange API struct. An optional static array type attribute stored in ``type(array_instance).__dlpack_c_exchange_api__`` that can be used to retrieve the DLPack C-API exchange API struct in DLPack 1.3 or later to speed up @@ -134,6 +134,7 @@ def __dlpack_c_exchange_api__(self: array) -> PyCapsule: out: PyCapsule The PyCapsule object containing the DLPack C-API exchange API struct. + .. note:: This is a static global object shared across all the array instances of the same type. It can be queried through the ``type(array_instance).__dlpack_c_exchange_api__`` attribute.