Add exact-name bitcode library lookup

Author: benhg

cuda_pathfinder/cuda/pathfinder/__init__.py

@@ -41,6 +41,9 @@
 from cuda.pathfinder._static_libs.find_bitcode_lib import (
     find_bitcode_lib as find_bitcode_lib,
 )
+from cuda.pathfinder._static_libs.find_bitcode_lib import (
+    find_bitcode_lib_by_name as find_bitcode_lib_by_name,
+)
 from cuda.pathfinder._static_libs.find_bitcode_lib import (
     locate_bitcode_lib as locate_bitcode_lib,
 )
@@ -77,7 +80,8 @@
 SUPPORTED_BINARY_UTILITIES = _SUPPORTED_BINARIES
 
 #: Tuple of supported bitcode library names that can be resolved
-#: via ``locate_bitcode_lib()`` and ``find_bitcode_lib()``.
+#: via ``locate_bitcode_lib()``, ``find_bitcode_lib()``, and
+#: ``find_bitcode_lib_by_name()``.
 #: Example value: ``"device"``.
 SUPPORTED_BITCODE_LIBS = _SUPPORTED_BITCODE_LIBS
 

cuda_pathfinder/cuda/pathfinder/_static_libs/find_bitcode_lib.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import functools
+import ntpath
 import os
 from dataclasses import dataclass
 from typing import NoReturn, TypedDict
@@ -74,13 +75,21 @@ def _no_such_file_in_dir(dir_path: str, filename: str, error_messages: list[str]
         attachments.append(f'  Directory does not exist: "{dir_path}"')
 
 
+def _validate_filename(filename: str) -> str:
+    if not isinstance(filename, str):
+        raise TypeError(f"filename must be a string, got {type(filename).__name__}")
+    if filename in ("", ".", "..") or "\0" in filename or ntpath.basename(filename) != filename:
+        raise ValueError(f"filename must be a file name without a directory: {filename!r}")
+    return filename
+
+
 class _FindBitcodeLib:
-    def __init__(self, name: str) -> None:
+    def __init__(self, name: str, *, filename: str | None = None) -> None:
         if name not in _SUPPORTED_BITCODE_LIBS_INFO:  # Updated reference
             raise ValueError(f"Unknown bitcode library: '{name}'. Supported: {', '.join(SUPPORTED_BITCODE_LIBS)}")
         self.name: str = name
         self.config: _BitcodeLibInfo = _SUPPORTED_BITCODE_LIBS_INFO[name]  # Updated reference
-        self.filename: str = self.config["filename"]
+        self.filename: str = self.config["filename"] if filename is None else _validate_filename(filename)
         self.rel_path: str = self.config["rel_path"]
         self.site_packages_dirs: tuple[str, ...] = self.config["site_packages_dirs"]
         self.error_messages: list[str] = []
@@ -130,14 +139,8 @@ def raise_not_found_error(self) -> NoReturn:
         raise BitcodeLibNotFoundError(f'Failure finding "{self.filename}": {err}\n{att}')
 
 
-def locate_bitcode_lib(name: str) -> LocatedBitcodeLib:
-    """Locate a bitcode library by name.
-
-    Raises:
-        ValueError: If ``name`` is not a supported bitcode library.
-        BitcodeLibNotFoundError: If the bitcode library cannot be found.
-    """
-    finder = _FindBitcodeLib(name)
+def _locate_bitcode_lib(name: str, *, filename: str | None = None) -> LocatedBitcodeLib:
+    finder = _FindBitcodeLib(name, filename=filename)
 
     abs_path = finder.try_site_packages()
     if abs_path is not None:
@@ -169,6 +172,16 @@ def locate_bitcode_lib(name: str) -> LocatedBitcodeLib:
     finder.raise_not_found_error()
 
 
+def locate_bitcode_lib(name: str) -> LocatedBitcodeLib:
+    """Locate a bitcode library by name.
+
+    Raises:
+        ValueError: If ``name`` is not a supported bitcode library.
+        BitcodeLibNotFoundError: If the bitcode library cannot be found.
+    """
+    return _locate_bitcode_lib(name)
+
+
 @functools.cache
 def find_bitcode_lib(name: str) -> str:
     """Find the absolute path to a bitcode library.
@@ -178,3 +191,23 @@ def find_bitcode_lib(name: str) -> str:
         BitcodeLibNotFoundError: If the bitcode library cannot be found.
     """
     return locate_bitcode_lib(name).abs_path
+
+
+@functools.cache
+def find_bitcode_lib_by_name(name: str, filename: str) -> str:
+    """Find an exact bitcode filename using a supported library's search paths.
+
+    This lets a library define its own filename convention, including any
+    architecture or other attributes encoded in the filename.
+
+    Args:
+        name: Supported bitcode library whose configured directories to search.
+        filename: Exact file name to find. Directory components are not allowed.
+
+    Raises:
+        TypeError: If ``filename`` is not a string.
+        ValueError: If ``name`` is unsupported or ``filename`` is not a file name.
+        BitcodeLibNotFoundError: If ``filename`` cannot be found.
+    """
+    _validate_filename(filename)
+    return _locate_bitcode_lib(name, filename=filename).abs_path

cuda_pathfinder/docs/source/api.rst

@@ -35,6 +35,7 @@ CUDA bitcode and static libraries.
 
    SUPPORTED_BITCODE_LIBS
    find_bitcode_lib
+   find_bitcode_lib_by_name
    locate_bitcode_lib
    LocatedBitcodeLib
    BitcodeLibNotFoundError

cuda_pathfinder/tests/test_find_bitcode_lib.py

@@ -11,6 +11,7 @@
     SUPPORTED_BITCODE_LIBS,
     BitcodeLibNotFoundError,
     find_bitcode_lib,
+    find_bitcode_lib_by_name,
     locate_bitcode_lib,
 )
 from cuda.pathfinder._utils.env_vars import get_cuda_path_or_home
