Fix recursive search in Client.get_items

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Fix usage documentation of `ItemSearch`
 - Fix fields argument to CLI  ([#797](https://github.com/stac-utils/pystac-client/pull/797))
+- Fix recursive search in `Client.get_items` ([#799](https://github.com/stac-utils/pystac-client/pull/799)) 
 
 ## [v0.8.6] - 2025-02-11
 

pystac_client/client.py

@@ -443,21 +443,34 @@ def get_collections(self) -> Iterator[Collection]:
                 call_modifier(self.modifier, collection)
                 yield collection
 
-    def get_items(
-        self, *ids: str, recursive: bool | None = None
-    ) -> Iterator["Item_Type"]:
+    def get_items(self, *ids: str, recursive: bool = True) -> Iterator["Item_Type"]:
         """Return all items of this catalog.
 
         Args:
             ids: Zero or more item ids to find.
-            recursive: unused in pystac-client, but needed for falling back to pystac
+            recursive : If True, search this catalog and all children for the
+                item; otherwise, only search the items of this catalog. Defaults
+                to True.
 
         Return:
             Iterator[Item]: Iterator of items whose parent is this
                 catalog.
         """
         if self.conforms_to(ConformanceClasses.ITEM_SEARCH):
-            search = self.search(ids=ids)
+            # Previously, recursive=None was treated the same as recursive=True.
+            # This if statement maintains this behaviour for backwards compatibility.
+            if recursive is not False:
+                search = self.search(ids=ids)
+                try:
+                    yield from search.items()
+                    return
+                except APIError:
+                    child_catalogs = [catalog.id for catalog, _, _ in self.walk()]
+                    search = self.search(
+                        ids=ids, collections=[self.id, *child_catalogs]
+                    )
+            else:
+                search = self.search(ids=ids, collections=[self.id])
             yield from search.items()
         else:
             self._warn_about_fallback("ITEM_SEARCH")

tests/test_client.py

@@ -738,19 +738,58 @@ def test_collections_are_clients() -> None:
 
 
 @pytest.mark.vcr
-def test_get_items_without_ids() -> None:
+def test_get_items_recursion_collections_required_without_ids() -> None:
+    """
+    Make sure recursion using /search works when the server requires collections
+    when searching
+    """
     client = Client.open(
         "https://planetarycomputer.microsoft.com/api/stac/v1/",
     )
     next(client.get_items())
 
 
+@pytest.mark.vcr
+def test_get_items_recursion_no_collections_without_ids() -> None:
+    """
+    Make sure recursion using /search works when the server does not require collections
+    when searching
+    """
+    client = Client.open(
+        "https://paituli.csc.fi/geoserver/ogc/stac/v1/",
+    )
+    next(client.get_items())
+
+
+@pytest.mark.vcr
+def test_get_items_non_recursion() -> None:
+    """Make sure that non-recursive search is used when using /search"""
+    client = Client.open(
+        "https://planetarycomputer.microsoft.com/api/stac/v1/",
+    )
+    with pytest.raises(StopIteration):
+        next(client.get_items(recursive=False))
+
+
 @pytest.mark.vcr
 def test_non_recursion_on_fallback() -> None:
+    """
+    Make sure that non-recursive search using fallback only looks for
+    non-recursive items
+    """
+    path = "https://raw.githubusercontent.com/stac-utils/pystac/v1.9.0/docs/example-catalog/catalog.json"
+    catalog = Client.from_file(path)
+    with pytest.warns(FallbackToPystac), pytest.raises(StopIteration):
+        next(catalog.get_items(recursive=False))
+
+
+@pytest.mark.vcr
+def test_recursion_on_fallback() -> None:
+    """Make sure that recursive search using fallback looks for recursive items"""
     path = "https://raw.githubusercontent.com/stac-utils/pystac/v1.9.0/docs/example-catalog/catalog.json"
     catalog = Client.from_file(path)
     with pytest.warns(FallbackToPystac):
-        [i for i in catalog.get_items()]
+        next(catalog.get_items())
 
 
 @pytest.mark.vcr