[WIP] Configurable options

[jsignell]

Related Issue(s):

• Closes Issue with get_collections #320

Description:

EDIT: It just occurred to me that I might be able to simplify this a bunch by just always making a warning and then configuring the filterwarnings setting. I am experimenting with that approach now.

This PR borrows heavily from xarray and sets up a mechanism for configuring options. The idea is that by default pystac-client is flexible, but within a particular context the user can configure their settings to make pystac-client more strict.

The first options all have to do with how to respond to different events. Here's an example using on old version of earth-search that does not have a "rel=data" link defined.

from pystac_client import Client
from pystac_client.options import set_options

client = Client.open("https://earth-search.aws.element84.com/v0")
with set_options(on_missing_link="error", on_fallback_to_pystac="error"):
    client.get_collection("sentinel-s2-l2a")

---------------------------------------------------------------------------
NotImplementedError                       Traceback (most recent call last)
Cell In[1], line 6
      4 client = Client.open("https://earth-search.aws.element84.com/v0")
      5 with set_options(on_missing_link="error", on_fallback_to_pystac="error"):
----> 6     client.get_collection("sentinel-s2-l2a")

File ~/pystac-client/pystac_client/client.py:253, in Client.get_collection(self, collection_id)
    250 collection: Union[Collection, CollectionClient]
    252 if self._supports_collections() and self._stac_io:
--> 253     url = self._get_collections_href(collection_id)
    254     collection = CollectionClient.from_dict(
    255         self._stac_io.read_json(url),
    256         root=self,
    257         modifier=self.modifier,
    258     )
    259     call_modifier(self.modifier, collection)

File ~/pystac-client/pystac_client/client.py:490, in Client._get_collections_href(self, collection_id)
    488 def _get_collections_href(self, collection_id: Optional[str] = None) -> str:
    489     data_link = self.get_single_link("data")
--> 490     href = self._get_href("data", data_link, "collections")
    491     if collection_id is None:
    492         return href

File ~/pystac-client/pystac_client/client.py:502, in Client._get_href(self, rel, link, endpoint)
    500         href = pystac.utils.make_absolute_href(href, self.self_href)
    501 else:
--> 502     respond(
    503         "missing_link", f"No link with {rel=} could be found in this catalog"
    504     )
    505     href = f"{self.self_href.rstrip('/')}/{endpoint}"
    506 return href

File ~/pystac-client/pystac_client/_utils.py:40, in respond(event, msg)
     38     warnings.warn(msg, UserWarning)
     39 elif on_event == "error":
---> 40     raise NotImplementedError(msg)

NotImplementedError: No link with rel='data' could be found in this catalog

Example from #320:

from pystac_client import Client
from pystac_client.options import set_options

set_options(on_fallback_to_pystac="error")

STAC_URL = 'https://cmr.earthdata.nasa.gov/stac'
catalog = Client.open(f'{STAC_URL}/OB_DAAC')
  
for c in catalog.get_collections():
    print(c)

/home/jsignell/pystac-client/pystac_client/_utils.py:38: UserWarning: Catalog does not conform to COLLECTIONS, FEATURES
  warnings.warn(msg, UserWarning)
---------------------------------------------------------------------------
NotImplementedError                       Traceback (most recent call last)
Cell In[1], line 9
      6 STAC_URL = 'https://cmr.earthdata.nasa.gov/stac'
      7 catalog = Client.open(f'{STAC_URL}/OB_DAAC')
----> 9 for c in catalog.get_collections():
     10     print(c)

File ~/pystac-client/pystac_client/client.py:293, in Client.get_collections(self)
    291             yield collection
    292 else:
--> 293     respond("fallback_to_pystac", "Falling back to pystac. This might be slow.")
    294     for collection in super().get_collections():
    295         call_modifier(self.modifier, collection)

File ~/pystac-client/pystac_client/_utils.py:40, in respond(event, msg)
     38     warnings.warn(msg, UserWarning)
     39 elif on_event == "error":
---> 40     raise NotImplementedError(msg)

NotImplementedError: Falling back to pystac. This might be slow.

The individual options are modular but they could be grouped into a more succinct flag like strict.

PR Checklist:

• Code is formatted
• Tests pass
• Changes are added to the CHANGELOG