change STACTypeError to create short informative message

Author: ircwaves

CHANGELOG.md

@@ -25,6 +25,7 @@
 - Updated raster extension to work with the item_assets extension's AssetDefinition objects ([#1110](https://github.com/stac-utils/pystac/pull/1110))
 - Return all validation errors from validation methods of `JsonSchemaSTACValidator` ([#1120](https://github.com/stac-utils/pystac/pull/1120))
 - EO extension updated to v1.1.0 ([#1131](https://github.com/stac-utils/pystac/pull/1131))
+- Use `id` in STACTypeError instead of entire dict ([#1126](https://github.com/stac-utils/pystac/pull/1126))
 
 ### Deprecated
 

pystac/catalog.py

@@ -1136,7 +1136,7 @@ def from_dict(
             d = migrate_to_latest(d, info)
 
         if not cls.matches_object_type(d):
-            raise STACTypeError(f"{d} does not represent a {cls.__name__} instance")
+            raise STACTypeError(d, cls)
 
         catalog_type = CatalogType.determine_type(d)
 
@@ -1187,8 +1187,6 @@ def from_file(
             stac_io = pystac.StacIO.default()
 
         result = super().from_file(href, stac_io)
-        if not isinstance(result, Catalog):
-            raise pystac.STACTypeError(f"{result} is not a {Catalog}.")
         result._stac_io = stac_io
 
         return result

pystac/collection.py

@@ -627,7 +627,7 @@ def from_dict(
             d = migrate_to_latest(d, info)
 
         if not cls.matches_object_type(d):
-            raise STACTypeError(f"{d} does not represent a {cls.__name__} instance")
+            raise STACTypeError(d, cls)
 
         catalog_type = CatalogType.determine_type(d)
 
@@ -754,15 +754,6 @@ def full_copy(
     ) -> Collection:
         return cast(Collection, super().full_copy(root, parent))
 
-    @classmethod
-    def from_file(
-        cls: Type[C], href: str, stac_io: Optional[pystac.StacIO] = None
-    ) -> C:
-        result = super().from_file(href, stac_io)
-        if not isinstance(result, Collection):
-            raise pystac.STACTypeError(f"{result} is not a {Collection}.")
-        return result
-
     @classmethod
     def matches_object_type(cls, d: Dict[str, Any]) -> bool:
         return identify_stac_object_type(d) == STACObjectType.COLLECTION

pystac/errors.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional, Union
+from typing import Any, Dict, Optional, Union
 
 
 class TemplateError(Exception):
@@ -24,7 +24,28 @@ class STACTypeError(Exception):
     a Catalog JSON was read in as an Item.
     """
 
-    pass
+    def __init__(
+        self,
+        bad_dict: Dict[str, Any],
+        expected: type,
+        extra_message: Optional[str] = "",
+    ):
+        """
+        Construct an exception with an appropriate error message from bad_dict and the
+        expected that it didn't align with.
+
+        Args:
+            bad_dict: Dictionary that did not match the expected type
+            expected: The expected type.
+            extra_message: message that will be appended to the exception message.
+        """
+        message = (
+            f"JSON (id = {bad_dict.get('id', 'unknown')}) does not represent"
+            f" a {expected.__name__} instance."
+        )
+        if extra_message:
+            message += " " + extra_message
+        super().__init__(message)
 
 
 class DuplicateObjectKeyError(Exception):

pystac/item.py

@@ -432,9 +432,7 @@ def from_dict(
             d = migrate_to_latest(d, info)
 
         if not cls.matches_object_type(d):
-            raise pystac.STACTypeError(
-                f"{d} does not represent a {cls.__name__} instance"
-            )
+            raise pystac.STACTypeError(d, cls)
 
         # some fields are passed through to __init__
         pass_through_fields = [
@@ -504,23 +502,11 @@ def full_copy(
     ) -> Item:
         return cast(Item, super().full_copy(root, parent))
 
-    @classmethod
-    def from_file(
-        cls: Type[T], href: str, stac_io: Optional[pystac.StacIO] = None
-    ) -> T:
-        result = super().from_file(href, stac_io)
-        if not isinstance(result, Item):
-            raise pystac.STACTypeError(f"{result} is not a {Item}.")
-        return result
-
     @classmethod
     def matches_object_type(cls, d: Dict[str, Any]) -> bool:
         for field in ("type", "stac_version"):
             if field not in d:
-                raise pystac.STACTypeError(
-                    f"{d} does not represent a {cls.__name__} instance"
-                    f"'{field}' is missing."
-                )
+                raise pystac.STACTypeError(d, cls, f"'{field}' is missing.")
         return identify_stac_object_type(d) == STACObjectType.ITEM
 
     @property

pystac/item_collection.py

@@ -175,7 +175,7 @@ def from_dict(
                 hit of a deepcopy.
         """
         if not cls.is_item_collection(d):
-            raise STACTypeError("Dict is not a valid ItemCollection")
+            raise STACTypeError(d, cls)
 
         items = [
             pystac.Item.from_dict(item, preserve_dict=preserve_dict, root=root)

pystac/serialization/identify.py

@@ -248,7 +248,8 @@ def identify_stac_object(json_dict: Dict[str, Any]) -> STACJSONDescription:
     object_type = identify_stac_object_type(json_dict)
 
     if object_type is None:
-        raise pystac.STACTypeError("JSON does not represent a STAC object.")
+        extra_message = f"'type' attribute is {json_dict.get('type', 'not set')}"
+        raise pystac.STACTypeError(json_dict, pystac.STACObject, extra_message)
 
     version_range = STACVersionRange()
 

tests/data-files/catalogs/invalid-catalog/catalog.json

@@ -0,0 +1,7 @@
+{
+  "type": "Catalog",
+  "id": "broken_cat",
+  "description": "test catalog w/o stac_version",
+  "links": [],
+  "stac_extensions": []
+}

tests/serialization/test_identify.py

@@ -69,7 +69,9 @@ def test_identify_invalid_stac_object_with_version(self) -> None:
         with pytest.raises(pystac.STACTypeError) as ctx:
             identify_stac_object(invalid_dict)
 
-        assert "JSON does not represent a STAC object" in str(ctx.value.args[0])
+        assert "JSON (id = concepts) does not represent a STACObject instance." in str(
+            ctx.value.args[0]
+        )
 
     def test_identify_non_stac_raises_error(self) -> None:
         plain_feature_dict = {
@@ -81,7 +83,9 @@ def test_identify_non_stac_raises_error(self) -> None:
         with pytest.raises(pystac.STACTypeError) as ctx:
             identify_stac_object(plain_feature_dict)
 
-        assert "JSON does not represent a STAC object" in str(ctx.value.args[0])
+        assert "JSON (id = unknown) does not represent a STACObject instance." in str(
+            ctx.value.args[0]
+        )
 
     def test_identify_invalid_with_stac_version(self) -> None:
         not_stac = {"stac_version": "0.9.0", "type": "Custom"}

tests/test_catalog.py

@@ -105,6 +105,12 @@ def test_from_dict_preserves_dict(self) -> None:
         _ = Catalog.from_dict(param_dict, preserve_dict=False)
         assert param_dict != catalog_dict
 
+    def test_from_file_bad_catalog(self) -> None:
+        with pytest.raises(pystac.errors.STACTypeError) as ctx:
+            _ = Catalog.from_file(TestCases.get_path(TestCases.bad_catalog_case))
+        assert "(id = broken_cat) does not represent a STACObject" in ctx.value.args[0]
+        assert "is Catalog" in ctx.value.args[0]
+
     def test_from_dict_set_root(self) -> None:
         path = TestCases.get_path("data-files/catalogs/test-case-1/catalog.json")
         with open(path) as f:
@@ -1281,7 +1287,7 @@ def test_catalog_with_href_caches_by_href(self) -> None:
         # cached only by HREF
         assert len(cache.id_keys_to_objects) == 0
 
-    def testfrom_invalid_dict_raises_exception(self) -> None:
+    def test_from_invalid_dict_raises_exception(self) -> None:
         stac_io = pystac.StacIO.default()
         collection_dict = stac_io.read_json(
             TestCases.get_path("data-files/collections/multi-extent.json")