@@ -30,15 +31,17 @@ def _bitcode_lib_filename(libname: str) -> str:
 @pytest.fixture
 def clear_find_bitcode_lib_cache():
     find_bitcode_lib_module.find_bitcode_lib.cache_clear()
+    find_bitcode_lib_module.find_bitcode_lib_by_name.cache_clear()
     get_cuda_path_or_home.cache_clear()
     yield
     find_bitcode_lib_module.find_bitcode_lib.cache_clear()
+    find_bitcode_lib_module.find_bitcode_lib_by_name.cache_clear()
     get_cuda_path_or_home.cache_clear()
 
 
-def _make_bitcode_lib_file(dir_path: Path, libname: str) -> str:
+def _make_bitcode_lib_file(dir_path: Path, filename: str) -> str:
     dir_path.mkdir(parents=True, exist_ok=True)
-    file_path = dir_path / _bitcode_lib_filename(libname)
+    file_path = dir_path / filename
     file_path.touch()
     return str(file_path)
 
@@ -92,14 +95,15 @@ def test_locate_bitcode_lib(info_summary_append, libname):
 @pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
 @pytest.mark.parametrize("libname", SUPPORTED_BITCODE_LIBS)
 def test_locate_bitcode_lib_search_order(monkeypatch, tmp_path, libname):
+    filename = _bitcode_lib_filename(libname)
     site_packages_lib_dir = _site_packages_bitcode_lib_dir_under(tmp_path / "site-packages", libname)
-    site_packages_path = _make_bitcode_lib_file(site_packages_lib_dir, libname)
+    site_packages_path = _make_bitcode_lib_file(site_packages_lib_dir, filename)
 
     conda_prefix = tmp_path / "conda-prefix"
-    conda_path = _make_bitcode_lib_file(_bitcode_lib_dir_under(_conda_anchor(conda_prefix), libname), libname)
+    conda_path = _make_bitcode_lib_file(_bitcode_lib_dir_under(_conda_anchor(conda_prefix), libname), filename)
 
     cuda_home = tmp_path / "cuda-home"
