Refined from_dlpack docstrings, reorged impl of from_dlpack

Used try/except/else/finally to avoid raising an exception when
another one is in flight (confusing UX).

device keyword is only allowed to be (kDLCPU, 0) or
(kDLOneAPI, num). Device keyword value is used to create output
array, rather than device_id deduced from it.

Author: oleksandr-pavlyk

dpctl/tensor/_dlpack.pyx

@@ -935,9 +935,8 @@ cpdef object from_dlpack_capsule(object py_caps):
             "The DLPack tensor resides on unsupported device."
         )
 
-cdef usm_ndarray _to_usm_ary_from_host_blob(object host_blob, int device_id):
-    root_device = dpctl.SyclDevice(str(<int>device_id))
-    q = Device.create_device(root_device).sycl_queue
+cdef usm_ndarray _to_usm_ary_from_host_blob(object host_blob, dev : Device):
+    q = dev.sycl_queue
     np_ary = np.asarray(host_blob)
     dt = np_ary.dtype
     if dt.char in "dD" and q.sycl_device.has_aspect_fp64 is False:
@@ -952,14 +951,25 @@ cdef usm_ndarray _to_usm_ary_from_host_blob(object host_blob, int device_id):
     return usm_ary
 
 
+# only cdef to make it private
+cdef object _create_device(object device, object dl_device):
+    if isinstance(device, Device):
+        return device
+    elif isinstance(device, dpctl.SyclDevice):
+        return Device.create_device(device)
+    else:
+        root_device = dpctl.SyclDevice(str(<int>dl_device[1]))
+        return Device.create_device(root_device)
+
+
 def from_dlpack(x, /, *, device=None, copy=None):
     """ from_dlpack(x, /, *, device=None, copy=None)
 
     Constructs :class:`dpctl.tensor.usm_ndarray` instance from a Python
     object ``x`` that implements ``__dlpack__`` protocol.
 
     Args:
-        x (Python object):
+        x (object):
             A Python object representing an array that supports
             ``__dlpack__`` protocol.
         device (Optional[str,
@@ -1044,45 +1054,72 @@ def from_dlpack(x, /, *, device=None, copy=None):
                 )
         else:
             if not isinstance(device, dpctl.SyclDevice):
-                d = Device.create_device(device).sycl_device
+                device = Device.create_device(device)
+                d = device.sycl_device
             else:
                 d = device
             dl_device = (device_OneAPI, get_parent_device_ordinal_id(<c_dpctl.SyclDevice>d))
+    if dl_device is not None:
+        if (dl_device[0] not in [device_OneAPI, device_CPU]):
+            raise ValueError(
+                f"Argument `device`={device} is not supported."
+            )
+    got_type_error = False
+    got_buffer_error = False
+    got_other_error = False
+    saved_exception = None
     try:
-        dlpack_capsule = dlpack_attr(max_version=get_build_dlpack_version(), dl_device=dl_device, copy=copy)
-        return from_dlpack_capsule(dlpack_capsule)
+        # setting max_version to minimal version that supports dl_device/copy keywords
+        dlpack_capsule = dlpack_attr(max_version=(1, 0), dl_device=dl_device, copy=copy)
     except TypeError:
-        # max_version/dl_device, copy keywords are not supported by __dlpack__
-        x_dldev = dlpack_dev_attr()
-        if (dl_device is None) or (dl_device == x_dldev):
-            dlpack_capsule = dlpack_attr()
-            return from_dlpack_capsule(dlpack_capsule)
-        # must copy via host
-        if copy is False:
-            raise BufferError(
-                "Importing data via DLPack requires copying, but copy=False was provided"
-            )
-        if x_dldev == (device_CPU, 0) and dl_device[0] == device_OneAPI:
-            dlpack_capsule = dlpack_attr()
-            host_blob = from_dlpack_capsule(dlpack_capsule)
-        else:
-            raise BufferError(f"Can not import to requested device {dl_device}")
-        return _to_usm_ary_from_host_blob(host_blob, dl_device[1])
-    except (BufferError, NotImplementedError) as e:
-        # we are here, because dlpack_attr could not deal with requested dl_device,
-        # or copying was required
-        if copy is False:
-            raise BufferError(
-                "Importing data via DLPack requires copying, but copy=False was provided"
-            ) from e
-        # must copy via host
-        if dl_device[0] != device_OneAPI:
-            raise BufferError(f"Can not import to requested device {dl_device}")
-        x_dldev = dlpack_dev_attr()
-        if x_dldev == (device_CPU, 0):
-            dlpack_capsule = dlpack_attr()
-            host_blob = from_dlpack_capsule(dlpack_capsule)
-        else:
-            dlpack_capsule = dlpack_attr(max_version=(1, 0), dl_device=(device_CPU, 0), copy=copy)
-            host_blob = from_dlpack_capsule(dlpack_capsule)
-        return _to_usm_ary_from_host_blob(host_blob, dl_device[1])
+        # exporter does not support max_version keyword
+        got_type_error = True
+    except (BufferError, NotImplementedError):
+        # Either dl_device, or copy can be satisfied
+        got_buffer_error = True
+    except Exception as e:
+        got_other_error = True
+        saved_exception = e
+    else:
+        # execution did not raise exceptions
+        return from_dlpack_capsule(dlpack_capsule)
+    finally:
+        if got_type_error:
+            # max_version/dl_device, copy keywords are not supported by __dlpack__
+            x_dldev = dlpack_dev_attr()
+            if (dl_device is None) or (dl_device == x_dldev):
+                dlpack_capsule = dlpack_attr()
+                return from_dlpack_capsule(dlpack_capsule)
+            # must copy via host
+            if copy is False:
+                raise BufferError(
+                    "Importing data via DLPack requires copying, but copy=False was provided"
+                )
+            if x_dldev == (device_CPU, 0) and dl_device[0] == device_OneAPI:
+                dlpack_capsule = dlpack_attr()
+                host_blob = from_dlpack_capsule(dlpack_capsule)
+            else:
+                raise BufferError(f"Can not import to requested device {dl_device}")
+            dev = _create_device(device, dl_device)
+            return _to_usm_ary_from_host_blob(host_blob, dev)
+        elif got_buffer_error:
+            # we are here, because dlpack_attr could not deal with requested dl_device,
+            # or copying was required
+            if copy is False:
+                raise BufferError(
+                    "Importing data via DLPack requires copying, but copy=False was provided"
+                )
+            # must copy via host
+            if dl_device[0] != device_OneAPI:
+                raise BufferError(f"Can not import to requested device {dl_device}")
+            x_dldev = dlpack_dev_attr()
+            if x_dldev == (device_CPU, 0):
+                dlpack_capsule = dlpack_attr()
+                host_blob = from_dlpack_capsule(dlpack_capsule)
+            else:
+                dlpack_capsule = dlpack_attr(max_version=(1, 0), dl_device=(device_CPU, 0), copy=copy)
+                host_blob = from_dlpack_capsule(dlpack_capsule)
+            dev = _create_device(device, dl_device)
+            return _to_usm_ary_from_host_blob(host_blob, dev)
+        elif got_other_error:
+            raise saved_exception