From ba39a010651d8e3e50dda35ed5f61076e3901a00 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Fri, 5 Jun 2026 10:40:11 -0700 Subject: [PATCH 1/7] Update get_devices and get_composite_devices to return tuple --- dpctl/_sycl_device_factory.pxd | 6 +++--- dpctl/_sycl_device_factory.pyx | 28 +++++++++++++++------------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/dpctl/_sycl_device_factory.pxd b/dpctl/_sycl_device_factory.pxd index 6ed5de90e3..9c4ef08498 100644 --- a/dpctl/_sycl_device_factory.pxd +++ b/dpctl/_sycl_device_factory.pxd @@ -18,7 +18,7 @@ # cython: language_level=3 """ The file declares several helper functions to create SyclDevice objects -from SYCL standard device_selectors, to get a list of SyclDevices for a +from SYCL standard device_selectors, to get a tuple of SyclDevices for a specific backend or device_type. """ @@ -31,8 +31,8 @@ cpdef SyclDevice select_accelerator_device() cpdef SyclDevice select_cpu_device() cpdef SyclDevice select_default_device() cpdef SyclDevice select_gpu_device() -cpdef list get_devices(backend=*, device_type=*) -cpdef list get_composite_devices() +cpdef tuple get_devices(backend=*, device_type=*) +cpdef tuple get_composite_devices() cpdef int get_num_devices(backend=*, device_type=*) cpdef cpp_bool has_gpu_devices() cpdef cpp_bool has_cpu_devices() diff --git a/dpctl/_sycl_device_factory.pyx b/dpctl/_sycl_device_factory.pyx index 7a9794ede0..7288bd5c86 100644 --- a/dpctl/_sycl_device_factory.pyx +++ b/dpctl/_sycl_device_factory.pyx @@ -22,7 +22,7 @@ - wrapper functions to create a SyclDevice from the standard SYCL device selector classes. - - functions to return a list of devices based on a specified device_type or + - functions to return a tuple of devices based on a specified device_type or backend_type combination. """ @@ -133,7 +133,7 @@ cdef _device_type _enum_to_dpctl_sycl_device_ty(DTy): return _device_type._UNKNOWN_DEVICE -cdef list _get_devices(DPCTLDeviceVectorRef DVRef): +cdef tuple _get_devices(DPCTLDeviceVectorRef DVRef): cdef list devices = [] cdef size_t nelems = 0 if DVRef: @@ -143,12 +143,14 @@ cdef list _get_devices(DPCTLDeviceVectorRef DVRef): D = SyclDevice._create(DRef) devices.append(D) - return devices + return tuple(devices) -cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all): +cpdef tuple get_devices( + backend=backend_type.all, device_type=device_type_t.all +): """ - Returns a list of :class:`dpctl.SyclDevice` instances selected based on + Returns a tuple of :class:`dpctl.SyclDevice` instances selected based on the given :class:`dpctl.device_type` and :class:`dpctl.backend_type` values. The function is analogous to ``sycl::devices::get_devices()``, but with an @@ -167,15 +169,15 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all): "gpu", "cpu", "accelerator", or "all". Default: ``dpctl.device_type.all``. Returns: - list: - A list of available :class:`dpctl.SyclDevice` instances that + tuple: + A tuple of available :class:`dpctl.SyclDevice` instances that satisfy the provided :class:`dpctl.backend_type` and :class:`dpctl.device_type` values. """ cdef _backend_type BTy = _backend_type._ALL_BACKENDS cdef _device_type DTy = _device_type._ALL_DEVICES cdef DPCTLDeviceVectorRef DVRef = NULL - cdef list devices + cdef tuple devices if isinstance(backend, str): BTy = _string_to_dpctl_sycl_backend_ty(backend) @@ -204,9 +206,9 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all): return devices -cpdef list get_composite_devices(): +cpdef tuple get_composite_devices(): """ - Returns a list of the available composite :class:`dpctl.SyclDevice` + Returns a tuple of the available composite :class:`dpctl.SyclDevice` instances. Only available when `ZE_FLAT_DEVICE_HIERARCHY=COMBINED` is set in @@ -219,11 +221,11 @@ cpdef list get_composite_devices(): https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/experimental/sycl_ext_oneapi_composite_device.asciidoc Returns: - list: - A list of available composite :class:`dpctl.SyclDevice` instances. + tuple: + A tuple of available composite :class:`dpctl.SyclDevice` instances. """ cdef DPCTLDeviceVectorRef DVRef = NULL - cdef list composite_devices + cdef tuple composite_devices DVRef = DPCTLDeviceMgr_GetCompositeDevices() composite_devices = _get_devices(DVRef) From a4bedfeb243449352f3df40b02d2e02a7ff65c74 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Fri, 5 Jun 2026 10:42:02 -0700 Subject: [PATCH 2/7] Update get_platforms and SyclPlatform device getters to return tuple --- dpctl/_sycl_platform.pxd | 2 +- dpctl/_sycl_platform.pyx | 26 +++++++++++++------------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/dpctl/_sycl_platform.pxd b/dpctl/_sycl_platform.pxd index 6512363077..2e49944395 100644 --- a/dpctl/_sycl_platform.pxd +++ b/dpctl/_sycl_platform.pxd @@ -45,4 +45,4 @@ cdef class SyclPlatform(_SyclPlatform): cdef bool equals(self, SyclPlatform) -cpdef list get_platforms() +cpdef tuple get_platforms() diff --git a/dpctl/_sycl_platform.pyx b/dpctl/_sycl_platform.pyx index 41eff7b5d3..645b06237c 100644 --- a/dpctl/_sycl_platform.pyx +++ b/dpctl/_sycl_platform.pyx @@ -378,7 +378,7 @@ cdef class SyclPlatform(_SyclPlatform): def get_devices(self, device_type=device_type_t.all): """ - Returns the list of :class:`dpctl.SyclDevice` objects associated with + Returns a tuple of :class:`dpctl.SyclDevice` objects associated with :class:`dpctl.SyclPlatform` instance selected based on the given :class:`dpctl.device_type`. @@ -391,8 +391,8 @@ cdef class SyclPlatform(_SyclPlatform): Default: ``dpctl.device_type.all``. Returns: - list: - A :obj:`list` of :class:`dpctl.SyclDevice` objects + tuple: + A :obj:`tuple` of :class:`dpctl.SyclDevice` objects that belong to this platform. Raises: @@ -455,16 +455,16 @@ cdef class SyclPlatform(_SyclPlatform): devices.append(SyclDevice._create(DRef)) DPCTLDeviceVector_Delete(DVRef) - return devices + return tuple(devices) def get_composite_devices(self): """ - Returns the list of composite :class:`dpctl.SyclDevice` objects + Returns a tuple of composite :class:`dpctl.SyclDevice` objects associated with :class:`dpctl.SyclPlatform` instance. Returns: - list: - A :obj:`list` of composite :class:`dpctl.SyclDevice` objects + tuple: + A :obj:`tuple` of composite :class:`dpctl.SyclDevice` objects that belong to this platform. Raises: @@ -487,7 +487,7 @@ cdef class SyclPlatform(_SyclPlatform): composite_devices.append(SyclDevice._create(DRef)) DPCTLDeviceVector_Delete(DVRef) - return composite_devices + return tuple(composite_devices) def lsplatform(verbosity=0): @@ -596,13 +596,13 @@ def lsplatform(verbosity=0): DPCTLPlatformVector_Delete(PVRef) -cpdef list get_platforms(): +cpdef tuple get_platforms(): """ - Returns a list of all available SYCL platforms on the system. + Returns a tuple of all available SYCL platforms on the system. Returns: - List[:class:`.SyclPlatform`]: - A list of SYCL platforms on the system. + Tuple[:class:`.SyclPlatform`]: + A tuple of SYCL platforms on the system. """ cdef list platforms = [] cdef DPCTLPlatformVectorRef PVRef = NULL @@ -617,4 +617,4 @@ cpdef list get_platforms(): platforms.append(P) DPCTLPlatformVector_Delete(PVRef) - return platforms + return tuple(platforms) From e292a54a7b620446c933f40fe4671ad6a91c17f8 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Mon, 8 Jun 2026 03:09:24 -0700 Subject: [PATCH 3/7] Update SyclDevice methods to return tuple --- dpctl/_sycl_device.pxd | 6 ++--- dpctl/_sycl_device.pyx | 52 +++++++++++++++++++++--------------------- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/dpctl/_sycl_device.pxd b/dpctl/_sycl_device.pxd index 190d981cd0..2415e490a4 100644 --- a/dpctl/_sycl_device.pxd +++ b/dpctl/_sycl_device.pxd @@ -51,9 +51,9 @@ cdef public api class SyclDevice(_SyclDevice) [ cdef int _init_from__SyclDevice(self, _SyclDevice other) cdef int _init_from_selector(self, DPCTLSyclDeviceSelectorRef DSRef) cdef DPCTLSyclDeviceRef get_device_ref(self) - cdef list create_sub_devices_equally(self, size_t count) - cdef list create_sub_devices_by_counts(self, object counts) - cdef list create_sub_devices_by_affinity( + cdef tuple create_sub_devices_equally(self, size_t count) + cdef tuple create_sub_devices_by_counts(self, object counts) + cdef tuple create_sub_devices_by_affinity( self, _partition_affinity_domain_type domain ) cdef cpp_bool equals(self, SyclDevice q) diff --git a/dpctl/_sycl_device.pyx b/dpctl/_sycl_device.pyx index 6c6638e2e3..dba9980932 100644 --- a/dpctl/_sycl_device.pyx +++ b/dpctl/_sycl_device.pyx @@ -157,7 +157,7 @@ cdef class _SyclDevice: DPCTLSize_t_Array_Delete(self._max_work_item_sizes) -cdef list _get_devices(DPCTLDeviceVectorRef DVRef): +cdef tuple _get_devices(DPCTLDeviceVectorRef DVRef): """ Deletes DVRef. Pass a copy in case an original reference is needed. """ @@ -171,7 +171,7 @@ cdef list _get_devices(DPCTLDeviceVectorRef DVRef): devices.append(D) DPCTLDeviceVector_Delete(DVRef) - return devices + return tuple(devices) cdef str _backend_type_to_filter_string_part(_backend_type BTy): @@ -1188,7 +1188,7 @@ cdef class SyclDevice(_SyclDevice): @property def sub_group_sizes(self): - """ Returns list of supported sub-group sizes for this device. + """ Returns tuple of supported sub-group sizes for this device. :Example: @@ -1197,11 +1197,11 @@ cdef class SyclDevice(_SyclDevice): >>> import dpctl >>> dev = dpctl.select_cpu_device() >>> dev.sub_group_sizes - [4, 8, 16, 32, 64] + (4, 8, 16, 32, 64) Returns: - List[int]: - List of supported sub-group sizes. + Tuple[int]: + Tuple of supported sub-group sizes. """ cdef size_t *sg_sizes = NULL cdef size_t sg_sizes_len = 0 @@ -1214,9 +1214,9 @@ cdef class SyclDevice(_SyclDevice): for i in range(sg_sizes_len): res.append(sg_sizes[i]) DPCTLSize_t_Array_Delete(sg_sizes) - return res + return tuple(res) else: - return [] + return () @property def sycl_platform(self): @@ -1590,11 +1590,11 @@ cdef class SyclDevice(_SyclDevice): """ return DPCTLDevice_Hash(self._device_ref) - cdef list create_sub_devices_equally(self, size_t count): - """ Returns a list of sub-devices partitioned from this SYCL device + cdef tuple create_sub_devices_equally(self, size_t count): + """ Returns a tuple of sub-devices partitioned from this SYCL device based on the ``count`` parameter. - The returned list contains as many sub-devices as can be created + The returned tuple contains as many sub-devices as can be created such that each sub-device contains count compute units. If the device’s total number of compute units is not evenly divided by count, then the remaining compute units are not included in any of @@ -1605,7 +1605,7 @@ cdef class SyclDevice(_SyclDevice): Number of sub-devices to partition into. Returns: - List[:class:`dpctl.SyclDevice`]: + Tuple[:class:`dpctl.SyclDevice`]: Created sub-devices. Raises: @@ -1623,15 +1623,15 @@ cdef class SyclDevice(_SyclDevice): ) return _get_devices(DVRef) - cdef list create_sub_devices_by_counts(self, object counts): - """ Returns a list of sub-devices partitioned from this SYCL device + cdef tuple create_sub_devices_by_counts(self, object counts): + """ Returns a tuple of sub-devices partitioned from this SYCL device based on the ``counts`` parameter. For each non-zero value ``M`` in the counts vector, a sub-device with ``M`` compute units is created. Returns: - List[:class:`dpctl.SyclDevice`]: + Tuple[:class:`dpctl.SyclDevice`]: Created sub-devices. Raises: @@ -1670,14 +1670,14 @@ cdef class SyclDevice(_SyclDevice): ) return _get_devices(DVRef) - cdef list create_sub_devices_by_affinity( + cdef tuple create_sub_devices_by_affinity( self, _partition_affinity_domain_type domain ): - """ Returns a list of sub-devices partitioned from this SYCL device by + """ Returns a tuple of sub-devices partitioned from this SYCL device by affinity domain based on the ``domain`` parameter. Returns: - List[:class:`dpctl.SyclDevice`]: + Tuple[:class:`dpctl.SyclDevice`]: Created sub-devices. Raises: @@ -1692,8 +1692,8 @@ cdef class SyclDevice(_SyclDevice): def create_sub_devices(self, **kwargs): """create_sub_devices(partition=partition_spec) - Creates a list of sub-devices by partitioning a root device based on the - provided partition specifier. + Creates a tuple of sub-devices by partitioning a root device based on + the provided partition specifier. A partition specifier must be provided using a ``partition`` keyword argument. Possible values for the specifier are: an integer, a @@ -1725,7 +1725,7 @@ cdef class SyclDevice(_SyclDevice): Specification to partition the device as follows: - Specifying an int (``count``) - The returned list contains as + The returned tuple contains as many sub-devices as can be created such that each sub-device contains ``count`` compute units. If the device’s total number of compute units is not evenly @@ -1742,7 +1742,7 @@ cdef class SyclDevice(_SyclDevice): sub-device with ``M`` compute units is created. Returns: - List[:class:`dpctl.SyclDevice`]: + Tuple[:class:`dpctl.SyclDevice`]: Created sub-devices. Raises: @@ -1831,14 +1831,14 @@ cdef class SyclDevice(_SyclDevice): return SyclDevice._create(CDRef) def component_devices(self): - """ Returns a list of component devices contained in this SYCL device. + """ Returns a tuple of component devices contained in this SYCL device. - The returned list will be empty if this SYCL device is not a composite + The returned tuple will be empty if this SYCL device is not a composite device, i.e., if `is_composite` is ``False``. Returns: - List[:class:`dpctl.SyclDevice`]: - List of component devices. + Tuple[:class:`dpctl.SyclDevice`]: + Tuple of component devices. Raises: ValueError: From 99568834a14d7c006d8a2ace045477711917783f Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Mon, 8 Jun 2026 03:09:55 -0700 Subject: [PATCH 4/7] Update test_get_unpartitioned_parent_device_from_sub_device to check tuple --- dpctl/tests/test_sycl_device.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/tests/test_sycl_device.py b/dpctl/tests/test_sycl_device.py index e9eee7e223..3a9899f2a6 100644 --- a/dpctl/tests/test_sycl_device.py +++ b/dpctl/tests/test_sycl_device.py @@ -307,7 +307,7 @@ def test_get_unpartitioned_parent_device_from_sub_device(): sdevs = dev.create_sub_devices(partition=[1, 1]) except dpctl.SyclSubDeviceCreationError: pytest.skip("Default device can not be partitioned") - assert isinstance(sdevs, list) and len(sdevs) > 0 + assert isinstance(sdevs, tuple) and len(sdevs) > 0 assert dev == sdevs[0].get_unpartitioned_parent_device() From 4fde78c133e3f265335adc0c5841141c56711ee1 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Mon, 8 Jun 2026 03:43:05 -0700 Subject: [PATCH 5/7] Update get_devices in SyclContex to return tuple --- dpctl/_sycl_context.pyx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dpctl/_sycl_context.pyx b/dpctl/_sycl_context.pyx index 102cae52f8..ac915db811 100644 --- a/dpctl/_sycl_context.pyx +++ b/dpctl/_sycl_context.pyx @@ -388,12 +388,12 @@ cdef class SyclContext(_SyclContext): def get_devices(self): """ - Returns the list of :class:`dpctl.SyclDevice` objects associated with + Returns a tuple of :class:`dpctl.SyclDevice` objects associated with :class:`dpctl.SyclContext` instance. Returns: - list: - A :obj:`list` of :class:`dpctl.SyclDevice` objects + tuple: + A :obj:`tuple` of :class:`dpctl.SyclDevice` objects that belong to this context. Raises: @@ -415,7 +415,7 @@ cdef class SyclContext(_SyclContext): DRef = DPCTLDeviceVector_GetAt(DVRef, i) devices.append(SyclDevice._create(DRef)) DPCTLDeviceVector_Delete(DVRef) - return devices + return tuple(devices) @property def device_count(self): From 83d4e327159c9e48f55518b737649d056c025cd8 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Mon, 8 Jun 2026 03:47:54 -0700 Subject: [PATCH 6/7] Fix typo in SyclContext docstring example --- dpctl/_sycl_context.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/_sycl_context.pyx b/dpctl/_sycl_context.pyx index ac915db811..bb4b7a1658 100644 --- a/dpctl/_sycl_context.pyx +++ b/dpctl/_sycl_context.pyx @@ -153,7 +153,7 @@ cdef class SyclContext(_SyclContext): sub_devices = cpu_d.create_sub_devices(partition=2) # Create a context common to all the sub-devices. ctx = dpctl.SyclContext(sub_devices) - assert(len(ctx.get_devices) == len(sub_devices)) + assert(len(ctx.get_devices()) == len(sub_devices)) - Invoking the constructor with a named ``PyCapsule`` with name **"SyclContextRef"** that carries a pointer to a ``sycl::context`` From 67ce17f0cb253e6aeb9d4178dc9def75537f420a Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Tue, 9 Jun 2026 05:18:03 -0700 Subject: [PATCH 7/7] Update docstring Returns format to use Tuple[:class:] style --- dpctl/_sycl_context.pyx | 4 ++-- dpctl/_sycl_device_factory.pyx | 4 ++-- dpctl/_sycl_platform.pyx | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/dpctl/_sycl_context.pyx b/dpctl/_sycl_context.pyx index bb4b7a1658..a09d5ddb3c 100644 --- a/dpctl/_sycl_context.pyx +++ b/dpctl/_sycl_context.pyx @@ -392,8 +392,8 @@ cdef class SyclContext(_SyclContext): :class:`dpctl.SyclContext` instance. Returns: - tuple: - A :obj:`tuple` of :class:`dpctl.SyclDevice` objects + Tuple[:class:`dpctl.SyclDevice`]: + A tuple of :class:`dpctl.SyclDevice` objects that belong to this context. Raises: diff --git a/dpctl/_sycl_device_factory.pyx b/dpctl/_sycl_device_factory.pyx index 7288bd5c86..f52b5d99bd 100644 --- a/dpctl/_sycl_device_factory.pyx +++ b/dpctl/_sycl_device_factory.pyx @@ -169,7 +169,7 @@ cpdef tuple get_devices( "gpu", "cpu", "accelerator", or "all". Default: ``dpctl.device_type.all``. Returns: - tuple: + Tuple[:class:`dpctl.SyclDevice`]: A tuple of available :class:`dpctl.SyclDevice` instances that satisfy the provided :class:`dpctl.backend_type` and :class:`dpctl.device_type` values. @@ -221,7 +221,7 @@ cpdef tuple get_composite_devices(): https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/experimental/sycl_ext_oneapi_composite_device.asciidoc Returns: - tuple: + Tuple[:class:`dpctl.SyclDevice`]: A tuple of available composite :class:`dpctl.SyclDevice` instances. """ cdef DPCTLDeviceVectorRef DVRef = NULL diff --git a/dpctl/_sycl_platform.pyx b/dpctl/_sycl_platform.pyx index 645b06237c..6bc3cd050b 100644 --- a/dpctl/_sycl_platform.pyx +++ b/dpctl/_sycl_platform.pyx @@ -391,8 +391,8 @@ cdef class SyclPlatform(_SyclPlatform): Default: ``dpctl.device_type.all``. Returns: - tuple: - A :obj:`tuple` of :class:`dpctl.SyclDevice` objects + Tuple[:class:`dpctl.SyclDevice`]: + A tuple of :class:`dpctl.SyclDevice` objects that belong to this platform. Raises: @@ -463,8 +463,8 @@ cdef class SyclPlatform(_SyclPlatform): associated with :class:`dpctl.SyclPlatform` instance. Returns: - tuple: - A :obj:`tuple` of composite :class:`dpctl.SyclDevice` objects + Tuple[:class:`dpctl.SyclDevice`]: + A tuple of composite :class:`dpctl.SyclDevice` objects that belong to this platform. Raises: