Simpler extension interface

[jsignell]

Related Issue(s):

• Closes Simpler extension interface #1051

Description:

When the extension is implemented:

import pystac

PROJ_EXT_EXAMPLE_URL = "https://raw.githubusercontent.com/stac-extensions/projection/v1.1.0/examples/item.json"

item = pystac.Item.from_file(PROJ_EXT_EXAMPLE_URL)
item.ext.proj.epsg
# 32659

When the extension isn't implemented:

item.ext.eo

---------------------------------------------------------------------------
ExtensionNotImplemented                   Traceback (most recent call last)
Cell In[5], line 1
----> 1 item.ext.eo

File ~/pystac/pystac/extensions/ext.py:47, in ItemExt.eo(self)
     45 @property
     46 def eo(self) -> EOExtension[pystac.Item]:
---> 47     return EOExtension.ext(self.stac_object)

File ~/pystac/pystac/extensions/eo.py:408, in EOExtension.ext(cls, obj, add_if_missing)
    397 """Extends the given STAC Object with properties from the
    398 :stac-ext:`Electro-Optical Extension <eo>`.
    399 
   (...)
    405     pystac.ExtensionTypeError : If an invalid object type is passed.
    406 """
    407 if isinstance(obj, pystac.Item):
--> 408     cls.validate_has_extension(obj, add_if_missing)
    409     return cast(EOExtension[T], ItemEOExtension(obj))
    410 elif isinstance(obj, pystac.Asset):

File ~/pystac/pystac/extensions/base.py:201, in ExtensionManagementMixin.validate_has_extension(cls, obj, add_if_missing)
    198     cls.add_to(obj)
    200 if not cls.has_extension(obj):
--> 201     raise pystac.ExtensionNotImplemented(
    202         f"Could not find extension schema URI {cls.get_schema_uri()} in object."
    203     )

ExtensionNotImplemented: Could not find extension schema URI https://stac-extensions.github.io/eo/v1.1.0/schema.json in object.

Add an extension

item.ext.add("eo")

PR Checklist:

• pre-commit hooks pass locally
• 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]

Codecov Report

Attention: 57 lines in your changes are missing coverage. Please review.

Files	Coverage Δ
pystac/asset.py	97.14% <100.00%> (+0.11%)	⬆️
pystac/collection.py	93.05% <100.00%> (+0.09%)	⬆️
pystac/extensions/classification.py	95.03% <100.00%> (+0.01%)	⬆️
pystac/extensions/file.py	91.85% <100.00%> (+0.06%)	⬆️
pystac/extensions/grid.py	96.29% <100.00%> (+0.06%)	⬆️
pystac/extensions/item_assets.py	95.57% <100.00%> (+0.20%)	⬆️
pystac/extensions/label.py	93.33% <100.00%> (+0.01%)	⬆️
pystac/extensions/mgrs.py	98.71% <100.00%> (+0.01%)	⬆️
pystac/extensions/raster.py	90.25% <100.00%> (+0.03%)	⬆️
pystac/extensions/scientific.py	95.03% <100.00%> (+0.03%)	⬆️
... and 16 more

📢 Thoughts on this report? Let us know!.

[gadomski]

Concept seems good to me! Hopefully this will be a pretty low maintenance burden once it gets set up, since most of the work is still in the extensions themselves.

[jsignell]

okie dokie! It's greeeeennnn over here

[jsignell]

I guess I can do the docs updates on this branch as well.

[gadomski]

No notes on the impl, I'm 👍🏼 ^ 2. Looks great. I think we just need docstrings on the functions, and maybe a "Making a new extension class" tutorial? The tutorial could be its own ticket too if you want to push this in first.

[philvarner]

1. I'd prefer if item.ext.eo returned None rather than throwing an Exception. I guess it's more Pythonic to throw an exception for everything, but dislike that convention, since it's not an error condition if the Item doesn't implement the extension.

With that, I could write code as:

if eo := item.ext.eo:
  print(eo.cloud_cover)

instead of:

try:
  print(eo.cloud_cover)
except ExtensionNotImplemented:
  pass

2. I'd prefer if item.ext.add, instead of accepting a raw string parameter (presumably the Field Name Prefix?) took a parameter of a custom type (e.g., Extension) that all extensions had to implement, as a form of dynamic enum. That would give better typechecking than just a string, which in practice is pretty error-prone.

[gadomski]

That would give better typechecking than just a string, which in practice is pretty error-prone.

I think the use of Literal here makes the type checking better: https://github.com/stac-utils/pystac/pull/1243/files#diff-3a39d1c18e4343de9e2ad0a08ee71c3e616589cbc3677eeac625e679f195ea16R27-R47.

took a parameter of a custom type (e.g., Extension)

I believe @jsignell started with an Enum implementation, but it felt clunky. I think a soft design goal here might be "access and set extension attributes without additional imports"?

I'd prefer if item.ext.eo returned None rather than throwing an Exception.

The only downside here is that for type checking, item.ext.eo then becomes Optional[Extension], so you have to do assert item.ext.eo before accessing the attributes to make mypy happy. The "throw if absent" pattern makes the "I know it's there" use case slightly less verbose. 🤷🏼

[jsignell]

I'd prefer if item.ext.eo returned None rather than throwing an Exception.

The only downside here is that for type checking, item.ext.eo then becomes Optional[Extension], so you have to do assert item.ext.eo before accessing the attributes to make mypy happy. The "throw if absent" pattern makes the "I know it's there" use case slightly less verbose. 🤷🏼

I didn't call it out in my example, but there is also a has method so the no-error incantation would be:

if item.ext.has("eo"):
    print(item.ext.eo.cloud_cover)

Does that feel better?

[philvarner]

I'm fine with whatever y'all decide on.

[jsignell]

Finally circled back. I took a pass at the docs and tutorials as well.

[gadomski]

🎉 thanks for this @jsignell really stoked about it.