Surface warnings when accessing deprecated collections #156

[TomAugspurger]

https://github.com/stac-extensions/version offers a mechanism for marking a collection or item as deprecated.

We at the Planetary Computer are deprecating our landsat-8-c2-l2 collection in favor of landsat-c2-l2. I would love it if querying a deprecated collection or item would surface a (Python) Depracation / FutureWarning

>>> catalog = pystac_client.Client.open("https://planetarycomputer.microsoft.com/api/stac/v1")
>>> landsat = catalog.get_collection("landsat-8-c2-l2")
FutureWarning("The collection 'landsat-8-c2-l2' is deprecated. Use 'landsat-c2-l2' instead.")

pystac-client would build the Collection. If it detects the version extension and it's marked as deprecated, then you'd look for a latest link and use it as the alternative.

Ideally something similar with search, but I don't know 100% know how that would work. We probably don't want to emit 100 warnings for a search with 100 deprecated items.

This should probably be easily configurable by an environment variable and perhaps a global variable. Users can do stuff with the warnings registry, but that's a bit unweildy.

re DeprecationWarning vs. FutureWarning, I don't know what best practice is these days. Previous versions of Python automatically silenced DeprecationWarnings that weren't running under __main__ so I've always used FutureWarning for stuff I want users to see. That might have changed in recent versions of python.

(Transferred from https://github.com/stac-utils/pystac-client/issues/156)