fix get items recursive documentation (stac-utils#800)

* fix get items recursive documentation

* update changelog

* add warning

* formatting update

Author: mishaschwartz

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
 

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: