diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f860329..26fdfc37 100644 --- a/CHANGELOG.md +++ b/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)) +- Clarify recursive behaviour of the `get_items` method in the method docstring ([#800](https://github.com/stac-utils/pystac-client/pull/800)) ## [v0.8.6] - 2025-02-11 diff --git a/pystac_client/client.py b/pystac_client/client.py index f7eb7c6c..0d7d189d 100644 --- a/pystac_client/client.py +++ b/pystac_client/client.py @@ -36,7 +36,12 @@ ) from pystac_client.mixins import QUERYABLES_ENDPOINT, QueryablesMixin from pystac_client.stac_api_io import StacApiIO, Timeout -from pystac_client.warnings import DoesNotConformTo, FallbackToPystac, NoConformsTo +from pystac_client.warnings import ( + DoesNotConformTo, + FallbackToPystac, + NoConformsTo, + PystacClientWarning, +) if TYPE_CHECKING: from pystac.item import Item as Item_Type @@ -450,13 +455,20 @@ def get_items( Args: ids: Zero or more item ids to find. - recursive: unused in pystac-client, but needed for falling back to pystac - + recursive: If this client conforms to the ITEM_SEARCH conformance class, + this is unused and this will always yield items recursively. + Otherwise, this will only return items recursively if True or None. Return: Iterator[Item]: Iterator of items whose parent is this catalog. """ if self.conforms_to(ConformanceClasses.ITEM_SEARCH): + if recursive is False: + warnings.warn( + "Getting items recursively using the /search endpoint " + "(the recursive argument is being ignored).", + PystacClientWarning, + ) search = self.search(ids=ids) yield from search.items() else: