Add docs and hint about extension summaries (#1157)

* Add example using summaries in docs

* Include hint about summaries if appropriate

* Update changelog

* Update pystac/extensions/base.py

Co-authored-by: Ian Cooke <ircwaves@users.noreply.github.com>

* Add tests for MGRS and classification, clean up punctuation

---------

Co-authored-by: Ian Cooke <ircwaves@users.noreply.github.com>

Author: jsignell

CHANGELOG.md

@@ -17,7 +17,7 @@
 - `get_derived_from`, `add_derived_from` and `remove_derived_from` to Items ([#1136](https://github.com/stac-utils/pystac/pull/1136))
 - `ItemEOExtension.get_assets` for getting assets filtered on band `name` or `common_name` ([#1140](https://github.com/stac-utils/pystac/pull/1140))
 - `max_items` and `recursive` to `Catalog.validate_all` ([#1141](https://github.com/stac-utils/pystac/pull/1141))
-- `KML` as a built in media type ([#1127](https://github.com/stac-utils/pystac/issues/1127))  
+- `KML` as a built in media type ([#1127](https://github.com/stac-utils/pystac/issues/1127))
 
 ### Changed
 
@@ -35,6 +35,7 @@
 - Use `id` in STACTypeError instead of entire dict ([#1126](https://github.com/stac-utils/pystac/pull/1126))
 - Make sure that `get_items` is backwards compatible ([#1139](https://github.com/stac-utils/pystac/pull/1139))
 - Make `_repr_html_` look like `_repr_json_` output ([#1142](https://github.com/stac-utils/pystac/pull/1142))
+- Improved error message when `.ext` is called on a Collection ([#1157](https://github.com/stac-utils/pystac/pull/1157))
 
 ### Deprecated
 

docs/concepts.rst

@@ -482,14 +482,15 @@ Extension <eo>`, you can access the properties associated with that extension us
    import pystac
    from pystac.extensions.eo import EOExtension
 
-   item = Item(...)  # See docs for creating an Item
+   item = pystac.Item.from_file("tests/data-files/eo/eo-landsat-example.json")
 
    # Check that the Item implements the EO Extension
    if EOExtension.has_extension(item):
       eo_ext = EOExtension.ext(item)
 
       bands = eo_ext.bands
       cloud_cover = eo_ext.cloud_cover
+      snow_cover = eo_ext.snow_cover
       ...
 
 .. note:: The ``ext`` method will raise an :exc:`~pystac.ExtensionNotImplemented`
@@ -511,7 +512,7 @@ can therefore mutate those properties.* For instance:
 
 .. code-block:: python
 
-   item = Item.from_file("tests/data-files/eo/eo-landsat-example.json")
+   item = pystac.Item.from_file("tests/data-files/eo/eo-landsat-example.json")
    print(item.properties["eo:cloud_cover"])
    # 78
 
@@ -563,7 +564,7 @@ extended.
 .. code-block:: python
 
    # Load a basic item without any extensions
-   item = Item.from_file("tests/data-files/item/sample-item.json")
+   item = pystac.Item.from_file("tests/data-files/item/sample-item.json")
    print(item.stac_extensions)
    # []
 
@@ -575,14 +576,38 @@ extended.
 Extended Summaries
 ------------------
 
-Extension classes like :class:`~pystac.extensions.eo.EOExtension` may also provide a
-``summaries`` static method that can be used to extend the Collection summaries. This
-method returns a class inheriting from
+Extension classes like :class:`~pystac.extensions.projection.ProjectionExtension` may
+also provide a ``summaries`` static method that can be used to extend the Collection
+summaries. This method returns a class inheriting from
 :class:`pystac.extensions.base.SummariesExtension` that provides tools for summarizing
 the properties defined by that extension. These classes also hold a reference to the
 Collection's :class:`pystac.Summaries` instance in the ``summaries`` attribute.
 
-See :class:`pystac.extensions.eo.SummariesEOExtension` for an example implementation.
+
+.. code-block:: python
+
+   import pystac
+   from pystac.extensions.projection import ProjectionExtension
+
+   # Load a collection that does not implement the Projection extension
+   collection = pystac.Collection.from_file(
+      "tests/data-files/examples/1.0.0/collection.json"
+   )
+
+   # Add Projection extension summaries to the collection
+   proj = ProjectionExtension.summaries(collection, add_if_missing=True)
+   print(collection.stac_extensions)
+   # [
+   #     ....,
+   #     'https://stac-extensions.github.io/projection/v1.1.0/schema.json'
+   # ]
+
+   # Set the values for various extension fields
+   proj.epsg = [4326]
+   collection_as_dict = collection.to_dict()
+   collection_as_dict["summaries"]["proj:epsg"]
+   # [4326]
+
 
 Item Asset properties
 =====================

pystac/extensions/base.py

@@ -191,3 +191,11 @@ def validate_has_extension(cls, obj: S, add_if_missing: bool = False) -> None:
             raise pystac.ExtensionNotImplemented(
                 f"Could not find extension schema URI {cls.get_schema_uri()} in object."
             )
+
+    @classmethod
+    def _ext_error_message(cls, obj: Any) -> str:
+        contents = [f"{cls.__name__} does not apply to type '{type(obj).__name__}'"]
+        if hasattr(cls, "summaries") and isinstance(obj, pystac.Collection):
+            hint = f"Hint: Did you mean to use `{cls.__name__}.summaries` instead?"
+            contents.append(hint)
+        return ". ".join(contents)

pystac/extensions/classification.py

@@ -542,12 +542,8 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ClassificationExtension[T]
             return cast(
                 ClassificationExtension[T], RasterBandClassificationExtension(obj)
             )
-
         else:
-            raise pystac.ExtensionTypeError(
-                "Classification extension does not apply to type "
-                f"'{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/datacube.py

@@ -602,9 +602,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> DatacubeExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(DatacubeExtension[T], AssetDatacubeExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Datacube extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
 
 class CollectionDatacubeExtension(DatacubeExtension[pystac.Collection]):

pystac/extensions/eo.py

@@ -406,9 +406,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> EOExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(EOExtension[T], AssetEOExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"EO extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/file.py

@@ -227,9 +227,7 @@ def ext(cls, obj: pystac.Asset, add_if_missing: bool = False) -> FileExtension:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cls(obj)
         else:
-            raise pystac.ExtensionTypeError(
-                f"File Info extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
 
 class FileExtensionHooks(ExtensionHooks):

pystac/extensions/grid.py

@@ -103,9 +103,7 @@ def ext(cls, obj: pystac.Item, add_if_missing: bool = False) -> GridExtension:
             cls.validate_has_extension(obj, add_if_missing)
             return GridExtension(obj)
         else:
-            raise pystac.ExtensionTypeError(
-                f"Grid Extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
 
 class GridExtensionHooks(ExtensionHooks):

pystac/extensions/item_assets.py

@@ -248,9 +248,7 @@ def ext(
             cls.validate_has_extension(obj, add_if_missing)
             return cls(obj)
         else:
-            raise pystac.ExtensionTypeError(
-                f"Item Assets extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
 
 class ItemAssetsExtensionHooks(ExtensionHooks):

pystac/extensions/label.py

@@ -709,9 +709,7 @@ def ext(cls, obj: pystac.Item, add_if_missing: bool = False) -> LabelExtension:
             cls.validate_has_extension(obj, add_if_missing)
             return cls(obj)
         else:
-            raise pystac.ExtensionTypeError(
-                f"Label extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/mgrs.py

@@ -235,9 +235,7 @@ def ext(cls, obj: pystac.Item, add_if_missing: bool = False) -> "MgrsExtension":
             cls.validate_has_extension(obj, add_if_missing)
             return MgrsExtension(obj)
         else:
-            raise pystac.ExtensionTypeError(
-                f"MGRS Extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
 
 class MgrsExtensionHooks(ExtensionHooks):

pystac/extensions/pointcloud.py

@@ -458,9 +458,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> PointcloudExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(PointcloudExtension[T], AssetPointcloudExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Pointcloud extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/projection.py

@@ -286,9 +286,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ProjectionExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(ProjectionExtension[T], AssetProjectionExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Projection extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/raster.py

@@ -737,9 +737,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> RasterExtension[T]:
             )
             return cast(RasterExtension[T], ItemAssetsRasterExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Raster extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/sar.py

@@ -322,9 +322,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> SarExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(SarExtension[T], AssetSarExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"SAR extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/sat.py

@@ -153,9 +153,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> SatExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(SatExtension[T], AssetSatExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Satellite extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/scientific.py

@@ -244,9 +244,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ScientificExtension[T]:
             cls.validate_has_extension(obj, add_if_missing)
             return cast(ScientificExtension[T], ItemScientificExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Scientific extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/storage.py

@@ -155,9 +155,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> StorageExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(StorageExtension[T], AssetStorageExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"StorageExtension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/table.py

@@ -161,9 +161,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> TableExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(TableExtension[T], AssetTableExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Table extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @property
     def columns(self) -> Optional[List[Column]]:

pystac/extensions/timestamps.py

@@ -134,9 +134,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> TimestampsExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(TimestampsExtension[T], AssetTimestampsExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Timestamps extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

pystac/extensions/version.py

@@ -219,9 +219,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> VersionExtension[T]:
             cls.validate_has_extension(obj, add_if_missing)
             return cast(VersionExtension[T], ItemVersionExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"Version extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
 
 class CollectionVersionExtension(VersionExtension[pystac.Collection]):

pystac/extensions/view.py

@@ -163,9 +163,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ViewExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(ViewExtension[T], AssetViewExtension(obj))
         else:
-            raise pystac.ExtensionTypeError(
-                f"View extension does not apply to type '{type(obj).__name__}'"
-            )
+            raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
     @classmethod
     def summaries(

tests/data-files/examples/1.0.0/collection.json

@@ -60,10 +60,6 @@
       "minimum": 1.2,
       "maximum": 1.2
     },
-    "proj:epsg": {
-      "minimum": 32659,
-      "maximum": 32659
-    },
     "view:sun_elevation": {
       "minimum": 54.9,
       "maximum": 54.9

tests/extensions/test_classification.py

@@ -107,6 +107,15 @@ def test_ext_raises_if_item_does_not_conform(plain_item: Item) -> None:
         ClassificationExtension.ext(plain_item)
 
 
+def test_ext_raises_on_collection(collection: pystac.Collection) -> None:
+    with pytest.raises(
+        pystac.errors.ExtensionTypeError,
+        match="ClassificationExtension does not apply to type 'Collection'",
+    ) as e:
+        ClassificationExtension.ext(collection)  # type:ignore
+    assert "Hint" in str(e.value)
+
+
 def test_apply_bitfields(plain_item: Item) -> None:
     ClassificationExtension.add_to(plain_item)
     ClassificationExtension.ext(plain_item).apply(

tests/extensions/test_custom.py

@@ -66,9 +66,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> "CustomExtension[T]":
             cls.validate_has_extension(obj, add_if_missing)
             return cast(CustomExtension[T], CatalogCustomExtension(obj))
 
-        raise pystac.ExtensionTypeError(
-            f"Custom extension does not apply to {type(obj).__name__}"
-        )
+        raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
 
 
 class CatalogCustomExtension(CustomExtension[pystac.Catalog]):

tests/extensions/test_datacube.py

@@ -57,7 +57,7 @@ def test_should_raise_exception_when_passing_invalid_extension_object(
     ) -> None:
         self.assertRaisesRegex(
             ExtensionTypeError,
-            r"^Datacube extension does not apply to type 'object'$",
+            r"^DatacubeExtension does not apply to type 'object'$",
             DatacubeExtension.ext,
             object(),
         )

tests/extensions/test_eo.py

@@ -342,7 +342,7 @@ def test_should_raise_exception_when_passing_invalid_extension_object(
     ) -> None:
         self.assertRaisesRegex(
             ExtensionTypeError,
-            r"^EO extension does not apply to type 'object'$",
+            r"^EOExtension does not apply to type 'object'$",
             EOExtension.ext,
             object(),
         )
@@ -472,3 +472,13 @@ def test_get_assets_works_even_if_band_info_is_incomplete(
 
     assets = eo_ext.get_assets(common_name=common_name)  # type:ignore
     assert len(assets) == 0
+
+
+def test_exception_should_include_hint_if_obj_is_collection(
+    collection: pystac.Collection,
+) -> None:
+    with pytest.raises(
+        ExtensionTypeError,
+        match="Hint: Did you mean to use `EOExtension.summaries` instead?",
+    ):
+        EOExtension.ext(collection)  # type:ignore

tests/extensions/test_file.py

@@ -232,7 +232,7 @@ def test_should_raise_exception_when_passing_invalid_extension_object(
     ) -> None:
         self.assertRaisesRegex(
             ExtensionTypeError,
-            r"^File Info extension does not apply to type 'object'$",
+            r"^FileExtension does not apply to type 'object'$",
             FileExtension.ext,
             object(),
         )