Changes to select_device_with_aspects

1. Added docstring
2. Rename arguments from "aspect_list", "deny_list" to
   "required_aspects", "excluded_aspects"
3. Permit aspects to be gives as Python sequences
4. If unsupported aspect is specified, AttributeError is raised
   as opposed to ValueError
5. ValueError is raised of the requested device is not available.

6. Tests were modified to account for possibility that function
   invocation may raise ValueError
7. Test was added to test that ValueError error is raised when
   impossible configuration is requested, like when
   required_aspects and excluded_aspects sets intersect.

Author: oleksandr-pavlyk

dpctl/_device_selection.py

@@ -1,37 +1,73 @@
+import collections.abc
+from itertools import chain
+
 from . import SyclDevice, get_devices
 
 
-def select_device_with_aspects(aspect_list, deny_list=[]):
-    check_list = aspect_list + deny_list
-    for asp in check_list:
+def select_device_with_aspects(required_aspects, excluded_aspects=[]):
+    """Selects the root :class:`dpctl.SyclDevice` that has the highest
+    default selector score among devices that have all aspects in the
+    `required_aspects` list, and do not have any aspects in `excluded_aspects`
+    list.
+
+    Supported
+
+        :Example:
+            .. code-block:: python
+
+                import dpctl
+                # select a GPU that supports double precision
+                dpctl.select_device_with_aspects(['fp64', 'gpu'])
+                # select non-custom device with USM shared allocations
+                dpctl.select_device_with_aspects(
+                    ['usm_shared_allocations'], excluded_aspects=['custom'])
+    """
+    if isinstance(required_aspects, str):
+        required_aspects = [required_aspects]
+    if isinstance(excluded_aspects, str):
+        excluded_aspects = [excluded_aspects]
+    seq = collections.abc.Sequence
+    input_types_ok = isinstance(required_aspects, seq) and isinstance(
+        excluded_aspects, seq
+    )
+    if not input_types_ok:
+        raise TypeError(
+            "Aspects are expected to be Python sequences, "
+            "e.g. lists, of strings"
+        )
+    for asp in chain(required_aspects, excluded_aspects):
         if type(asp) != str:
             raise TypeError("The list objects must be of a string type")
         if not hasattr(SyclDevice, "has_aspect_" + asp):
-            raise ValueError(f"The {asp} aspect is not supported in dpctl")
+            raise AttributeError(f"The {asp} aspect is not supported in dpctl")
     devs = get_devices()
     max_score = 0
     selected_dev = None
 
     for dev in devs:
-        # aspect_status = True
-        #     for asp in aspect_list:
-        #         has_aspect = "dev.has_aspect_" + asp
-        #         if not eval(has_aspect):
-        #             aspect_status = False
-        #     for deny in deny_list:
-        #         has_aspect = "dev.has_aspect_" + deny
-        #         if eval(has_aspect):
-        #             aspect_status = False
         aspect_status = all(
-            (getattr(dev, "has_aspect_" + asp) is True for asp in aspect_list)
+            (
+                getattr(dev, "has_aspect_" + asp) is True
+                for asp in required_aspects
+            )
         )
         aspect_status = aspect_status and not (
             any(
-                (getattr(dev, "has_aspect_" + asp) is True for asp in deny_list)
+                (
+                    getattr(dev, "has_aspect_" + asp) is True
+                    for asp in excluded_aspects
+                )
             )
         )
         if aspect_status and dev.default_selector_score > max_score:
             max_score = dev.default_selector_score
             selected_dev = dev
 
+    if selected_dev is None:
+        raise ValueError(
+            f"Requested device is unavailable: "
+            f"required_aspects={required_aspects}, "
+            f"excluded_aspects={excluded_aspects}"
+        )
+
     return selected_dev

dpctl/tests/test_sycl_device.py

@@ -647,7 +647,7 @@ def test_hashing_of_device():
     assert device_dict
 
 
-list_of_valid_aspects = [
+list_of_supported_aspects = [
     "cpu",
     "gpu",
     "accelerator",
@@ -664,7 +664,9 @@ def test_hashing_of_device():
     "usm_system_allocator",
 ]
 
-list_of_invalid_aspects = [
+# SYCL 2020 spec aspects not presently
+# supported in DPC++, and dpctl
+list_of_unsupported_aspects = [
     "emulated",
     "host_debuggable",
     "atomic64",
@@ -673,25 +675,39 @@ def test_hashing_of_device():
 ]
 
 
-@pytest.fixture(params=list_of_valid_aspects)
-def valid_aspects(request):
+@pytest.fixture(params=list_of_supported_aspects)
+def supported_aspect(request):
     return request.param
 
 
-@pytest.fixture(params=list_of_invalid_aspects)
-def invalid_aspects(request):
+@pytest.fixture(params=list_of_unsupported_aspects)
+def unsupported_aspect(request):
     return request.param
 
 
-def test_valid_aspects(valid_aspects):
-    dpctl.select_device_with_aspects([valid_aspects])
+def test_supported_aspect(supported_aspect):
+    try:
+        dpctl.select_device_with_aspects(supported_aspect)
+    except ValueError:
+        # ValueError may be raised if no device with
+        # requested aspect charateristics is available
+        pass
 
 
-def test_invalid_aspects(invalid_aspects):
+def test_unsupported_aspect(unsupported_aspect):
     try:
-        dpctl.select_device_with_aspects([invalid_aspects])
+        dpctl.select_device_with_aspects(unsupported_aspect)
         raise AttributeError(
-            f"The {invalid_aspects} aspect is supported in dpctl"
+            f"The {unsupported_aspect} aspect is now supported in dpctl"
         )
-    except ValueError:
-        pytest.skip(f"The {invalid_aspects} aspect is not supported in dpctl")
+    except AttributeError:
+        pytest.skip(
+            f"The {unsupported_aspect} aspect is not supported in dpctl"
+        )
+
+
+def test_handle_no_device():
+    with pytest.raises(ValueError):
+        dpctl.select_device_with_aspects(["gpu", "cpu"])
+    with pytest.raises(ValueError):
+        dpctl.select_device_with_aspects("cpu", excluded_aspects="cpu")