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 3b3040672..60a45f0cf 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -85,6 +85,19 @@ 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. +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 +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..785acdc52 100644 --- a/src/array_api_stubs/_draft/array_object.py +++ b/src/array_api_stubs/_draft/array_object.py @@ -119,6 +119,27 @@ 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 + 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.