Replace validate_has_extension with ensure_has_extension

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 - More permissive schema_uri matching to allow future versions of extension schemas ([#1231](https://github.com/stac-utils/pystac/pull/1231))
 
+### Changed
+
+- Deprecated `ExtensionManagementMixin.validate_has_extension` and replaced with `ExtensionManagementMixin.ensure_has_extension`. Calling `ExtensionManagementMixin.validate_has_extension` will raise a `DeprecationWarning` and call `ExtensionManagementMixin.ensure_has_extension` ([#1248](https://github.com/stac-utils/pystac/pull/1248))
+
 ## [v1.8.4] - 2023-09-22
 
 ### Added

docs/tutorials/adding-new-and-custom-extensions.ipynb

@@ -202,7 +202,7 @@
     "    @classmethod\n",
     "    def ext(cls, obj: pystac.Item, add_if_missing: bool = False) -> \"OrderExtension\":\n",
     "        if isinstance(obj, pystac.Item):\n",
-    "            cls.validate_has_extension(obj, add_if_missing)\n",
+    "            cls.ensure_has_extension(obj, add_if_missing)\n",
     "            return OrderExtension(obj)\n",
     "        else:\n",
     "            raise pystac.ExtensionTypeError(\n",

pystac/extensions/base.py

@@ -181,10 +181,35 @@ def validate_owner_has_extension(
                 )
             else:
                 return
-        return cls.validate_has_extension(cast(S, asset.owner), add_if_missing)
+        return cls.ensure_has_extension(cast(S, asset.owner), add_if_missing)
 
     @classmethod
     def validate_has_extension(cls, obj: S, add_if_missing: bool = False) -> None:
+        """
+        DEPRECATED
+
+        .. deprecated:: 1.9
+            Use :meth:`ensure_has_extension` instead.
+
+        Given a :class:`~pystac.STACObject`, checks if the object has this
+        extension's schema URI in its :attr:`~pystac.STACObject.stac_extensions` list.
+        If ``add_if_missing`` is ``True``, the schema URI will be added to the object.
+
+        Args:
+            obj : The object to validate.
+            add_if_missing : Whether to add the schema URI to the object if it is
+                not already present. Defaults to False.
+        """
+        warnings.warn(
+            "validate_has_extension is deprecated and will be removed in v1.9. "
+            "Use ensure_has_extension instead",
+            DeprecationWarning,
+        )
+
+        return cls.ensure_has_extension(obj, add_if_missing)
+
+    @classmethod
+    def ensure_has_extension(cls, obj: S, add_if_missing: bool = False) -> None:
         """Given a :class:`~pystac.STACObject`, checks if the object has this
         extension's schema URI in its :attr:`~pystac.STACObject.stac_extensions` list.
         If ``add_if_missing`` is ``True``, the schema URI will be added to the object.

pystac/extensions/classification.py

@@ -531,13 +531,13 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ClassificationExtension[T]
             pystac.ExtensionTypeError : If an invalid object type is passed
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(ClassificationExtension[T], ItemClassificationExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(ClassificationExtension[T], AssetClassificationExtension(obj))
         elif isinstance(obj, item_assets.AssetDefinition):
-            cls.validate_has_extension(
+            cls.ensure_has_extension(
                 cast(Union[pystac.Item, pystac.Collection], obj.owner), add_if_missing
             )
             return cast(
@@ -554,7 +554,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ClassificationExtension[T]
     def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesClassificationExtension:
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesClassificationExtension(obj)
 
 

pystac/extensions/datacube.py

@@ -537,10 +537,10 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> DatacubeExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Collection):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(DatacubeExtension[T], CollectionDatacubeExtension(obj))
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(DatacubeExtension[T], ItemDatacubeExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)

pystac/extensions/eo.py

@@ -405,7 +405,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> EOExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(EOExtension[T], ItemEOExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)
@@ -418,7 +418,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesEOExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesEOExtension(obj)
 
 

pystac/extensions/grid.py

@@ -105,7 +105,7 @@ def ext(cls, obj: pystac.Item, add_if_missing: bool = False) -> GridExtension:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return GridExtension(obj)
         else:
             raise pystac.ExtensionTypeError(cls._ext_error_message(obj))

pystac/extensions/item_assets.py

@@ -245,7 +245,7 @@ def ext(
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Collection):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cls(obj)
         else:
             raise pystac.ExtensionTypeError(cls._ext_error_message(obj))

pystac/extensions/label.py

@@ -711,7 +711,7 @@ def ext(cls, obj: pystac.Item, add_if_missing: bool = False) -> LabelExtension:
         This extension can be applied to instances of :class:`~pystac.Item`.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cls(obj)
         else:
             raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
@@ -721,7 +721,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesLabelExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesLabelExtension(obj)
 
 

pystac/extensions/mgrs.py

@@ -233,7 +233,7 @@ def ext(cls, obj: pystac.Item, add_if_missing: bool = False) -> "MgrsExtension":
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return MgrsExtension(obj)
         else:
             raise pystac.ExtensionTypeError(cls._ext_error_message(obj))

pystac/extensions/pointcloud.py

@@ -448,7 +448,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> PointcloudExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(PointcloudExtension[T], ItemPointcloudExtension(obj))
         elif isinstance(obj, pystac.Asset):
             if obj.owner is not None and not isinstance(obj.owner, pystac.Item):
@@ -464,7 +464,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> PointcloudExtension[T]:
     def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesPointcloudExtension:
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesPointcloudExtension(obj)
 
 

pystac/extensions/projection.py

@@ -285,7 +285,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ProjectionExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(ProjectionExtension[T], ItemProjectionExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)
@@ -298,7 +298,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesProjectionExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesProjectionExtension(obj)
 
 

pystac/extensions/raster.py

@@ -738,7 +738,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> RasterExtension[T]:
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(RasterExtension[T], AssetRasterExtension(obj))
         elif isinstance(obj, item_assets.AssetDefinition):
-            cls.validate_has_extension(
+            cls.ensure_has_extension(
                 cast(Union[pystac.Item, pystac.Collection], obj.owner), add_if_missing
             )
             return cast(RasterExtension[T], ItemAssetsRasterExtension(obj))
@@ -749,7 +749,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> RasterExtension[T]:
     def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesRasterExtension:
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesRasterExtension(obj)
 
 

pystac/extensions/sar.py

@@ -312,7 +312,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> SarExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(SarExtension[T], ItemSarExtension(obj))
         elif isinstance(obj, pystac.Asset):
             if obj.owner is not None and not isinstance(obj.owner, pystac.Item):
@@ -329,7 +329,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesSarExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesSarExtension(obj)
 
 

pystac/extensions/sat.py

@@ -147,7 +147,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> SatExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(SatExtension[T], ItemSatExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)
@@ -160,7 +160,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesSatExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesSatExtension(obj)
 
 

pystac/extensions/scientific.py

@@ -238,10 +238,10 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ScientificExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Collection):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(ScientificExtension[T], CollectionScientificExtension(obj))
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(ScientificExtension[T], ItemScientificExtension(obj))
         else:
             raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
@@ -251,7 +251,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesScientificExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesScientificExtension(obj)
 
 

pystac/extensions/storage.py

@@ -149,7 +149,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> StorageExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(StorageExtension[T], ItemStorageExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)
@@ -162,7 +162,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesStorageExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesStorageExtension(obj)
 
 

pystac/extensions/table.py

@@ -152,10 +152,10 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> TableExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Collection):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(TableExtension[T], CollectionTableExtension(obj))
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(TableExtension[T], ItemTableExtension(obj))
         if isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)

pystac/extensions/timestamps.py

@@ -128,7 +128,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> TimestampsExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(TimestampsExtension[T], ItemTimestampsExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)
@@ -141,7 +141,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesTimestampsExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesTimestampsExtension(obj)
 
 

pystac/extensions/version.py

@@ -213,10 +213,10 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> VersionExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Collection):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(VersionExtension[T], CollectionVersionExtension(obj))
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(VersionExtension[T], ItemVersionExtension(obj))
         else:
             raise pystac.ExtensionTypeError(cls._ext_error_message(obj))

pystac/extensions/view.py

@@ -157,7 +157,7 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> ViewExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(ViewExtension[T], ItemViewExtension(obj))
         elif isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)
@@ -170,7 +170,7 @@ def summaries(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> SummariesViewExtension:
         """Returns the extended summaries object for the given collection."""
-        cls.validate_has_extension(obj, add_if_missing)
+        cls.ensure_has_extension(obj, add_if_missing)
         return SummariesViewExtension(obj)
 
 

pystac/extensions/xarray_assets.py

@@ -54,10 +54,10 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> XarrayAssetsExtension[T]:
             pystac.ExtensionTypeError : If an invalid object type is passed.
         """
         if isinstance(obj, pystac.Collection):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return CollectionXarrayAssetsExtension(obj)
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return ItemXarrayAssetsExtension(obj)
         if isinstance(obj, pystac.Asset):
             cls.validate_owner_has_extension(obj, add_if_missing)

tests/extensions/test_custom.py

@@ -57,13 +57,13 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> "CustomExtension[T]":
             cls.validate_owner_has_extension(obj, add_if_missing)
             return cast(CustomExtension[T], AssetCustomExtension(obj))
         if isinstance(obj, pystac.Item):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(CustomExtension[T], ItemCustomExtension(obj))
         if isinstance(obj, pystac.Collection):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(CustomExtension[T], CollectionCustomExtension(obj))
         if isinstance(obj, pystac.Catalog):
-            cls.validate_has_extension(obj, add_if_missing)
+            cls.ensure_has_extension(obj, add_if_missing)
             return cast(CustomExtension[T], CatalogCustomExtension(obj))
 
         raise pystac.ExtensionTypeError(cls._ext_error_message(obj))