Skip to content

Commit b6cbcc0

Browse files
Andy-Jostclaude
andcommitted
Copyedit the docs, comments, docstrings and messages this PR adds (NVIDIA#2783)
A plain-language pass over the prose the PR introduces: one idea per sentence, active voice, no semicolons or parenthetical asides, one term per concept (cuda-bindings for the package, cuda.bindings for the module). Error messages keep what they state and change only how they say it; the tests that match them follow. The regenerated stubs follow their docstrings. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent 6ba9004 commit b6cbcc0

64 files changed

Lines changed: 707 additions & 633 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎ci/tools/cuda_core_bindings_floor.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,14 @@
1010
1111
CI installs `cuda-bindings==<floor>` next to a freshly built cuda-core wheel to
1212
test the oldest cuda-bindings that wheel supports (BINDINGS_SOURCE=floor in
13-
ci/tools/env-vars). The floor is read from the wheel under test rather than
13+
ci/tools/env-vars). This script reads the floor from the wheel under test, not
1414
from the checkout, so a nightly job that tests a wheel built from another
1515
commit reads that wheel's floor.
1616
17-
Each build records its floor in the generated cuda/core/_build_info.py (at top
18-
level in a single-major build, under cuda/core/cu<major>/ in the merged wheel);
19-
this script reads the CUDA_BINDINGS_FLOOR literal out of it without running it.
17+
Each build records its floor in the generated cuda/core/_build_info.py. A
18+
single-major build places the file at top level. The merged wheel places it
19+
under cuda/core/cu<major>/. This script parses the CUDA_BINDINGS_FLOOR literal
20+
out of it and never runs it.
2021
"""
2122

2223
from __future__ import annotations
@@ -31,7 +32,7 @@
3132

3233

3334
def _literal(source: str, name: str):
34-
"""The literal assigned to `name` at module level of `source`, parsed without executing it."""
35+
"""The literal that `source` assigns to `name` at module level. Parses the source and never runs it."""
3536
for node in ast.parse(source, MODULE).body:
3637
if isinstance(node, ast.AnnAssign):
3738
targets = [node.target]
@@ -56,7 +57,7 @@ def floor_from_wheel(wheel: Path, major: int) -> str:
5657
for candidate in (f"cuda/core/cu{major}/{MODULE}", f"cuda/core/{MODULE}"):
5758
if candidate in names:
5859
return floor_from_source(zf.read(candidate).decode("utf-8"), major)
59-
raise SystemExit(f"{wheel.name} contains no build for CUDA {major} (no {MODULE}); is it a cuda-core wheel?")
60+
raise SystemExit(f"{wheel.name} contains no build for CUDA {major}: it has no {MODULE}. Is it a cuda-core wheel?")
6061

6162

6263
def main(argv: list[str] | None = None) -> int:

‎ci/tools/env-vars‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -64,22 +64,23 @@ elif [[ "${1}" == "test" ]]; then
6464
# BINDINGS_SOURCE controls which cuda-bindings to install at test time:
6565
# main — use the just-built bindings wheel from this CI run
6666
# backport — fetch bindings from the prior (N-1) branch
67-
# floor — install the oldest cuda-bindings the cuda-core wheel under test
68-
# supports, from PyPI (its per-major floor; see
67+
# floor — install from PyPI the oldest cuda-bindings that the cuda-core
68+
# wheel under test supports, its per-major floor (see
6969
# cuda_core/cuda/core/_bindings_floor.py and ci/tools/run-tests).
70-
# Selected when the test CTK minor differs from the one the wheel
71-
# was built against, so those rows exercise new cuda-core + floor
72-
# bindings + older CTK libraries, the skew cuda-core supports.
73-
# (cuda-bindings older than the floor is unsupported and fails at
74-
# import: https://github.com/NVIDIA/cuda-python/issues/2783.)
70+
# Selected when the test CTK minor differs from the minor the
71+
# wheel was built against. Those rows exercise a new cuda-core
72+
# with the floor cuda-bindings and older CTK libraries, the skew
73+
# that cuda-core supports. cuda-bindings older than the floor is
74+
# unsupported and fails at import
75+
# (https://github.com/NVIDIA/cuda-python/issues/2783).
7576
#
7677
# SKIP_CUDA_BINDINGS_TEST / SKIP_CYTHON_TEST control which *tests* to run
7778
# (they do NOT affect installation — that's BINDINGS_SOURCE's job).
7879

7980
BUILD_CUDA_MINOR="$(cut -d '.' -f 2 <<< ${BUILD_CUDA_VER})"
8081
TEST_CUDA_MINOR="$(cut -d '.' -f 2 <<< ${CUDA_VER})"
81-
# The prior-major half of the cuda-core wheel is built against ci/versions.yml's
82-
# prev_build toolkit (and the backport branch's bindings).
82+
# CI builds the prior-major half of the cuda-core wheel against the prev_build
83+
# toolkit in ci/versions.yml and the backport branch's bindings.
8384
BUILD_PREV_CUDA_VER="$(sed -n '/prev_build:/,/version:/s/.*version: *"\([^"]*\)".*/\1/p' ci/versions.yml)"
8485
BUILD_PREV_CUDA_MINOR="$(cut -d '.' -f 2 <<< ${BUILD_PREV_CUDA_VER})"
8586

‎ci/tools/run-tests‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,8 @@ elif [[ "${test_module}" == "core" || "${test_module}" == nightly-* ]]; then
7474

7575
# Resolve bindings based on BINDINGS_SOURCE (set by env-vars):
7676
# main/backport → local wheel from artifacts dir
77-
# floor → the oldest cuda-bindings the core wheel under test supports,
78-
# read from that wheel, installed from PyPI
77+
# floor → the oldest cuda-bindings that the cuda-core wheel under test
78+
# supports, read from that wheel and installed from PyPI
7979
BINDINGS_ARGS=()
8080
if [[ "${BINDINGS_SOURCE}" == "floor" ]]; then
8181
CORE_WHL_FOR_FLOOR=("${CUDA_CORE_ARTIFACTS_DIR}"/*.whl)

‎cuda_bindings/AGENTS.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,10 @@ the `legacy_tests` subdirectory.
5151

5252
- `CUDA_HOME` or `CUDA_PATH` must point to a valid CUDA Toolkit for source
5353
builds.
54-
- The toolkit's `cuda.h` must have the major.minor the generated sources came
55-
from (`CUDA_VERSION` in `cuda/bindings/cydriver.pxd`). `build_hooks.py`
56-
checks this before cythonize and fails with a message that names both.
54+
- The toolkit's `cuda.h` must have the same major.minor as the generated
55+
sources, `CUDA_VERSION` in `cuda/bindings/cydriver.pxd`. `build_hooks.py`
56+
checks this before cythonize and fails with a message that names both
57+
versions.
5758
- `CUDA_PYTHON_PARALLEL_LEVEL` controls build parallelism.
5859
- Runtime behavior is affected by
5960
`CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM` and

‎cuda_bindings/build_hooks.py‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@
3434
# Populated by _build_cuda_bindings(); consumed by setup.py.
3535
_extensions = None
3636

37-
# The generated sources declare the types and functions of one CUDA header set;
38-
# cydriver.pxd records which. The install docs state the resulting build rule.
37+
# The generated sources declare the types and functions of one CUDA header set,
38+
# and cydriver.pxd records which. The install docs state the build rule that results.
3939
_CYDRIVER_PXD = Path(__file__).resolve().parent / "cuda" / "bindings" / "cydriver.pxd"
4040
_GENERATED_VERSION_RE = re.compile(r"^cdef enum:\s*CUDA_VERSION\s*=\s*(\d+)\s*$")
4141
_CUDA_H_VERSION_RE = re.compile(r"^#\s*define\s+CUDA_VERSION\s+(\d+)\s*$")
@@ -108,7 +108,7 @@ def _read_version_macro(path: str, pattern: re.Pattern) -> int | None:
108108

109109

110110
def _read_cuda_h_version(cuda_path: str) -> int:
111-
"""The CUDA_VERSION macro (e.g. 13040 for 13.4) of the cuda.h under cuda_path."""
111+
"""The CUDA_VERSION macro of the cuda.h under cuda_path, for example 13040 for 13.4."""
112112
cuda_h = _cuda_h_path(cuda_path)
113113
try:
114114
version = _read_version_macro(cuda_h, _CUDA_H_VERSION_RE)
@@ -123,7 +123,10 @@ def _read_cuda_h_version(cuda_path: str) -> int:
123123

124124

125125
def _generated_cuda_version() -> int:
126-
"""The CUDA_VERSION of the headers this source tree was generated from (cuda/bindings/cydriver.pxd)."""
126+
"""The CUDA_VERSION of the headers that this source tree was generated from.
127+
128+
Read from cuda/bindings/cydriver.pxd.
129+
"""
127130
version = _read_version_macro(str(_CYDRIVER_PXD), _GENERATED_VERSION_RE)
128131
if version is None:
129132
raise RuntimeError(f"Cannot read CUDA_VERSION from {_CYDRIVER_PXD}")
@@ -136,12 +139,12 @@ def _major_minor(cuda_version: int) -> str:
136139

137140

138141
def _check_cuda_headers(cuda_path: str) -> None:
139-
"""Reject a toolkit whose cuda.h is not the major.minor this source tree was generated from.
142+
"""Reject a toolkit whose cuda.h is not the major.minor that this source tree was generated from.
140143
141144
Against another minor, the C++ compile fails with a long list of
142-
redefinition and undeclared-type errors that do not name the cause
143-
(https://github.com/NVIDIA/cuda-python/issues/2783). Runs before
144-
cythonize, which is the first step that touches the source tree.
145+
redefinition and undeclared-type errors that do not name the cause. See
146+
https://github.com/NVIDIA/cuda-python/issues/2783. Runs before cythonize,
147+
which is the first step that touches the source tree.
145148
"""
146149
generated = _generated_cuda_version()
147150
needed, found = _major_minor(generated), _major_minor(_read_cuda_h_version(cuda_path))

