Configurable warnings

pystac_client/client.py

@@ -1,5 +1,6 @@
 from functools import lru_cache
 from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Union
+import warnings
 
 import pystac
 import pystac.utils
@@ -27,6 +28,7 @@
     SortbyLike,
 )
 from pystac_client.stac_api_io import StacApiIO
+from pystac_client.warnings import FALLBACK_MSG, FallbackToPystac, MissingLink
 
 if TYPE_CHECKING:
     from pystac.item import Item as Item_Type
@@ -203,14 +205,14 @@ def from_file(  # type: ignore
 
         return client
 
+    def conforms_to(self, *conformance_classes: ConformanceClasses) -> bool:
+        return bool(self._stac_io and self._stac_io.conforms_to(*conformance_classes))
+
     def _supports_collections(self) -> bool:
-        return self._conforms_to(ConformanceClasses.COLLECTIONS) or self._conforms_to(
-            ConformanceClasses.FEATURES
+        return self.conforms_to(
+            ConformanceClasses.COLLECTIONS, ConformanceClasses.FEATURES
         )
 
-    def _conforms_to(self, conformance_class: ConformanceClasses) -> bool:
-        return self._stac_io.conforms_to(conformance_class)  # type: ignore
-
     @classmethod
     def from_dict(
         cls,
@@ -236,15 +238,19 @@ def from_dict(
         return result
 
     @lru_cache()
-    def get_collection(self, collection_id: str) -> Optional[Collection]:
+    def get_collection(
+        self, collection_id: str
+    ) -> Optional[Union[Collection, CollectionClient]]:
         """Get a single collection from this Catalog/API
 
         Args:
             collection_id: The Collection ID to get
 
         Returns:
-            CollectionClient: A STAC Collection
+            Union[Collection, CollectionClient]: A STAC Collection
         """
+        collection: Union[Collection, CollectionClient]
+
         if self._supports_collections() and self._stac_io:
             url = self._get_collections_href(collection_id)
             collection = CollectionClient.from_dict(
@@ -255,21 +261,22 @@ def get_collection(self, collection_id: str) -> Optional[Collection]:
             call_modifier(self.modifier, collection)
             return collection
         else:
-            for col in self.get_collections():
-                if col.id == collection_id:
-                    call_modifier(self.modifier, col)
-                    return col
+            warnings.warn(FALLBACK_MSG, category=FallbackToPystac)
+            for collection in super().get_collections():
+                if collection.id == collection_id:
+                    call_modifier(self.modifier, collection)
+                    return collection
 
         return None
 
-    def get_collections(self) -> Iterator[Collection]:
+    def get_collections(self) -> Iterator[Union[Collection, CollectionClient]]:
         """Get Collections in this Catalog
 
             Gets the collections from the /collections endpoint if supported,
             otherwise fall back to Catalog behavior of following child links
 
         Return:
-            Iterator[Collection]: Iterator over Collections in Catalog/API
+            Iterator[Union[Collection, CollectionClient]]: Collections in Catalog/API
         """
         collection: Union[Collection, CollectionClient]
 
@@ -285,6 +292,7 @@ def get_collections(self) -> Iterator[Collection]:
                     call_modifier(self.modifier, collection)
                     yield collection
         else:
+            warnings.warn(FALLBACK_MSG, category=FallbackToPystac)
             for collection in super().get_collections():
                 call_modifier(self.modifier, collection)
                 yield collection
@@ -296,10 +304,11 @@ def get_items(self) -> Iterator["Item_Type"]:
             Iterator[Item]:: Iterator of items whose parent is this
                 catalog.
         """
-        if self._conforms_to(ConformanceClasses.ITEM_SEARCH):
+        if self.conforms_to(ConformanceClasses.ITEM_SEARCH):
             search = self.search()
             yield from search.items()
         else:
+            warnings.warn(FALLBACK_MSG, category=FallbackToPystac)
             for item in super().get_items():
                 call_modifier(self.modifier, item)
                 yield item
@@ -313,13 +322,7 @@ def get_all_items(self) -> Iterator["Item_Type"]:
                 catalogs or collections connected to this catalog through
                 child links.
         """
-        if self._conforms_to(ConformanceClasses.ITEM_SEARCH):
-            # these are already modified
-            yield from self.get_items()
-        else:
-            for item in super().get_items():
-                call_modifier(self.modifier, item)
-                yield item
+        yield from self.get_items()
 
     def search(
         self,
@@ -438,26 +441,8 @@ def search(
                 or does not have a link with
                 a ``"rel"`` type of ``"search"``.
         """
-        if not self._conforms_to(ConformanceClasses.ITEM_SEARCH):
-            raise NotImplementedError(
-                "This catalog does not support search because it "
-                f'does not conform to "{ConformanceClasses.ITEM_SEARCH}"'
-            )
-        search_link = self.get_search_link()
-        if search_link:
-            if isinstance(search_link.target, str):
-                search_href = search_link.target
-            else:
-                raise NotImplementedError(
-                    "Link with rel=search was an object rather than a URI"
-                )
-        else:
-            raise NotImplementedError(
-                "No link with rel=search could be found in this catalog"
-            )
-
         return ItemSearch(
-            url=search_href,
+            url=self._get_search_href(),
             method=method,
             max_items=max_items,
             stac_io=self._stac_io,
@@ -497,35 +482,28 @@ def get_search_link(self) -> Optional[pystac.Link]:
             None,
         )
 
+    def _get_search_href(self) -> str:
+        search_link = self.get_search_link()
+        href = self._get_href("search", search_link, "search")
+        return href
+
     def _get_collections_href(self, collection_id: Optional[str] = None) -> str:
-        self_href = self.get_self_href()
-        if self_href is None:
-            data_link = self.get_single_link("data")
-            if data_link is None:
-                raise ValueError(
-                    "cannot build a collections href without a self href or a data link"
-                )
-            else:
-                collections_href = data_link.href
+        data_link = self.get_single_link("data")
+        href = self._get_href("data", data_link, "collections")
+        if collection_id is None:
+            return href
         else:
-            collections_href = f"{self_href.rstrip('/')}/collections"
-
-        if not pystac.utils.is_absolute_href(collections_href):
-            collections_href = self._make_absolute_href(collections_href)
+            return f"{href.rstrip('/')}/{collection_id}"
 
-        if collection_id is None:
-            return collections_href
+    def _get_href(self, rel: str, link: Optional[pystac.Link], endpoint: str) -> str:
+        if link and isinstance(link.href, str):
+            href = link.href
+            if not pystac.utils.is_absolute_href(href):
+                href = pystac.utils.make_absolute_href(href, self.self_href)
         else:
-            return f"{collections_href.rstrip('/')}/{collection_id}"
-
-    def _make_absolute_href(self, href: str) -> str:
-        self_link = self.get_single_link("self")
-        if self_link is None:
-            raise ValueError("cannot build an absolute href without a self link")
-        elif not pystac.utils.is_absolute_href(self_link.href):
-            raise ValueError(
-                "cannot build an absolute href from "
-                f"a relative self link: {self_link.href}"
+            warnings.warn(
+                f"No link with {rel=} could be found in this catalog",
+                category=MissingLink,
             )
-        else:
-            return pystac.utils.make_absolute_href(href, self_link.href)
+            href = f"{self.self_href.rstrip('/')}/{endpoint}"
+        return href

pystac_client/collection_client.py

@@ -138,7 +138,7 @@ def get_item(self, id: str, recursive: bool = False) -> Optional["Item_Type"]:
             else:
                 search_link = None
             if (
-                stac_io.conforms_to(ConformanceClasses.FEATURES)
+                stac_io._conforms_to(ConformanceClasses.FEATURES)
                 and items_link is not None
             ):
                 url = f"{items_link.href}/{id}"
@@ -152,7 +152,7 @@ def get_item(self, id: str, recursive: bool = False) -> Optional["Item_Type"]:
                         raise err
                 assert isinstance(item, pystac.Item)
             elif (
-                stac_io.conforms_to(ConformanceClasses.ITEM_SEARCH)
+                stac_io._conforms_to(ConformanceClasses.ITEM_SEARCH)
                 and search_link
                 and search_link.href
             ):

pystac_client/item_search.py

@@ -278,7 +278,7 @@ def __init__(
         else:
             self._stac_io = StacApiIO()
 
-        self._assert_conforms_to(ConformanceClasses.ITEM_SEARCH)
+        self._stac_io.conforms_to(ConformanceClasses.ITEM_SEARCH)
 
         self._max_items = max_items
         if self._max_items is not None and limit is not None:
@@ -308,9 +308,6 @@ def __init__(
             k: v for k, v in params.items() if v is not None
         }
 
-    def _assert_conforms_to(self, conformance_class: ConformanceClasses) -> None:
-        self._stac_io.assert_conforms_to(conformance_class)
-
     def get_parameters(self) -> Dict[str, Any]:
         if self.method == "POST":
             return self._parameters
@@ -369,7 +366,7 @@ def _format_query(self, value: Optional[QueryLike]) -> Optional[Dict[str, Any]]:
         if value is None:
             return None
 
-        self._assert_conforms_to(ConformanceClasses.QUERY)
+        self._stac_io.conforms_to(ConformanceClasses.QUERY)
 
         if isinstance(value, dict):
             return value
@@ -418,7 +415,7 @@ def _format_filter(self, value: Optional[FilterLike]) -> Optional[FilterLike]:
         if value is None:
             return None
 
-        self._assert_conforms_to(ConformanceClasses.FILTER)
+        self._stac_io.conforms_to(ConformanceClasses.FILTER)
 
         return value
 
@@ -562,7 +559,7 @@ def _format_sortby(self, value: Optional[SortbyLike]) -> Optional[Sortby]:
         if value is None:
             return None
 
-        self._assert_conforms_to(ConformanceClasses.SORT)
+        self._stac_io.conforms_to(ConformanceClasses.SORT)
 
         if isinstance(value, str):
             return [self._sortby_part_to_dict(part) for part in value.split(",")]
@@ -599,7 +596,7 @@ def _format_fields(self, value: Optional[FieldsLike]) -> Optional[Fields]:
         if value is None:
             return None
 
-        self._assert_conforms_to(ConformanceClasses.FIELDS)
+        self._stac_io.conforms_to(ConformanceClasses.FIELDS)
 
         if isinstance(value, str):
             return self._fields_to_dict(value.split(","))

pystac_client/stac_api_io.py

@@ -4,6 +4,7 @@
 from copy import deepcopy
 from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Union
 from urllib.parse import urlparse
+import warnings
 
 import pystac
 from pystac.link import Link
@@ -20,6 +21,7 @@
 
 from .conformance import CONFORMANCE_URIS, ConformanceClasses
 from .exceptions import APIError
+from .warnings import DoesNotConformTo
 
 if TYPE_CHECKING:
     from pystac.catalog import Catalog as Catalog_Type
@@ -263,7 +265,7 @@ def get_pages(
                 (link for link in page.get("links", []) if link["rel"] == "next"), None
             )
 
-    def assert_conforms_to(self, conformance_class: ConformanceClasses) -> None:
+    def conforms_to(self, *conformance_classes: ConformanceClasses) -> bool:
         """Raises a :exc:`NotImplementedError` if the API does not publish the given
         conformance class. This method only checks against the ``"conformsTo"``
         property from the API landing page and does not make any additional
@@ -272,11 +274,23 @@ def assert_conforms_to(self, conformance_class: ConformanceClasses) -> None:
         Args:
             conformance_class: The ``ConformanceClasses`` key to check conformance
             against.
+        Return:
+            bool: Indicates if the API conforms to the given spec or URI.
+
         """
-        if not self.conforms_to(conformance_class):
-            raise NotImplementedError(f"{conformance_class} not supported")
+        if any(map(self._conforms_to, conformance_classes)):
+            return True
+        else:
+            warnings.warn(
+                (
+                    "Catalog does not conform to "
+                    f"{', '.join(c.name for c in conformance_classes)}"
+                ),
+                category=DoesNotConformTo,
+            )
+            return False
 
-    def conforms_to(self, conformance_class: ConformanceClasses) -> bool:
+    def _conforms_to(self, conformance_class: ConformanceClasses) -> bool:
         """Whether the API conforms to the given standard. This method only checks
         against the ``"conformsTo"`` property from the API landing page and does not
         make any additional calls to a ``/conformance`` endpoint even if the API

pystac_client/warnings.py

@@ -0,0 +1,47 @@
+from contextlib import contextmanager
+import warnings
+
+
+FALLBACK_MSG = "Falling back to pystac. This might be slow."
+
+
+class PystacClientWarning(UserWarning):
+    """Base warning class"""
+
+    ...
+
+
+class DoesNotConformTo(PystacClientWarning):
+    """Inform user when client does not conform to extension"""
+
+    ...
+
+
+class MissingLink(PystacClientWarning):
+    """Inform user when link is properly implemented"""
+
+    ...
+
+
+class FallbackToPystac(PystacClientWarning):
+    """Inform user when falling back to pystac implementation"""
+
+    ...
+
+
+@contextmanager
+def strict():  # type: ignore
+    warnings.filterwarnings("error", category=PystacClientWarning)
+    try:
+        yield
+    finally:
+        warnings.resetwarnings()
+
+
+@contextmanager
+def lax():  # type: ignore
+    warnings.filterwarnings("ignore", category=PystacClientWarning)
+    try:
+        yield
+    finally:
+        warnings.resetwarnings()