-    cuda_home_path = _make_bitcode_lib_file(_bitcode_lib_dir_under(cuda_home, libname), libname)
+    cuda_home_path = _make_bitcode_lib_file(_bitcode_lib_dir_under(cuda_home, libname), filename)
 
     site_packages_sub_dirs = tuple(
         tuple(rel_dir.split("/")) for rel_dir in _bitcode_lib_info(libname)["site_packages_dirs"]
@@ -135,6 +139,70 @@ def find_expected_sub_dir(sub_dir):
     assert located_lib.found_via == "CUDA_PATH"
 
 
+@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
+@pytest.mark.agent_authored(model="gpt-5")
+def test_find_bitcode_lib_by_name_search_order(monkeypatch, tmp_path):
+    libname = "device"
+    filename = "libdevice_sm_90.bc"
+    site_packages_lib_dir = _site_packages_bitcode_lib_dir_under(tmp_path / "site-packages", libname)
+    site_packages_path = _make_bitcode_lib_file(site_packages_lib_dir, filename)
+
+    conda_prefix = tmp_path / "conda-prefix"
+    conda_path = _make_bitcode_lib_file(_bitcode_lib_dir_under(_conda_anchor(conda_prefix), libname), filename)
+
+    cuda_home = tmp_path / "cuda-home"
+    cuda_home_path = _make_bitcode_lib_file(_bitcode_lib_dir_under(cuda_home, libname), filename)
+
+    site_packages_sub_dirs = tuple(
+        tuple(rel_dir.split("/")) for rel_dir in _bitcode_lib_info(libname)["site_packages_dirs"]
+    )
+
+    def find_expected_sub_dir(sub_dir):
+        assert sub_dir in site_packages_sub_dirs
+        if sub_dir == site_packages_sub_dirs[0]:
+            return [str(site_packages_lib_dir)]
+        return []
+
+    monkeypatch.setattr(
+        find_bitcode_lib_module,
+        "find_sub_dirs_all_sitepackages",
+        find_expected_sub_dir,
+    )
+    monkeypatch.setenv("CONDA_PREFIX", str(conda_prefix))
+    monkeypatch.setenv("CUDA_HOME", str(cuda_home))
+    monkeypatch.delenv("CUDA_PATH", raising=False)
+
+    assert find_bitcode_lib_by_name(libname, filename) == site_packages_path
+    os.remove(site_packages_path)
+    find_bitcode_lib_by_name.cache_clear()
+
+    assert find_bitcode_lib_by_name(libname, filename) == conda_path
+    os.remove(conda_path)
+    find_bitcode_lib_by_name.cache_clear()
+
+    assert find_bitcode_lib_by_name(libname, filename) == cuda_home_path
+
+
+@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
+@pytest.mark.agent_authored(model="gpt-5")
+def test_find_bitcode_lib_by_name_cache_keeps_filenames_separate(monkeypatch, tmp_path):
+    lib_dir = _site_packages_bitcode_lib_dir_under(tmp_path / "site-packages", "device")
+    sm80_path = _make_bitcode_lib_file(lib_dir, "libdevice_sm_80.bc")
+    sm90_path = _make_bitcode_lib_file(lib_dir, "libdevice_sm_90.bc")
+
+    monkeypatch.setattr(
+        find_bitcode_lib_module,
+        "find_sub_dirs_all_sitepackages",
+        lambda _sub_dir: [str(lib_dir)],
+    )
+    monkeypatch.delenv("CONDA_PREFIX", raising=False)
+    monkeypatch.delenv("CUDA_HOME", raising=False)
+    monkeypatch.delenv("CUDA_PATH", raising=False)
+
+    assert find_bitcode_lib_by_name("device", "libdevice_sm_80.bc") == sm80_path
+    assert find_bitcode_lib_by_name("device", "libdevice_sm_90.bc") == sm90_path
+
+
 @pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
 def test_find_bitcode_lib_not_found_error_includes_cuda_home_directory_listing(monkeypatch, tmp_path):
     cuda_home = tmp_path / "cuda-home"
@@ -162,6 +230,32 @@ def test_find_bitcode_lib_not_found_error_includes_cuda_home_directory_listing(m
     assert "README.txt" in message
 
 
+@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
+@pytest.mark.agent_authored(model="gpt-5")
+def test_find_bitcode_lib_by_name_not_found_error_uses_requested_filename(monkeypatch, tmp_path):
+    filename = "libdevice_sm_90.bc"
+    cuda_home = tmp_path / "cuda-home"
+    lib_dir = _bitcode_lib_dir_under(cuda_home, "device")
+    lib_dir.mkdir(parents=True)
+    (lib_dir / "libdevice.10.bc").touch()
+
+    monkeypatch.setattr(
+        find_bitcode_lib_module,
+        "find_sub_dirs_all_sitepackages",
+        lambda _sub_dir: [],
+    )
+    monkeypatch.delenv("CONDA_PREFIX", raising=False)
+    monkeypatch.setenv("CUDA_HOME", str(cuda_home))
+    monkeypatch.delenv("CUDA_PATH", raising=False)
+
+    with pytest.raises(BitcodeLibNotFoundError, match=rf'Failure finding "{filename}"') as exc_info:
+        find_bitcode_lib_by_name("device", filename)
+
+    message = str(exc_info.value)
+    assert f"No such file: {lib_dir / filename}" in message
+    assert "libdevice.10.bc" in message
+
+
 @pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
 def test_find_bitcode_lib_not_found_error_without_cuda_home(monkeypatch):
     monkeypatch.setattr(
@@ -183,3 +277,26 @@ def test_find_bitcode_lib_not_found_error_without_cuda_home(monkeypatch):
 def test_find_bitcode_lib_invalid_name():
     with pytest.raises(ValueError, match="Unknown bitcode library"):
         find_bitcode_lib_module.locate_bitcode_lib("invalid")
+
+
+@pytest.mark.parametrize(
+    "filename",
+    ("", ".", "..", "../file.bc", "subdir/file.bc", r"subdir\file.bc", r"C:\lib\file.bc", "bad\0name.bc"),
+)
+@pytest.mark.agent_authored(model="gpt-5")
+def test_find_bitcode_lib_by_name_rejects_paths(filename):
+    with pytest.raises(ValueError, match="without a directory"):
+        find_bitcode_lib_by_name("device", filename)
+
+
+@pytest.mark.parametrize("filename", (None, 90))
+@pytest.mark.agent_authored(model="gpt-5")
+def test_find_bitcode_lib_by_name_requires_string(filename):
+    with pytest.raises(TypeError, match="filename must be a string"):
+        find_bitcode_lib_by_name("device", filename)
+
+
+@pytest.mark.agent_authored(model="gpt-5")
+def test_find_bitcode_lib_by_name_invalid_project():
+    with pytest.raises(ValueError, match="Unknown bitcode library"):
+        find_bitcode_lib_by_name("not_a_real_lib", "libdevice_sm_90.bc")