‎cuda_bindings/docs/source/install.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ Requirements
128128

129129
[^3]: The version is derived from git tags via ``setuptools-scm``, so the clone must include tags reaching back to at least the latest ``v*`` tag. Clone with ``git clone https://github.com/NVIDIA/cuda-python.git``; do not use ``--depth`` or ``--no-tags``, since a shallow clone builds without error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See `Cloning the repository <https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_ for details and recovery steps.
130130

131-
Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. The build checks the header before it compiles anything; a mismatch stops it with a message that names the ``cuda.h`` it found and the version this source tree needs. Use the ``CUDA_PATH`` (or ``CUDA_HOME``) environment variable to specify the location of your headers. If both are set, ``CUDA_PATH`` takes precedence. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_PATH`` with:
131+
Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. The build checks the header before it compiles anything. A mismatch stops the build with a message that names the ``cuda.h`` it found and the version this source tree needs. Use the ``CUDA_PATH`` (or ``CUDA_HOME``) environment variable to specify the location of your headers. If both are set, ``CUDA_PATH`` takes precedence. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_PATH`` with:
132132

133133
.. code-block:: console
134134

‎cuda_bindings/docs/source/release/13.5.0-notes.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -301,7 +301,7 @@ Enhancements
301301
- ``nvvm.add_module_to_program``, ``nvvm.lazy_add_module_to_program``, ``nvvm.get_compiled_result``, ``nvvm.get_program_log`` (``buffer``)
302302
- For all ``cuda-bindings`` APIs, functions that accept a struct wrapper will accept the struct wrapper directly, rather than requiring getting the ``.ptr`` property.
303303
- Creating class instances in ``cuda-bindings`` should now be faster in most cases, because it requires 1 heap allocation rather than 2.
304-
- A source build now checks, before it compiles anything, that the CUDA Toolkit's ``cuda.h`` has the major.minor this source tree was generated from. A mismatch stops the build with a message that names the header found and the version needed. It used to surface as a long list of C++ redefinition errors.
304+
- Before a source build compiles anything, it now checks that the CUDA Toolkit's ``cuda.h`` has the major.minor this source tree was generated from. A mismatch stops the build with a message that names the header found and the version needed. Previously a mismatch surfaced as a long list of C++ redefinition errors.
305305

