allow 3-way copy arg to align all constructors

data-apis · leofang · Feb 14, 2024 · Feb 7, 2024 · Feb 8, 2024 · Feb 8, 2024
commit c102bcbb584b506514a4b90be094408f2d1b89e9
diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py
@@ -294,7 +294,7 @@ def __dlpack__(
         stream: Optional[Union[int, Any]] = None,
         max_version: Optional[tuple[int, int]] = None,
         dl_device: Optional[Tuple[Enum, int]] = None,
-        copy: Optional[bool] = False
+        copy: Optional[bool] = None
     ) -> PyCapsule:
         """
         Exports the array for consumption by :func:`~array_api.from_dlpack` as a DLPack capsule.
@@ -335,23 +335,24 @@ def __dlpack__(
                 not want to think about stream handling at all, potentially at the
                 cost of more synchronizations than necessary.
         max_version: Optional[tuple[int, int]]
-            The maximum DLPack version that the *consumer* (i.e., the caller of
+            the maximum DLPack version that the *consumer* (i.e., the caller of
             ``__dlpack__``) supports, in the form of a 2-tuple ``(major, minor)``.
             This method may return a capsule of version ``max_version`` (recommended
             if it does support that), or of a different version.
             This means the consumer must verify the version even when
             `max_version` is passed.
         dl_device: Optional[Tuple[Enum, int]]
-            The DLPack device type. Default is ``None``, meaning the exported capsule
+            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__`.
             If the device type cannot be handled by the producer, this function must
             raise `BufferError`.
         copy: Optional[bool]
-            Whether or not a copy should be made. Default is ``False`` to enable
-            zero-copy data exchange. However, a user can request a copy to be made
-            by the producer (through the consumer's :func:`~array_api.from_dlpack`)
-            to move data across the library (and/or device) boundary.
+            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``.

         Returns
         -------

diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py
@@ -218,7 +218,7 @@ def eye(
 def from_dlpack(
     x: object, /, *,
     device: Optional[device] = None,
-    copy: Optional[bool] = False,
+    copy: Optional[bool] = None
 ) -> Union[array, Any]:
     """
     Returns a new array containing the data from another (array) object with a ``__dlpack__`` method.
@@ -238,7 +238,7 @@ def from_dlpack(
 
         Other kinds of devices will be considered for standardization in a future version.
     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). Default: ``False``.
+        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__`).