From 09d1a7734ab63be96eec1481fedefc5f00190d1a Mon Sep 17 00:00:00 2001 From: LeSingh1 Date: Sun, 9 Aug 2026 14:13:21 -0700 Subject: [PATCH] docs(core): fix three cuda.core.system docs defects 1. Four Sphinx version directives are misspelled and render as errors. cuda_core/cuda/core/system/_device.pyx:895 .. version-changed:: 1.1.0 cuda_core/cuda/core/system/_device.pyx:909 .. version-added:: 1.1.0 cuda_core/cuda/core/system/_device.pyx:919 .. version-added:: 1.1.0 cuda_core/cuda/core/system/_nvlink.pxi:31 .. version-deprecated:: 1.1.0 The directives are `versionchanged`, `versionadded` and `deprecated` -- no hyphen. The repository already spells `.. versionadded::` correctly in 31 other places (texture/, graph/), so these four are typos, not a local convention. Sphinx emits "Unknown directive type" and drops the content, which is how the behaviour change in `Device.get_nvlink` ("Any link number not supported by this specific device will raise a ValueError") and the deprecation of `NvlinkInfo.max_links` have been missing from the rendered docs. The generated `_device.pyi` carries the same four typos and is fixed with them. 2. `Device.get_cpu_affinity`'s docstring describes memory affinity. Summary, fallback sentence and Returns section were copied from `get_memory_affinity` twenty lines above, so they promise "indices of NUMA nodes or CPU sockets" and "ideal memory affinity". The body calls `nvmlDeviceGetCpuAffinityWithinScope`, sizes the bitmask in CPU words (`ceil(cpu_count() / 64)`) and runs it through `_unpack_bitmask`, so the list holds logical CPU indices. The docstring even contradicts itself: the summary says "CPU affinity", the Returns section says "memory affinity". A caller who believes it will index NUMA nodes with CPU numbers. 3. The `register_events` example calls `.event_type` on the wrong object. `RegisteredSystemEvents.wait()` returns `SystemEvents`, which defines only `__init__`, `__len__` and `__getitem__`; `event_type` lives on the singular `SystemEvent`. So the documented snippet raises AttributeError. The example was copied from the device-level one in _device.pyx:728-734, where `DeviceEvents.wait()` really does return a single event. Rewritten to index the batch, and to import `SystemEventType`, which the snippet used without ever importing. --- cuda_core/cuda/core/system/_device.pyi | 19 ++++++++++--------- cuda_core/cuda/core/system/_device.pyx | 17 +++++++++-------- cuda_core/cuda/core/system/_nvlink.pxi | 2 +- cuda_core/cuda/core/system/_system_events.pyi | 6 ++++-- cuda_core/cuda/core/system/_system_events.pyx | 6 ++++-- 5 files changed, 28 insertions(+), 22 deletions(-) diff --git a/cuda_core/cuda/core/system/_device.pyi b/cuda_core/cuda/core/system/_device.pyi index c758576f0ac..a8d254fdf42 100644 --- a/cuda_core/cuda/core/system/_device.pyi +++ b/cuda_core/cuda/core/system/_device.pyi @@ -798,7 +798,7 @@ class _NvlinkInfoMeta(type): To find the actual number of Nvlinks available on a device, use :py:attr:`Device.get_nvlink_count`. - .. version-deprecated:: 1.1.0 + .. deprecated:: 1.1.0 This property is deprecated and will be removed in a future release. Use :py:attr:`Device.get_nvlink_count` instead. """ @@ -1484,15 +1484,15 @@ class Device: def get_cpu_affinity(self, scope: AffinityScope | str=...) -> list[int]: """ - Retrieves a list of indices of NUMA nodes or CPU sockets with the ideal - CPU affinity for the device. + Retrieves a list of logical CPU indices with the ideal CPU affinity for + the device. For Kepler™ or newer fully supported devices. Supported on Linux only. If requested scope is not applicable to the target topology, the API - will fall back to reporting the memory affinity for the immediate non-I/O + will fall back to reporting the CPU affinity for the immediate non-I/O ancestor of the device. Parameters @@ -1504,8 +1504,9 @@ class Device: Returns ------- list[int] - A list of indices of NUMA nodes or CPU sockets with the ideal memory - affinity for the device. + A list of logical CPU indices with the ideal CPU affinity for the + device. Contrast :meth:`get_memory_affinity`, which returns NUMA + node / CPU socket indices. """ def set_cpu_affinity(self) -> None: @@ -1743,7 +1744,7 @@ class Device: For devices with NVLink support. - .. version-changed:: 1.1.0 + .. versionchanged:: 1.1.0 Any link number not supported by this specific device will raise a `ValueError`. """ @@ -1753,7 +1754,7 @@ class Device: For devices with NVLink support. - .. version-added:: 1.1.0 + .. versionadded:: 1.1.0 """ def get_nvlinks(self) -> Iterable[NvlinkInfo]: @@ -1762,7 +1763,7 @@ class Device: For devices with NVLink support. - .. version-added:: 1.1.0 + .. versionadded:: 1.1.0 """ @property diff --git a/cuda_core/cuda/core/system/_device.pyx b/cuda_core/cuda/core/system/_device.pyx index 6c81c3b9732..ae816940737 100644 --- a/cuda_core/cuda/core/system/_device.pyx +++ b/cuda_core/cuda/core/system/_device.pyx @@ -521,15 +521,15 @@ cdef class Device: def get_cpu_affinity(self, scope: AffinityScope | str=AffinityScope.NODE) -> list[int]: """ - Retrieves a list of indices of NUMA nodes or CPU sockets with the ideal - CPU affinity for the device. + Retrieves a list of logical CPU indices with the ideal CPU affinity for + the device. For Kepler™ or newer fully supported devices. Supported on Linux only. If requested scope is not applicable to the target topology, the API - will fall back to reporting the memory affinity for the immediate non-I/O + will fall back to reporting the CPU affinity for the immediate non-I/O ancestor of the device. Parameters @@ -541,8 +541,9 @@ cdef class Device: Returns ------- list[int] - A list of indices of NUMA nodes or CPU sockets with the ideal memory - affinity for the device. + A list of logical CPU indices with the ideal CPU affinity for the + device. Contrast :meth:`get_memory_affinity`, which returns NUMA + node / CPU socket indices. """ try: scope = _AFFINITY_SCOPE_MAPPING[scope] @@ -892,7 +893,7 @@ cdef class Device: For devices with NVLink support. - .. version-changed:: 1.1.0 + .. versionchanged:: 1.1.0 Any link number not supported by this specific device will raise a `ValueError`. """ link_count = self.get_nvlink_count() @@ -906,7 +907,7 @@ cdef class Device: For devices with NVLink support. - .. version-added:: 1.1.0 + .. versionadded:: 1.1.0 """ return self.get_field_values([FieldId.DEV_NVLINK_LINK_COUNT])[0].value @@ -916,7 +917,7 @@ cdef class Device: For devices with NVLink support. - .. version-added:: 1.1.0 + .. versionadded:: 1.1.0 """ for link in range(self.get_nvlink_count()): yield self.get_nvlink(link) diff --git a/cuda_core/cuda/core/system/_nvlink.pxi b/cuda_core/cuda/core/system/_nvlink.pxi index 49ac1b75ba1..20b4fbd694d 100644 --- a/cuda_core/cuda/core/system/_nvlink.pxi +++ b/cuda_core/cuda/core/system/_nvlink.pxi @@ -28,7 +28,7 @@ class _NvlinkInfoMeta(type): To find the actual number of Nvlinks available on a device, use :py:attr:`Device.get_nvlink_count`. - .. version-deprecated:: 1.1.0 + .. deprecated:: 1.1.0 This property is deprecated and will be removed in a future release. Use :py:attr:`Device.get_nvlink_count` instead. """ diff --git a/cuda_core/cuda/core/system/_system_events.pyi b/cuda_core/cuda/core/system/_system_events.pyi index 5ae5b86bc57..ad36619f803 100644 --- a/cuda_core/cuda/core/system/_system_events.pyi +++ b/cuda_core/cuda/core/system/_system_events.pyi @@ -111,9 +111,11 @@ def register_events(events: SystemEventType | str | list[SystemEventType | str]) Examples -------- >>> from cuda.core import system + >>> from cuda.core.system.typing import SystemEventType >>> events = system.register_events([SystemEventType.UNBIND]) - >>> while event := events.wait(timeout_ms=10000): - ... print(f"Event {event.event_type} occurred.") + >>> while batch := events.wait(timeout_ms=10000): + ... for i in range(len(batch)): + ... print(f"Event {batch[i].event_type} occurred.") Parameters ---------- diff --git a/cuda_core/cuda/core/system/_system_events.pyx b/cuda_core/cuda/core/system/_system_events.pyx index 87a3dfcf1ef..408c28b9103 100644 --- a/cuda_core/cuda/core/system/_system_events.pyx +++ b/cuda_core/cuda/core/system/_system_events.pyx @@ -155,9 +155,11 @@ def register_events(events: SystemEventType | str | list[SystemEventType | str]) Examples -------- >>> from cuda.core import system + >>> from cuda.core.system.typing import SystemEventType >>> events = system.register_events([SystemEventType.UNBIND]) - >>> while event := events.wait(timeout_ms=10000): - ... print(f"Event {event.event_type} occurred.") + >>> while batch := events.wait(timeout_ms=10000): + ... for i in range(len(batch)): + ... print(f"Event {batch[i].event_type} occurred.") Parameters ----------