update to reflect the discussions

Author: leofang

src/array_api_stubs/_draft/array_object.py

@@ -326,6 +326,12 @@ def __dlpack__(
             - ``> 2``: stream number represented as a Python integer.
             - Using ``1`` and ``2`` is not supported.
 
+            .. note::
+                When ``dl_device`` is provided explicitly, ``stream`` must be a valid
+                construct for the specified device type. In particular, when ``kDLCPU``
+                is in use, ``stream`` must be ``None`` and a synchronization must be
+                performed to ensure data safety.
+
             .. admonition:: Tip
                 :class: important
 
@@ -344,16 +350,22 @@ def __dlpack__(
         dl_device: Optional[Tuple[Enum, int]]
             the DLPack device type. Default is ``None``, meaning the exported capsule
             should be on the same device as ``self`` is. When specified, the format
-            must follow that of the return value of :meth:`array.__dlpack_device__`.
+            must be a 2-tuple, following that of the return value of :meth:`array.__dlpack_device__`.
             If the device type cannot be handled by the producer, this function must
-            raise `BufferError`.
+            raise ``BufferError``.
         copy: Optional[bool]
             boolean indicating whether or not to copy the input. If ``True``, the
             function must always copy (paerformed by the producer), potentially allowing
             data movement across the library (and/or device) boundary. If ``False``,
             the function must never copy. If ``None``, the function must reuse existing
             memory buffer if possible and copy otherwise. Default: ``None``.
 
+            When a copy happens, the ``DLPACK_FLAG_BITMASK_IS_COPIED`` flag must be set.
+
+            .. note::
+                If a copy happens, and if the consumer-provided ``stream`` and ``dl_device``
+                can be understood by the producer, the copy must be performed over ``stream``.
+
         Returns
         -------
         capsule: PyCapsule
@@ -413,11 +425,14 @@ def __dlpack__(
         .. code:: python
 
             try:
-                x.__dlpack__(max_version=(1, 0))
+                x.__dlpack__(max_version=(1, 0), ...)
                 # if it succeeds, store info from the capsule named "dltensor_versioned",
                 # and need to set the name to "used_dltensor_versioned" when we're done
             except TypeError:
-                x.__dlpack__()
+                x.__dlpack__(...)
+
+        This logic is also applicable to handling of the new ``dl_device`` and ``copy``
+        keywords.
 
         .. versionchanged:: 2022.12
             Added BufferError.

src/array_api_stubs/_draft/creation_functions.py

@@ -228,19 +228,17 @@ def from_dlpack(
     x: object
         input (array) object.
     device: Optional[device]
-        device on which to place the created array. If ``device`` is ``None`` and ``x`` supports DLPack, the output array device must be inferred from ``x``. Default: ``None``.
+        device on which to place the created array. If ``device`` is ``None`` and ``x`` supports DLPack, the output array device must be inferred from ``x.device``. Default: ``None``.
 
         The v2023.12 standard only mandates that a compliant library must offer a way for ``from_dlpack`` to create an array on CPU (using
-        the library-chosen way to represent the CPU device - ``kDLCPU`` in DLPack - e.g. a ``"CPU"`` string or a ``Device("CPU")`` object).
-        If the compliant library does not support the CPU device and needs to outsource to another (compliant) array library, it may do so
+        a library-specifc way to represent the CPU device (``kDLCPU`` in DLPack) e.g. a ``"CPU"`` string or a ``Device("CPU")`` object).
+        If the array library does not support the CPU device and needs to outsource to another (compliant) array library, it may do so
         with a clear user documentation and/or run-time warning. If a copy must be made to enable this, and ``copy`` is set to ``False``,
         the function must raise ``ValueError``.
 
-        Other kinds of devices will be considered for standardization in a future version.
+        Other kinds of devices will be considered for standardization in a future version of this API standard.
     copy: Optional[bool]
-        boolean indicating whether or not to copy the input. If ``True``, the function must always copy. If ``False``, the function must never copy and must raise a ``BufferError`` in case a copy would be necessary (e.g. the producer disallows views). If ``None``, the function must reuse existing memory buffer if possible and copy otherwise. Default: ``None``.
-
-        If a copy is needed, the stream over which the copy is performed must be taken from the consumer, following the DLPack protocol (see :meth:`array.__dlpack__`).
+        boolean indicating whether or not to copy the input. If ``True``, the function must always copy. If ``False``, the function must never copy and must raise a ``BufferError`` in case a copy is deemed necessary (e.g. the producer disallows views). If ``None``, the function must reuse the existing memory buffer if possible and copy otherwise. Default: ``None``.
 
     Returns
     -------