Raster Extension: simplify typing, implement #370, add to API docs

Author: duckontheweb

docs/api.rst

@@ -414,6 +414,43 @@ AssetProjectionExtension
    :members:
    :show-inheritance:
 
+Raster Extension
+----------------
+
+DataType
+~~~~~~~~
+
+.. autoclass:: pystac.extensions.raster.DataType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Statistics
+~~~~~~~~~~
+
+.. autoclass:: pystac.extensions.raster.Statistics
+   :members:
+
+Histogram
+~~~~~~~~~
+
+.. autoclass:: pystac.extensions.raster.Histogram
+   :members:
+
+RasterBand
+~~~~~~~~~~
+
+.. autoclass:: pystac.extensions.raster.RasterBand
+   :members:
+
+RasterExtension
+~~~~~~~~~~~~~~~
+
+.. autoclass:: pystac.extensions.raster.RasterExtension
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
 Scientific Extension
 --------------------
 

pystac/extensions/raster.py

@@ -4,7 +4,7 @@
 """
 
 import enum
-from typing import Any, Dict, Generic, Iterable, List, Optional, TypeVar, cast
+from typing import Any, Dict, Iterable, List, Optional
 
 import pystac
 from pystac.extensions.base import (
@@ -14,8 +14,6 @@
 )
 from pystac.utils import get_opt, get_required, map_opt
 
-T = TypeVar("T", pystac.Item, pystac.Asset)
-
 SCHEMA_URI = "https://stac-extensions.github.io/raster/v1.0.0/schema.json"
 
 BANDS_PROP = "raster:bands"
@@ -625,9 +623,7 @@ def to_dict(self) -> Dict[str, Any]:
         return self.properties
 
 
-class RasterExtension(
-    Generic[T], PropertiesExtension, ExtensionManagementMixin[pystac.Item]
-):
+class RasterExtension(PropertiesExtension, ExtensionManagementMixin[pystac.Item]):
     """An abstract class that can be used to extend the properties of an
     :class:`~pystac.Item` or :class:`~pystac.Asset` with properties from
     the :stac-ext:`Raster Extension <raster>`. This class is generic over
@@ -639,6 +635,25 @@ class RasterExtension(
     :class:`~ItemRasterExtension` to extend an :class:`~pystac.Item`).
     """
 
+    asset_href: str
+    """The ``href`` value of the :class:`~pystac.Asset` being extended."""
+
+    properties: Dict[str, Any]
+    """The :class:`~pystac.Asset` fields, including extension properties."""
+
+    additional_read_properties: Optional[Iterable[Dict[str, Any]]] = None
+    """If present, this will be a list containing 1 dictionary representing the
+    properties of the owning :class:`~pystac.Item`."""
+
+    def __init__(self, asset: pystac.Asset):
+        self.asset_href = asset.href
+        self.properties = asset.properties
+        if asset.owner and isinstance(asset.owner, pystac.Item):
+            self.additional_read_properties = [asset.owner.properties]
+
+    def __repr__(self) -> str:
+        return "<AssetRasterExtension Asset href={}>".format(self.asset_href)
+
     def apply(self, bands: List[RasterBand]) -> None:
         """Applies raster extension properties to the extended :class:`pystac.Item` or
         :class:`pystac.Asset`.
@@ -673,10 +688,20 @@ def _get_bands(self) -> Optional[List[RasterBand]]:
     def get_schema_uri(cls) -> str:
         return SCHEMA_URI
 
-    @staticmethod
-    def ext(obj: T) -> "RasterExtension[T]":
+    @classmethod
+    def ext(cls, obj: pystac.Asset) -> "RasterExtension":
+        """Extends the given STAC Object with properties from the :stac-ext:`Raster
+        Extension <raster>`.
+
+        This extension can be applied to instances of :class:`~pystac.Asset`.
+
+        Raises:
+
+            pystac.ExtensionTypeError : If an invalid object type is passed.
+        """
         if isinstance(obj, pystac.Asset):
-            return cast(RasterExtension[T], AssetRasterExtension(obj))
+            cls.validate_has_extension(obj)
+            return cls(obj)
         else:
             raise pystac.ExtensionTypeError(
                 f"Raster extension does not apply to type {type(obj)}"
@@ -687,35 +712,6 @@ def summaries(obj: pystac.Collection) -> "SummariesRasterExtension":
         return SummariesRasterExtension(obj)
 
 
-class AssetRasterExtension(RasterExtension[pystac.Asset]):
-    """A concrete implementation of :class:`RasterExtension` on an :class:`~pystac.Asset`
-    that extends the Asset fields to include properties defined in the
-    :stac-ext:`Raster Extension <raster>`.
-
-    This class should generally not be instantiated directly. Instead, call
-    :meth:`RasterExtension.ext` on an :class:`~pystac.Asset` to extend it.
-    """
-
-    asset_href: str
-    """The ``href`` value of the :class:`~pystac.Asset` being extended."""
-
-    properties: Dict[str, Any]
-    """The :class:`~pystac.Asset` fields, including extension properties."""
-
-    additional_read_properties: Optional[Iterable[Dict[str, Any]]] = None
-    """If present, this will be a list containing 1 dictionary representing the
-    properties of the owning :class:`~pystac.Item`."""
-
-    def __init__(self, asset: pystac.Asset):
-        self.asset_href = asset.href
-        self.properties = asset.properties
-        if asset.owner and isinstance(asset.owner, pystac.Item):
-            self.additional_read_properties = [asset.owner.properties]
-
-    def __repr__(self) -> str:
-        return "<AssetRasterExtension Asset href={}>".format(self.asset_href)
-
-
 class SummariesRasterExtension(SummariesExtension):
     """A concrete implementation of :class:`~SummariesExtension` that extends
     the ``summaries`` field of a :class:`~pystac.Collection` to include properties

tests/extensions/test_raster.py

@@ -198,3 +198,18 @@ def test_asset_bands(self) -> None:
             item.assets["test"].properties["raster:bands"][0]["statistics"]["minimum"],
             1,
         )
+
+    def test_extension_not_implemented(self) -> None:
+        # Should raise exception if Item does not include extension URI
+        item = pystac.Item.from_file(self.PLANET_EXAMPLE_URI)
+        item.stac_extensions.remove(RasterExtension.get_schema_uri())
+
+        # Should raise exception if owning Item does not include extension URI
+        asset = item.assets["data"]
+
+        with self.assertRaises(pystac.ExtensionNotImplemented):
+            _ = RasterExtension.ext(asset)
+
+        # Should succeed if Asset has no owner
+        ownerless_asset = pystac.Asset.from_dict(asset.to_dict())
+        _ = RasterExtension.ext(ownerless_asset)