Add cuda.h toolkit version parser.

Introduce a small toolkit-info utility that reads the CUDA_VERSION macro from cuda.h so follow-up guard-rails changes can infer CTK major.minor from toolkit headers without depending on version.json.

Made-with: Cursor

Author: rwgk

cuda_pathfinder/cuda/pathfinder/_utils/toolkit_info.py

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import functools
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_CUDA_VERSION_RE = re.compile(r"^\s*#\s*define\s+CUDA_VERSION\s+(?P<encoded>\d+)\b", re.MULTILINE)
+
+
+class ReadCudaHeaderVersionError(RuntimeError):
+    """Raised when ``read_cuda_header_version()`` cannot determine the CTK version from ``cuda.h``."""
+
+
+@dataclass(frozen=True, slots=True)
+class CudaToolkitVersion:
+    """CUDA Toolkit version encoded by the ``CUDA_VERSION`` macro in ``cuda.h``."""
+
+    encoded: int
+    major: int
+    minor: int
+
+
+def parse_cuda_header_version(header_text: str) -> CudaToolkitVersion | None:
+    """Parse the CUDA Toolkit major/minor version from ``cuda.h`` text."""
+    match = _CUDA_VERSION_RE.search(header_text)
+    if match is None:
+        return None
+    encoded = int(match.group("encoded"))
+    return CudaToolkitVersion(
+        encoded=encoded,
+        major=encoded // 1000,
+        minor=(encoded % 1000) // 10,
+    )
+
+
+@functools.cache
+def read_cuda_header_version(cuda_header_path: str) -> CudaToolkitVersion:
+    """Read and parse the CUDA Toolkit major/minor version from ``cuda.h``."""
+    try:
+        header_text = Path(cuda_header_path).read_text(encoding="utf-8", errors="replace")
+        version = parse_cuda_header_version(header_text)
+        if version is None:
+            raise RuntimeError(f"{cuda_header_path!r} does not define CUDA_VERSION.")
+        return version
+    except Exception as exc:
+        raise ReadCudaHeaderVersionError(
+            f"Failed to read the CUDA Toolkit version from cuda.h at {cuda_header_path!r}."
+        ) from exc

cuda_pathfinder/tests/test_utils_toolkit_info.py

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import pytest
+
+from cuda.pathfinder._utils import toolkit_info
+
+
+@pytest.fixture(autouse=True)
+def _clear_cuda_header_version_cache():
+    toolkit_info.read_cuda_header_version.cache_clear()
+    yield
+    toolkit_info.read_cuda_header_version.cache_clear()
+
+
+def test_parse_cuda_header_version_returns_parsed_dataclass():
+    header_text = """
+    #ifndef CUDA_H
+    #define CUDA_H
+    #define CUDA_VERSION 13020
+    #endif
+    """
+
+    assert toolkit_info.parse_cuda_header_version(header_text) == toolkit_info.CudaToolkitVersion(
+        encoded=13020,
+        major=13,
+        minor=2,
+    )
+
+
+def test_parse_cuda_header_version_returns_none_when_macro_is_missing():
+    header_text = """
+    #ifndef CUDA_H
+    #define CUDA_H
+    #define CUDA_API_PER_THREAD_DEFAULT_STREAM 1
+    #endif
+    """
+
+    assert toolkit_info.parse_cuda_header_version(header_text) is None
+
+
+def test_read_cuda_header_version_reads_file_and_returns_parsed_dataclass(tmp_path):
+    cuda_h_path = tmp_path / "cuda.h"
+    cuda_h_path.write_text(
+        """
+        #ifndef CUDA_H
+        #define CUDA_H
+        #define CUDA_VERSION 12090 /* CUDA 12.9 */
+        #endif
+        """,
+        encoding="utf-8",
+    )
+
+    assert toolkit_info.read_cuda_header_version(str(cuda_h_path)) == toolkit_info.CudaToolkitVersion(
+        encoded=12090,
+        major=12,
+        minor=9,
+    )
+
+
+def test_read_cuda_header_version_tolerates_non_utf8_bytes(tmp_path):
+    cuda_h_path = tmp_path / "cuda.h"
+    cuda_h_path.write_bytes(
+        b"#ifndef CUDA_H\n"
+        b"#define CUDA_H\n"
+        b"\xff\xfe invalid bytes in comment or banner\n"
+        b"#define CUDA_VERSION 12080\n"
+        b"#endif\n"
+    )
+
+    assert toolkit_info.read_cuda_header_version(str(cuda_h_path)) == toolkit_info.CudaToolkitVersion(
+        encoded=12080,
+        major=12,
+        minor=8,
+    )
+
+
+def test_read_cuda_header_version_wraps_parse_failures(tmp_path):
+    cuda_h_path = tmp_path / "cuda.h"
+    cuda_h_path.write_text(
+        """
+        #ifndef CUDA_H
+        #define CUDA_H
+        #endif
+        """,
+        encoding="utf-8",
+    )
+
+    with pytest.raises(
+        toolkit_info.ReadCudaHeaderVersionError,
+        match="Failed to read the CUDA Toolkit version from cuda.h",
+    ) as exc_info:
+        toolkit_info.read_cuda_header_version(str(cuda_h_path))
+
+    assert isinstance(exc_info.value.__cause__, RuntimeError)
+    assert "does not define CUDA_VERSION" in str(exc_info.value.__cause__)