feat(api/list): allow filtering the list of snaps

snap_http/api/snaps.py

@@ -1,4 +1,4 @@
-from typing import Dict, List, Literal, Optional, Union
+from typing import Dict, List, Literal, Optional, Union, Iterable
 
 from .. import http
 from ..types import FileUpload, FormData, SnapdResponse
@@ -244,12 +244,17 @@ def unhold_all(names: List[str]) -> SnapdResponse:
     return http.post("/snaps", {"action": "unhold", "snaps": names})
 
 
-def list() -> SnapdResponse:
+def list(*, snaps: Optional[Iterable[str]] = None) -> SnapdResponse:
     """GETs a list of installed snaps.
 
     This stomps on builtins.list, so please import it namespaced.
+
+    :param snaps: An optional iterable of snap names by which to filter.
     """
-    return http.get("/snaps")
+    query_params = {}
+    if snaps is not None:
+        query_params["snaps"] = ",".join(snaps)
+    return http.get("/snaps", query_params=query_params)
 
 
 def list_all() -> SnapdResponse:

tests/integration/test_snaps.py

@@ -1,3 +1,5 @@
+import pytest
+
 import snap_http
 
 from tests.utils import get_snap_details, is_snap_installed, remove_assertion, wait_for
@@ -9,6 +11,25 @@ def test_list_snaps():
     assert "snapd" in installed_snaps
 
 
+@pytest.mark.parametrize(
+    "snaps",
+    [
+        {"snapd"},
+        {"snapd", "core24"},
+    ]
+)
+def test_list_snaps_with_names(snaps):
+    """Test listing snaps, filtering by name."""
+    listed_snaps = {snap["name"] for snap in snap_http.list(snaps=snaps).result}
+    assert listed_snaps == snaps
+
+
+def test_list_snaps_with_names_no_match():
+    """Test listing snaps, filtering by name."""
+    listed_snaps = {snap["name"] for snap in snap_http.list(snaps=["othsnaushoeatnlxbuehceaoemtapgi0ceuobhtkerobhgcio"]).result}
+    assert listed_snaps == set()
+
+
 def test_list_all_snaps():
     """Test listing snaps."""
     installed_snaps = {snap["name"] for snap in snap_http.list_all().result}

tests/unit/api/test_snaps.py

@@ -877,7 +877,14 @@ def mock_post(path, body):
         _ = api.unhold_all(["placeholder1", "placeholder2"])
 
 
-def test_list(monkeypatch):
+@pytest.mark.parametrize(
+    ("snaps", "expected_params"),
+    [
+        (None, {}),
+        (["snapd", "core24"], {"snaps": "snapd,core24"}),
+    ]
+)
+def test_list(monkeypatch, snaps, expected_params):
     """`api.list` returns a `types.SnapdResponse`."""
     mock_response = types.SnapdResponse(
         type="sync",
@@ -886,14 +893,16 @@ def test_list(monkeypatch):
         result=[{"title": "placeholder1"}, {"title": "placeholder2"}],
     )
 
-    def mock_get(path):
+    def mock_get(path, query_params):
         assert path == "/snaps"
 
+        assert query_params == expected_params
+
         return mock_response
 
     monkeypatch.setattr(http, "get", mock_get)
 
-    result = api.list()
+    result = api.list(snaps=snaps)
 
     assert result == mock_response