Add exact-name bitcode locate API

Author: rwgk

cuda_pathfinder/cuda/pathfinder/__init__.py

@@ -47,6 +47,9 @@
 from cuda.pathfinder._static_libs.find_bitcode_lib import (
     locate_bitcode_lib as locate_bitcode_lib,
 )
+from cuda.pathfinder._static_libs.find_bitcode_lib import (
+    locate_bitcode_lib_by_name as locate_bitcode_lib_by_name,
+)
 from cuda.pathfinder._static_libs.find_static_lib import (
     SUPPORTED_STATIC_LIBS as _SUPPORTED_STATIC_LIBS,
 )
@@ -80,8 +83,8 @@
 SUPPORTED_BINARY_UTILITIES = _SUPPORTED_BINARIES
 
 #: Tuple of supported bitcode library names that can be resolved
-#: via ``locate_bitcode_lib()``, ``find_bitcode_lib()``, and
-#: ``find_bitcode_lib_by_name()``.
+#: via ``locate_bitcode_lib()``, ``locate_bitcode_lib_by_name()``,
+#: ``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

@@ -182,6 +182,25 @@ def locate_bitcode_lib(name: str) -> LocatedBitcodeLib:
     return _locate_bitcode_lib(name)
 
 
+def locate_bitcode_lib_by_name(name: str, filename: str) -> LocatedBitcodeLib:
+    """Locate 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 locate. 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)
+
+
 @functools.cache
 def find_bitcode_lib(name: str) -> str:
     """Find the absolute path to a bitcode library.
@@ -209,5 +228,4 @@ def find_bitcode_lib_by_name(name: str, filename: str) -> str:
         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
+    return locate_bitcode_lib_by_name(name, filename).abs_path

cuda_pathfinder/docs/source/api.rst

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

cuda_pathfinder/tests/test_find_bitcode_lib.py

@@ -13,6 +13,7 @@
     find_bitcode_lib,
     find_bitcode_lib_by_name,
     locate_bitcode_lib,
+    locate_bitcode_lib_by_name,
 )
 from cuda.pathfinder._utils.env_vars import get_cuda_path_or_home
 
@@ -141,7 +142,7 @@ def find_expected_sub_dir(sub_dir):
 
 @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):
+def test_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)
@@ -172,14 +173,26 @@ def find_expected_sub_dir(sub_dir):
     monkeypatch.setenv("CUDA_HOME", str(cuda_home))
     monkeypatch.delenv("CUDA_PATH", raising=False)
 
+    located_lib = locate_bitcode_lib_by_name(libname, filename)
+    assert located_lib.abs_path == site_packages_path
+    assert located_lib.filename == filename
+    assert located_lib.found_via == "site-packages"
     assert find_bitcode_lib_by_name(libname, filename) == site_packages_path
     os.remove(site_packages_path)
     find_bitcode_lib_by_name.cache_clear()
 
+    located_lib = locate_bitcode_lib_by_name(libname, filename)
+    assert located_lib.abs_path == conda_path
+    assert located_lib.filename == filename
+    assert located_lib.found_via == "conda"
     assert find_bitcode_lib_by_name(libname, filename) == conda_path
     os.remove(conda_path)
     find_bitcode_lib_by_name.cache_clear()
 
+    located_lib = locate_bitcode_lib_by_name(libname, filename)
+    assert located_lib.abs_path == cuda_home_path
+    assert located_lib.filename == filename
+    assert located_lib.found_via == "CUDA_PATH"
     assert find_bitcode_lib_by_name(libname, filename) == cuda_home_path
 
 
@@ -283,20 +296,23 @@ def test_find_bitcode_lib_invalid_name():
     "filename",
     ("", ".", "..", "../file.bc", "subdir/file.bc", r"subdir\file.bc", r"C:\lib\file.bc", "bad\0name.bc"),
 )
+@pytest.mark.parametrize("lookup", (find_bitcode_lib_by_name, locate_bitcode_lib_by_name))
 @pytest.mark.agent_authored(model="gpt-5")
-def test_find_bitcode_lib_by_name_rejects_paths(filename):
+def test_bitcode_lib_by_name_rejects_paths(lookup, filename):
     with pytest.raises(ValueError, match="without a directory"):
-        find_bitcode_lib_by_name("device", filename)
+        lookup("device", filename)
 
 
 @pytest.mark.parametrize("filename", (None, 90))
+@pytest.mark.parametrize("lookup", (find_bitcode_lib_by_name, locate_bitcode_lib_by_name))
 @pytest.mark.agent_authored(model="gpt-5")
-def test_find_bitcode_lib_by_name_requires_string(filename):
+def test_bitcode_lib_by_name_requires_string(lookup, filename):
     with pytest.raises(TypeError, match="filename must be a string"):
-        find_bitcode_lib_by_name("device", filename)
+        lookup("device", filename)
 
 
+@pytest.mark.parametrize("lookup", (find_bitcode_lib_by_name, locate_bitcode_lib_by_name))
 @pytest.mark.agent_authored(model="gpt-5")
-def test_find_bitcode_lib_by_name_invalid_project():
+def test_bitcode_lib_by_name_invalid_project(lookup):
     with pytest.raises(ValueError, match="Unknown bitcode library"):
-        find_bitcode_lib_by_name("not_a_real_lib", "libdevice_sm_90.bc")
+        lookup("not_a_real_lib", "libdevice_sm_90.bc")