Skip to content

Commit 69c8e68

Browse files
aryanputtamdboom
andauthored
test(core): add cuda.core.__all__ vs public docs consistency check (NVIDIA#2347)
* test(core): add cuda.core.__all__ vs public docs consistency check Closes NVIDIA#2326. Parses docs/source/api.rst (autosummary entries and data directives while cuda.core is the active module) and compares the flat public names against cuda.core.__all__ in both directions. Dotted entries such as graph.Graph or checkpoint.Process are submodule namespaces and are excluded. Symbols documented in api_private.rst are accepted as documented so returned-helper docs do not fail the check. The tests skip when cuda.core.__all__ is not defined, so this lands independently of NVIDIA#2300 and activates once NVIDIA#2300 merges. Also adds the __all__-names-resolve guard suggested in the NVIDIA#2300 review. Signed-off-by: Aryan <[email protected]> * test(core): land cuda.core.__all__ and extend docs check to public subpackages Addresses review feedback that the consistency check was too narrow: - Define cuda.core.__all__ (flat public namespace) so the check runs instead of skipping, and add an aggregated __all__ to cuda.core.graph derived from its star-imported submodules. - Auto-discover public subpackages from cuda.core.__path__ (graph, system, texture, utils, and any added later; the internal cuNN wheel shims are excluded) and assert each defines a fully resolvable __all__. - Cross-check each documented subpackage's __all__ against api.rst, handling both the dotted (graph.Graph) and flat (currentmodule) doc conventions. system is documented in api_nvml.rst, so its doc cross-check is skipped. * test(core): parse API docs with docutils * Update content to pass current tests * Add docutils dependency to pyproject.toml * Simplify checks. No longer make sure that everything documented is public. * test(core): document intentional scope limits of api docs consistency check * Reorganize __all__ * Fix doc reference * Address findings in PR * Fix tests and make __all__ construction consistent * test(core): drop IPC types from _memory package contents expectation _ipc.__all__ is now empty, so `from cuda.core._memory import *` no longer binds IPCAllocationHandle or IPCBufferDescriptor. Update the expected list in test_package_contents to match. Signed-off-by: Aryan <[email protected]> --------- Signed-off-by: Aryan <[email protected]> Co-authored-by: Michael Droettboom <[email protected]> Co-authored-by: Michael Droettboom <[email protected]>
1 parent 55a2c88 commit 69c8e68

27 files changed

Lines changed: 395 additions & 50 deletions

‎cuda_core/cuda/core/__init__.py‎

Lines changed: 45 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -69,45 +69,51 @@ class _PatchedProperty(metaclass=_PatchedPropMeta):
6969

7070

7171
from cuda.core import checkpoint, system, utils
72-
from cuda.core._context import Context, ContextOptions
73-
from cuda.core._device import Device
74-
from cuda.core._device_resources import (
75-
DeviceResources,
76-
SMResource,
77-
SMResourceOptions,
78-
WorkqueueResource,
79-
WorkqueueResourceOptions,
80-
)
81-
from cuda.core._event import Event, EventOptions
82-
from cuda.core._graphics import GraphicsResource
83-
from cuda.core._host import Host
84-
from cuda.core._launch_config import LaunchConfig
85-
from cuda.core._launcher import launch
86-
from cuda.core._linker import Linker, LinkerOptions
87-
from cuda.core._memory import (
88-
Buffer,
89-
DeviceMemoryResource,
90-
DeviceMemoryResourceOptions,
91-
GraphMemoryResource,
92-
LegacyPinnedMemoryResource,
93-
ManagedBuffer,
94-
ManagedMemoryResource,
95-
ManagedMemoryResourceOptions,
96-
MemoryResource,
97-
PinnedMemoryResource,
98-
PinnedMemoryResourceOptions,
99-
VirtualMemoryResource,
100-
VirtualMemoryResourceOptions,
101-
)
102-
from cuda.core._module import Kernel, ObjectCode
103-
from cuda.core._program import Program, ProgramOptions
104-
from cuda.core._stream import (
105-
LEGACY_DEFAULT_STREAM,
106-
PER_THREAD_DEFAULT_STREAM,
107-
Stream,
108-
StreamOptions,
109-
)
110-
from cuda.core._tensor_map import TensorMapDescriptor, TensorMapDescriptorOptions
72+
from cuda.core._context import *
73+
from cuda.core._context import __all__ as _context_all
74+
from cuda.core._device import *
75+
from cuda.core._device import __all__ as _device_all
76+
from cuda.core._device_resources import *
77+
from cuda.core._device_resources import __all__ as _device_resources_all
78+
from cuda.core._event import *
79+
from cuda.core._event import __all__ as _event_all
80+
from cuda.core._graphics import *
81+
from cuda.core._graphics import __all__ as _graphics_all
82+
from cuda.core._host import *
83+
from cuda.core._host import __all__ as _host_all
84+
from cuda.core._launch_config import *
85+
from cuda.core._launch_config import __all__ as _launch_config_all
86+
from cuda.core._launcher import *
87+
from cuda.core._launcher import __all__ as _launcher_all
88+
from cuda.core._linker import *
89+
from cuda.core._linker import __all__ as _linker_all
90+
from cuda.core._memory import *
91+
from cuda.core._memory import __all__ as _memory_all
92+
from cuda.core._module import *
93+
from cuda.core._module import __all__ as _module_all
94+
from cuda.core._program import *
95+
from cuda.core._program import __all__ as _program_all
96+
from cuda.core._stream import *
97+
from cuda.core._stream import __all__ as _stream_all
98+
from cuda.core._tensor_map import *
99+
from cuda.core._tensor_map import __all__ as _tensor_map_all
100+
101+
__all__ = [
102+
*_context_all,
103+
*_device_all,
104+
*_device_resources_all,
105+
*_event_all,
106+
*_graphics_all,
107+
*_host_all,
108+
*_launch_config_all,
109+
*_launcher_all,
110+
*_linker_all,
111+
*_memory_all,
112+
*_module_all,
113+
*_program_all,
114+
*_stream_all,
115+
*_tensor_map_all,
116+
]
111117

112118
# isort: split
113119
# Texture/surface types live under the cuda.core.texture namespace (not the

‎cuda_core/cuda/core/_device.pyi‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1023,4 +1023,5 @@ class Device:
10231023
.. versionadded:: 1.1.0
10241024
"""
10251025
_tls = threading.local()
1026-
_lock = threading.Lock()
1026+
_lock = threading.Lock()
1027+
__all__ = ['Device']

‎cuda_core/cuda/core/_device.pyx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ _tls = threading.local()
6161
_lock = threading.Lock()
6262
cdef bint _is_cuInit = False
6363

64+
__all__ = ['Device']
65+
6466

6567
cdef class DeviceProperties:
6668
"""

‎cuda_core/cuda/core/_event.pyi‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,7 @@ class IPCEventDescriptor:
180180

181181
def __reduce__(self) -> tuple[object, ...]:
182182
...
183+
__all__ = ['Event', 'EventOptions']
183184

184185
def _reduce_event(event: Event) -> tuple[object, ...]:
185186
...

‎cuda_core/cuda/core/_event.pyx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ if TYPE_CHECKING:
4343
import cuda.bindings.driver # no-cython-lint
4444
from cuda.core._device import Device
4545

46+
__all__ = ['Event', 'EventOptions']
47+
4648

4749
@dataclass
4850
cdef class EventOptions:

‎cuda_core/cuda/core/_host.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
import threading
77
from typing import ClassVar
88

9+
__all__ = ["Host"]
10+
911

1012
class Host:
1113
"""Host (CPU) location for managed-memory operations.

‎cuda_core/cuda/core/_launch_config.pyi‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ class LaunchConfig:
6666
def __hash__(self) -> int:
6767
...
6868
_LAUNCH_CONFIG_ATTRS = ('grid', 'cluster', 'block', 'shmem_size', 'is_cooperative')
69+
__all__ = ['LaunchConfig']
6970

7071
def _to_native_launch_config(config: LaunchConfig) -> object:
7172
"""Convert LaunchConfig to native driver CUlaunchConfig.

‎cuda_core/cuda/core/_launch_config.pyx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ from cuda.core._utils.cuda_utils import (
1515

1616
_LAUNCH_CONFIG_ATTRS = ('grid', 'cluster', 'block', 'shmem_size', 'is_cooperative')
1717

18+
__all__ = ['LaunchConfig']
19+
1820

1921
cdef class LaunchConfig:
2022
"""Customizable launch options.

‎cuda_core/cuda/core/_launcher.pyi‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ from cuda.core._stream import Stream
88
from cuda.core.graph import GraphBuilder
99
from cuda.core.typing import IsStreamType
1010

11+
__all__ = ['launch']
1112

1213
def launch(stream: Stream | GraphBuilder | IsStreamType, config: LaunchConfig, kernel: Kernel, *kernel_args) -> None:
1314
"""Launches a :obj:`~_module.Kernel`

‎cuda_core/cuda/core/_launcher.pyx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ if TYPE_CHECKING:
2424
from cuda.core.graph import GraphBuilder
2525
from cuda.core.typing import IsStreamType
2626

27+
__all__ = ['launch']
28+
2729

2830
def launch(
2931
stream: Stream | GraphBuilder | IsStreamType,

0 commit comments

Comments
 (0)