306306
Behavior changes
307307
----------------

‎cuda_bindings/tests/test_build_hooks.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
22
# SPDX-License-Identifier: Apache-2.0
33

4-
"""build_hooks.py: the CUDA header check that runs before cythonize.
4+
"""Tests for the CUDA header check that build_hooks.py runs before cythonize.
55
6-
A cuda-bindings source tree is generated from one CUDA header set and compiles
7-
only against a toolkit of that major.minor; against another minor the C++
6+
A cuda-bindings source tree is generated from one CUDA header set. It compiles
7+
only against a toolkit of that major.minor. Against another minor, the C++
88
compile fails with redefinition errors that do not name the cause. The check
99
reads both versions and fails early with a message that does. No GPU needed.
1010
11-
build_hooks.py is a PEP 517 backend, not an installed module, so it is loaded
12-
from source. It imports setuptools at the top; the ``test`` extra provides it.
11+
build_hooks.py is a PEP 517 backend, not an installed module, so the tests load
12+
it from source. It imports setuptools at the top, which the ``test`` extra provides.
1313
"""
1414

1515
import importlib.util
@@ -26,7 +26,7 @@
2626
@pytest.fixture(scope="module")
2727
def build_hooks():
2828
if not BUILD_HOOKS.is_file():
29-
pytest.skip(f"{BUILD_HOOKS} is not in this tree; these tests need the source checkout")
29+
pytest.skip(f"{BUILD_HOOKS} is not in this tree. These tests need the source checkout")
3030
spec = importlib.util.spec_from_file_location("cuda_bindings_build_hooks", BUILD_HOOKS)
3131
module = importlib.util.module_from_spec(spec)
3232
spec.loader.exec_module(module)
@@ -52,7 +52,7 @@ def test_generated_header_version_is_read_from_cydriver_pxd(build_hooks):
5252
def test_a_header_of_the_generated_major_minor_passes(build_hooks, tmp_path):
5353
generated = build_hooks._generated_cuda_version()
5454
build_hooks._check_cuda_headers(_write_cuda_h(tmp_path, generated))
55-
# Only major.minor matters; the last digit (13041) is a toolkit patch.
55+
# Only major.minor matters. The last digit, as in 13041, is a toolkit patch.
5656
build_hooks._check_cuda_headers(_write_cuda_h(tmp_path, generated + 1))
5757

5858

@@ -91,7 +91,7 @@ def test_the_build_checks_the_header_before_it_touches_the_tree(build_hooks, tmp
9191
monkeypatch.setattr(build_hooks, "_get_cuda_path", lambda: cuda_path)
9292

9393
def not_reached():
94-
raise AssertionError("the header check must run before the source tree is modified")
94+
raise AssertionError("the header check must run before the build modifies the source tree")
9595

9696
monkeypatch.setattr(build_hooks, "_rename_architecture_specific_files", not_reached)
9797
with pytest.raises(RuntimeError, match="source tree needs CUDA .* headers"):

0 commit comments

Comments
 (0)