Align with dpctl changes for DLPack v1.0 support (#1980)

* Adopt dpnp to DLPack v1.0

* Add more tests to cover different use cases 7c8e83f

Author: github-actions[bot]

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 5a2aabf17785544d6749f88a18e15dfe
+config: 89cb4a5b0282510d312a9965fa4fed0d
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_modules/dpnp/dpnp_array.html

@@ -12,7 +12,7 @@
     </script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>dpnp.dpnp_array &mdash; Data Parallel Extension for NumPy 0.16.0dev0+158.gef4a310502e documentation</title>
+  <title>dpnp.dpnp_array &mdash; Data Parallel Extension for NumPy 0.16.0dev0+159.g7c8e83f7ada documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
 
@@ -23,7 +23,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=3ddceb5c"></script>
+        <script src="../../_static/documentation_options.js?v=cc63d5c7"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -43,7 +43,7 @@
             Data Parallel Extension for NumPy
           </a>
               <div class="version">
-                0.16.0dev0+158.gef4a310502e
+                0.16.0dev0+159.g7c8e83f7ada
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
@@ -282,27 +282,61 @@ <h1>Source code for dpnp.dpnp_array</h1><div class="highlight"><pre>
     <span class="c1"># &#39;__divmod__&#39;,</span>
     <span class="c1"># &#39;__doc__&#39;,</span>
 
-    <span class="k">def</span> <span class="nf">__dlpack__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+    <span class="k">def</span> <span class="nf">__dlpack__</span><span class="p">(</span>
+        <span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">max_version</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">dl_device</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">copy</span><span class="o">=</span><span class="kc">None</span>
+    <span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Produces DLPack capsule.</span>
 
 <span class="sd">        Parameters</span>
 <span class="sd">        ----------</span>
 <span class="sd">        stream : {:class:`dpctl.SyclQueue`, None}, optional</span>
-<span class="sd">            Execution queue to synchronize with. If ``None``,</span>
-<span class="sd">            synchronization is not performed.</span>
+<span class="sd">            Execution queue to synchronize with. If ``None``, synchronization</span>
+<span class="sd">            is not performed.</span>
+<span class="sd">            Default: ``None``.</span>
+<span class="sd">        max_version {tuple of ints, None}, optional</span>
+<span class="sd">            The maximum DLPack version the consumer (caller of ``__dlpack__``)</span>
+<span class="sd">            supports. As ``__dlpack__`` may not always return a DLPack capsule</span>
+<span class="sd">            with version `max_version`, the consumer must verify the version</span>
+<span class="sd">            even if this argument is passed.</span>
+<span class="sd">            Default: ``None``.</span>
+<span class="sd">        dl_device {tuple, None}, optional:</span>
+<span class="sd">            The device the returned DLPack capsule will be placed on. The</span>
+<span class="sd">            device must be a 2-tuple matching the format of</span>
+<span class="sd">            ``__dlpack_device__`` method, an integer enumerator representing</span>
+<span class="sd">            the device type followed by an integer representing the index of</span>
+<span class="sd">            the device.</span>
+<span class="sd">            Default: ``None``.</span>
+<span class="sd">        copy {bool, None}, optional:</span>
+<span class="sd">            Boolean indicating whether or not to copy the input.</span>
+
+<span class="sd">            * If `copy` is ``True``, the input will always be copied.</span>
+<span class="sd">            * If ``False``, a ``BufferError`` will be raised if a copy is</span>
+<span class="sd">              deemed necessary.</span>
+<span class="sd">            * If ``None``, a copy will be made only if deemed necessary,</span>
+<span class="sd">              otherwise, the existing memory buffer will be reused.</span>
+
+<span class="sd">            Default: ``None``.</span>
 
 <span class="sd">        Raises</span>
 <span class="sd">        ------</span>
-<span class="sd">        MemoryError</span>
+<span class="sd">        MemoryError:</span>
 <span class="sd">            when host memory can not be allocated.</span>
-<span class="sd">        DLPackCreationError</span>
-<span class="sd">            when array is allocated on a partitioned</span>
-<span class="sd">            SYCL device, or with a non-default context.</span>
+<span class="sd">        DLPackCreationError:</span>
+<span class="sd">            when array is allocated on a partitioned SYCL device, or with</span>
+<span class="sd">            a non-default context.</span>
+<span class="sd">        BufferError:</span>
+<span class="sd">            when a copy is deemed necessary but `copy` is ``False`` or when</span>
+<span class="sd">            the provided `dl_device` cannot be handled.</span>
 
 <span class="sd">        &quot;&quot;&quot;</span>
 
-        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_array_obj</span><span class="o">.</span><span class="n">__dlpack__</span><span class="p">(</span><span class="n">stream</span><span class="o">=</span><span class="n">stream</span><span class="p">)</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_array_obj</span><span class="o">.</span><span class="n">__dlpack__</span><span class="p">(</span>
+            <span class="n">stream</span><span class="o">=</span><span class="n">stream</span><span class="p">,</span>
+            <span class="n">max_version</span><span class="o">=</span><span class="n">max_version</span><span class="p">,</span>
+            <span class="n">dl_device</span><span class="o">=</span><span class="n">dl_device</span><span class="p">,</span>
+            <span class="n">copy</span><span class="o">=</span><span class="n">copy</span><span class="p">,</span>
+        <span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">__dlpack_device__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>

_modules/dpnp/dpnp_flatiter.html

@@ -12,7 +12,7 @@
     </script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>dpnp.dpnp_flatiter &mdash; Data Parallel Extension for NumPy 0.16.0dev0+158.gef4a310502e documentation</title>
+  <title>dpnp.dpnp_flatiter &mdash; Data Parallel Extension for NumPy 0.16.0dev0+159.g7c8e83f7ada documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
 
@@ -23,7 +23,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=3ddceb5c"></script>
+        <script src="../../_static/documentation_options.js?v=cc63d5c7"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -43,7 +43,7 @@
             Data Parallel Extension for NumPy
           </a>
               <div class="version">
-                0.16.0dev0+158.gef4a310502e
+                0.16.0dev0+159.g7c8e83f7ada
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">

_modules/dpnp/dpnp_iface.html

@@ -12,7 +12,7 @@
     </script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>dpnp.dpnp_iface &mdash; Data Parallel Extension for NumPy 0.16.0dev0+158.gef4a310502e documentation</title>
+  <title>dpnp.dpnp_iface &mdash; Data Parallel Extension for NumPy 0.16.0dev0+159.g7c8e83f7ada documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
 
@@ -23,7 +23,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=3ddceb5c"></script>
+        <script src="../../_static/documentation_options.js?v=cc63d5c7"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -43,7 +43,7 @@
             Data Parallel Extension for NumPy
           </a>
               <div class="version">
-                0.16.0dev0+158.gef4a310502e
+                0.16.0dev0+159.g7c8e83f7ada
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
@@ -562,7 +562,7 @@ <h1>Source code for dpnp.dpnp_iface</h1><div class="highlight"><pre>
 
 <div class="viewcode-block" id="from_dlpack">
 <a class="viewcode-back" href="../../reference/generated/dpnp.from_dlpack.html#dpnp.from_dlpack">[docs]</a>
-<span class="k">def</span> <span class="nf">from_dlpack</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="o">/</span><span class="p">):</span>
+<span class="k">def</span> <span class="nf">from_dlpack</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">device</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">copy</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Create a dpnp array from a Python object implementing the ``__dlpack__``</span>
 <span class="sd">    protocol.</span>
@@ -574,17 +574,46 @@ <h1>Source code for dpnp.dpnp_iface</h1><div class="highlight"><pre>
 <span class="sd">    obj : object</span>
 <span class="sd">        A Python object representing an array that implements the ``__dlpack__``</span>
 <span class="sd">        and ``__dlpack_device__`` methods.</span>
+<span class="sd">    device : {:class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`,</span>
+<span class="sd">              :class:`dpctl.tensor.Device`, tuple, None}, optional</span>
+<span class="sd">        Array API concept of a device where the output array is to be placed.</span>
+<span class="sd">        ``device`` can be ``None``, an oneAPI filter selector string,</span>
+<span class="sd">        an instance of :class:`dpctl.SyclDevice` corresponding to</span>
+<span class="sd">        a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`,</span>
+<span class="sd">        a :class:`dpctl.tensor.Device` object returned by</span>
+<span class="sd">        :attr:`dpctl.tensor.usm_ndarray.device`, or a 2-tuple matching</span>
+<span class="sd">        the format of the output of the ``__dlpack_device__`` method,</span>
+<span class="sd">        an integer enumerator representing the device type followed by</span>
+<span class="sd">        an integer representing the index of the device.</span>
+<span class="sd">        Default: ``None``.</span>
+<span class="sd">    copy {bool, None}, optional</span>
+<span class="sd">        Boolean indicating whether or not to copy the input.</span>
+
+<span class="sd">        * If `copy``is ``True``, the input will always be copied.</span>
+<span class="sd">        * If ``False``, a ``BufferError`` will be raised if a copy is deemed</span>
+<span class="sd">          necessary.</span>
+<span class="sd">        * If ``None``, a copy will be made only if deemed necessary, otherwise,</span>
+<span class="sd">          the existing memory buffer will be reused.</span>
+
+<span class="sd">        Default: ``None``.</span>
 
 <span class="sd">    Returns</span>
 <span class="sd">    -------</span>
 <span class="sd">    out : dpnp_array</span>
 <span class="sd">        Returns a new dpnp array containing the data from another array</span>
 <span class="sd">        (obj) with the ``__dlpack__`` method on the same device as object.</span>
 
+<span class="sd">    Raises</span>
+<span class="sd">    ------</span>
+<span class="sd">    TypeError:</span>
+<span class="sd">        if `obj` does not implement ``__dlpack__`` method</span>
+<span class="sd">    ValueError:</span>
+<span class="sd">        if the input array resides on an unsupported device</span>
+
 <span class="sd">    &quot;&quot;&quot;</span>
 
-    <span class="n">usm_ary</span> <span class="o">=</span> <span class="n">dpt</span><span class="o">.</span><span class="n">from_dlpack</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span>
-    <span class="k">return</span> <span class="n">dpnp_array</span><span class="o">.</span><span class="n">_create_from_usm_ndarray</span><span class="p">(</span><span class="n">usm_ary</span><span class="p">)</span></div>
+    <span class="n">usm_res</span> <span class="o">=</span> <span class="n">dpt</span><span class="o">.</span><span class="n">from_dlpack</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">device</span><span class="o">=</span><span class="n">device</span><span class="p">,</span> <span class="n">copy</span><span class="o">=</span><span class="n">copy</span><span class="p">)</span>
+    <span class="k">return</span> <span class="n">dpnp_array</span><span class="o">.</span><span class="n">_create_from_usm_ndarray</span><span class="p">(</span><span class="n">usm_res</span><span class="p">)</span></div>
 
 
 

_modules/dpnp/dpnp_iface_arraycreation.html

@@ -12,7 +12,7 @@
     </script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>dpnp.dpnp_iface_arraycreation &mdash; Data Parallel Extension for NumPy 0.16.0dev0+158.gef4a310502e documentation</title>
+  <title>dpnp.dpnp_iface_arraycreation &mdash; Data Parallel Extension for NumPy 0.16.0dev0+159.g7c8e83f7ada documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
 
@@ -23,7 +23,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=3ddceb5c"></script>
+        <script src="../../_static/documentation_options.js?v=cc63d5c7"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -43,7 +43,7 @@
             Data Parallel Extension for NumPy
           </a>
               <div class="version">
-                0.16.0dev0+158.gef4a310502e
+                0.16.0dev0+159.g7c8e83f7ada
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">

_modules/dpnp/dpnp_iface_counting.html

@@ -12,7 +12,7 @@
     </script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>dpnp.dpnp_iface_counting &mdash; Data Parallel Extension for NumPy 0.16.0dev0+158.gef4a310502e documentation</title>
+  <title>dpnp.dpnp_iface_counting &mdash; Data Parallel Extension for NumPy 0.16.0dev0+159.g7c8e83f7ada documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
 
@@ -23,7 +23,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=3ddceb5c"></script>
+        <script src="../../_static/documentation_options.js?v=cc63d5c7"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -43,7 +43,7 @@
             Data Parallel Extension for NumPy
           </a>
               <div class="version">
-                0.16.0dev0+158.gef4a310502e
+                0.16.0dev0+159.g7c8e83f7ada
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">

_modules/dpnp/dpnp_iface_histograms.html

@@ -12,7 +12,7 @@
     </script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>dpnp.dpnp_iface_histograms &mdash; Data Parallel Extension for NumPy 0.16.0dev0+158.gef4a310502e documentation</title>
+  <title>dpnp.dpnp_iface_histograms &mdash; Data Parallel Extension for NumPy 0.16.0dev0+159.g7c8e83f7ada documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
 
@@ -23,7 +23,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=3ddceb5c"></script>
+        <script src="../../_static/documentation_options.js?v=cc63d5c7"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -43,7 +43,7 @@
             Data Parallel Extension for NumPy
           </a>
               <div class="version">
-                0.16.0dev0+158.gef4a310502e
+                0.16.0dev0+159.g7c8e83f7ada
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">