Add __geo_interface__ for items

[gadomski]

Related Issue(s):

• Closes Implement __geo_interface__ #786

Description:
Adds __geo_interface__ for items, collections, and spatial extent. Includes a pystac.utils.box function that cribs from shapely, with a couple of tweaks. Collection and spatial extent geo interfaces are impelemented per @duckontheweb's suggestion (if len(bboxes) == 1, use that as a Polygon; if len(bboxes) > 1, use bboxes[1:] as a MultiPolygon).

I can see @philvarner's point that we're making an opinionated decision w.r.t. the Collection geointerface that may not be correct. It'd be good to get other's opinions on the correct Collection approach, and if there's disagreement it may make sense to remove it from this PR and put that decision off until later. I've pulled in a couple of reviewers for that reason.

PR Checklist:

• Code is formatted (run pre-commit run --all-files)
• Tests pass (run scripts/test)
• Documentation has been updated to reflect changes, if applicable
• This PR maintains or improves overall codebase code coverage.
• Changes are added to the CHANGELOG. See the docs for information about adding to the changelog.

[codecov-commenter]

Codecov Report

Base: 94.29% // Head: 94.31% // Increases project coverage by +0.01% 🎉

Coverage data is based on head (0f28b9f) compared to base (8b2a540).
Patch coverage: 100.00% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #885      +/-   ##
==========================================
+ Coverage   94.29%   94.31%   +0.01%     
==========================================
  Files          80       80              
  Lines       11909    11941      +32     
  Branches     1130     1132       +2     
==========================================
+ Hits        11230    11262      +32     
  Misses        496      496              
  Partials      183      183              

Impacted Files	Coverage Δ
pystac/collection.py	92.69% <100.00%> (+0.26%)	⬆️
pystac/item.py	88.88% <100.00%> (+0.17%)	⬆️
pystac/utils.py	95.48% <100.00%> (+0.10%)	⬆️
tests/test_collection.py	99.59% <100.00%> (+0.02%)	⬆️
tests/test_item.py	99.55% <100.00%> (+<0.01%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[TomAugspurger]

Collection and spatial extent geo interfaces are impelemented per @duckontheweb's suggestion (if len(bboxes) == 1, use that as a Polygon; if len(bboxes) > 1, use bboxes[1:] as a MultiPolygon)

This is a tough one, but worries me a bit. In pandas, I think we've regretted "values-dependent" behavior, where the output type or structure depends on the values of the input, rather than just the type, every single time we've done it (on purpose or accidentally).

What's the downside to always returning a MultiPolygon for a Collection (even if it has just a single member)? Will they be fundamentally harder for downstream consumers to use than a single Polygon?

[gadomski]

What's the downside to always returning a MultiPolygon for a Collection (even if it has just a single member)? Will they be fundamentally harder for downstream consumers to use than a single Polygon?

I don't know -- I don't have a great sense of the downstream tooling. It felt weird to make a thing Multi when I knew it wasn't but I don't have any fundamental problem with always doing a MultiPolygon.

IMO bigger issue is whether we include the first bounding box (full envelope) in that MultiPolygon

[gadomski]

I've removed __geo_interface__ for Collections and SpatialExtents, keeping it only for Items. This seems like the best way forward, since there isn't an obvious implementation for SpatialExtents.