Add utilities for installing kwave binaries (#377)

To check if kwave binaries are present, one can now do this:

```
all(p.exists() for p,_ in get_kwave_paths())
```

And then if they are not present then one can

```
download_and_install_kwave_assets()
```

if there is an internet connection, otherwise us
`install_kwave_asset_from_file` on individual needed files.
The names of the needed files are

```
[p.name for p,_ in get_kwave_paths()]
```

Author: ebrahimebrahim

src/openlifu/util/assets.py

@@ -15,7 +15,7 @@
 from openlifu.util.types import PathLike
 
 
-def install_asset(destination:PathLike, path_to_asset:PathLike|None, url_to_asset:str|None) -> None:
+def install_asset(destination:PathLike, path_to_asset:PathLike|None=None, url_to_asset:str|None=None) -> None:
     """Install a file to a location if it isn't already there.
 
     Downloads if a `url_to_asset` is provided, and copies if a local `path_to_asset` is provided.
@@ -136,9 +136,9 @@ def _import_kwave_inertly() -> ModuleType:
     return _import_without_calls("kwave", banned_calls=["install_binaries"])
 
 def get_kwave_paths() -> list[tuple[Path, str]]:
-    """Get a list of paths and urls to kwave binaries.
+    """Get a list of paths and urls to kwave binaries for this platform.
 
-    Each item in the list is a pair consisting of the install of a needed binary, followed by a download url for that binary.
+    Each item in the list is a pair consisting of the install path of a needed binary, followed by a download url for that binary.
     """
     kwave = _import_kwave_inertly()
     paths : list[tuple[str, str]] = []
@@ -147,3 +147,24 @@ def get_kwave_paths() -> list[tuple[Path, str]]:
             _, filename = url.split("/")[-2:]
             paths.append((Path(kwave.BINARY_PATH) / filename, url))
     return paths
+
+def download_and_install_kwave_assets() -> None:
+    """Download and install the binaries needed by kwave for this platform"""
+    for install_path, url in get_kwave_paths():
+        install_asset(destination=install_path, url_to_asset=url)
+
+def install_kwave_asset_from_file(path_to_kwave_binary:PathLike) -> Path:
+    """Copy kwave binary file to the appropriate place for kwave to use it.
+    The filename is used to identify which binary it is.
+    Returns the path to the installed (i.e. copied) binary.
+    """
+    path_to_kwave_binary = Path(path_to_kwave_binary)
+    kwave_paths = get_kwave_paths()
+    for install_path, _ in kwave_paths:
+        if path_to_kwave_binary.name == install_path.name:
+            install_asset(destination=install_path, path_to_asset=path_to_kwave_binary)
+            return install_path
+    raise ValueError(
+        f"The filename {path_to_kwave_binary.name} was not recognized as one of the binaries kwave is looking for: "
+        + ", ".join([str(install_path) for install_path, _ in kwave_paths])
+    )

tests/test_assets.py

@@ -7,7 +7,12 @@
 import pytest
 import requests
 
-from openlifu.util.assets import get_kwave_paths, install_asset
+from openlifu.util.assets import (
+    download_and_install_kwave_assets,
+    get_kwave_paths,
+    install_asset,
+    install_kwave_asset_from_file,
+)
 
 
 def test_destination_already_exists(tmp_path, mocker):
@@ -106,3 +111,51 @@ def test_get_kwave_paths():
         assert isinstance(p, Path)
         assert isinstance(url, str)
         assert len(url) > 0
+
+def test_download_and_install_kwave_assets(tmp_path, mocker):
+    """Verify kwave assets are downloaded by calling install_asset for each binary."""
+    fake_paths = [
+        (tmp_path / "bin1", "http://example.com/bin1"),
+        (tmp_path / "bin2", "http://example.com/bin2"),
+    ]
+    mocker.patch("openlifu.util.assets.get_kwave_paths", return_value=fake_paths)
+    mock_install_asset = mocker.patch("openlifu.util.assets.install_asset")
+
+    download_and_install_kwave_assets()
+
+    assert mock_install_asset.call_count == 2
+    # Check that install_asset was called for each item in our fake list
+    mock_install_asset.assert_any_call(destination=fake_paths[0][0], url_to_asset=fake_paths[0][1])
+    mock_install_asset.assert_any_call(destination=fake_paths[1][0], url_to_asset=fake_paths[1][1])
+
+
+def test_install_kwave_asset_from_file_succeeds(tmp_path, mocker):
+    """Verify a kwave binary is installed from a file with a matching name."""
+    install_path1 = tmp_path / "kwave_binary_1"
+    install_path2 = tmp_path / "another_binary"
+    fake_paths = [(install_path1, "url1"), (install_path2, "url2")]
+    mocker.patch("openlifu.util.assets.get_kwave_paths", return_value=fake_paths)
+    mock_install_asset = mocker.patch("openlifu.util.assets.install_asset")
+
+    # The source file can be in any directory, as long as its name matches.
+    source_file = tmp_path / "some_dir" / "kwave_binary_1"
+
+    result = install_kwave_asset_from_file(source_file)
+
+    mock_install_asset.assert_called_once_with(destination=install_path1, path_to_asset=source_file)
+    assert result == install_path1
+
+
+def test_install_kwave_asset_from_file_fails_on_unrecognized_name(tmp_path, mocker):
+    """Verify a ValueError is raised for a kwave binary with a non-matching name."""
+    fake_paths = [(tmp_path / "kwave_binary_1", "url1")]
+    mocker.patch("openlifu.util.assets.get_kwave_paths", return_value=fake_paths)
+    mock_install_asset = mocker.patch("openlifu.util.assets.install_asset")
+
+    unrecognized_file = tmp_path / "unrecognized_file.exe"
+
+    with pytest.raises(ValueError, match="was not recognized as one of the binaries"):
+        install_kwave_asset_from_file(unrecognized_file)
+
+    # Ensure we didn't accidentally try to install anything
+    mock_install_asset.assert_not_called()