[DLPack] Update to include DLPack C Exchange API

spec/draft/API_specification/array_object.rst

@@ -273,6 +273,7 @@ Attributes
    array.shape
    array.size
    array.T
+   array.__dlpack_c_exchange_api__
 
 -------------------------------------------------
 

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 <https://dmlc.github.io/dlpack/latest/python_spec.html>`__
+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
 -----------------------
 

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.