Add keywords to common metadata (stac-utils#1443)

* add keywords to common metadata

* Update pystac/common_metadata.py

* fix: lint

---------

Co-authored-by: Pete Gadomski <[email protected]>

Author: 2 people

CHANGELOG.md

@@ -13,6 +13,7 @@
 - Add netCDF to pystac.media_type ([#1386](https://github.com/stac-utils/pystac/pull/1386))
 - Add convenience method for accessing pystac_client ([#1365](https://github.com/stac-utils/pystac/pull/1365))
 - Fix field ordering when saving `Item`s ([#1423](https://github.com/stac-utils/pystac/pull/1423))
+- Add keywords to common metadata ([#1443](https://github.com/stac-utils/pystac/pull/1443))
 - Add roles to common metadata ([#1444](https://github.com/stac-utils/pystac/pull/1444/files))
 
 ### Changed

pystac/common_metadata.py

@@ -232,6 +232,15 @@ def updated(self) -> datetime | None:
     def updated(self, v: datetime | None) -> None:
         self._set_field("updated", utils.map_opt(utils.datetime_to_str, v))
 
+    @property
+    def keywords(self) -> list[str] | None:
+        """Get or set the keywords describing the STAC entity."""
+        return self._get_field("keywords", list[str])
+
+    @keywords.setter
+    def keywords(self, v: list[str] | None) -> None:
+        self._set_field("keywords", v)
+
     @property
     def roles(self) -> list[str] | None:
         """Get or set the semantic roles of the entity."""

pystac/extensions/ext.py

@@ -12,6 +12,7 @@
 from pystac.extensions.pointcloud import PointcloudExtension
 from pystac.extensions.projection import ProjectionExtension
 from pystac.extensions.raster import RasterExtension
+from pystac.extensions.render import Render, RenderExtension
 from pystac.extensions.sar import SarExtension
 from pystac.extensions.sat import SatExtension
 from pystac.extensions.scientific import ScientificExtension
@@ -36,6 +37,7 @@
     "pc",
     "proj",
     "raster",
+    "render",
     "sar",
     "sat",
     "sci",
@@ -58,6 +60,7 @@
     PointcloudExtension.name: PointcloudExtension,
     ProjectionExtension.name: ProjectionExtension,
     RasterExtension.name: RasterExtension,
+    RenderExtension.name: RenderExtension,
     SarExtension.name: SarExtension,
     SatExtension.name: SatExtension,
     ScientificExtension.name: ScientificExtension,
@@ -110,6 +113,10 @@ def cube(self) -> DatacubeExtension[Collection]:
     def item_assets(self) -> dict[str, AssetDefinition]:
         return ItemAssetsExtension.ext(self.stac_object).item_assets
 
+    @property
+    def render(self) -> dict[str, Render]:
+        return RenderExtension.ext(self.stac_object).renders
+
     @property
     def sci(self) -> ScientificExtension[Collection]:
         return ScientificExtension.ext(self.stac_object)
@@ -164,6 +171,10 @@ def pc(self) -> PointcloudExtension[Item]:
     def proj(self) -> ProjectionExtension[Item]:
         return ProjectionExtension.ext(self.stac_object)
 
+    @property
+    def render(self) -> RenderExtension[Item]:
+        return RenderExtension.ext(self.stac_object)
+
     @property
     def sar(self) -> SarExtension[Item]:
         return SarExtension.ext(self.stac_object)

pystac/extensions/render.py

@@ -0,0 +1,273 @@
+"""Implements the :stac-ext:`Render Extension <render>`."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, Literal, TypeVar
+
+import pystac
+from pystac.extensions.base import ExtensionManagementMixin, PropertiesExtension
+from pystac.extensions.hooks import ExtensionHooks
+from pystac.utils import get_required, map_opt
+
+T = TypeVar("T", pystac.Collection, pystac.Item)
+
+SCHEMA_URI_PATTERN: str = (
+    "https://stac-extensions.github.io/render/v{version}/schema.json"
+)
+DEFAULT_VERSION: str = "1.0.0"
+
+SUPPORTED_VERSIONS = [DEFAULT_VERSION]
+
+RENDERS_PROP = "renders"
+
+
+class Render:
+    properties: dict[str, Any]
+
+    def __init__(self, properties: dict[str, Any]) -> None:
+        self.properties = properties
+
+    @property
+    def assets(self) -> list[str]:
+        return get_required(self.properties.get("assets"), self, "assets")
+
+    @assets.setter
+    def assets(self, v: list[str]) -> None:
+        self.properties["assets"] = v
+
+    @property
+    def title(self) -> str | None:
+        return self.properties.get("title")
+
+    @title.setter
+    def title(self, v: str | None) -> None:
+        if v is not None:
+            self.properties["title"] = v
+        else:
+            self.properties.pop("title", None)
+
+    @property
+    def rescale(self) -> list[list[float]] | None:
+        return self.properties.get("rescale")
+
+    @rescale.setter
+    def rescale(self, v: list[list[float]] | None) -> None:
+        if v is not None:
+            self.properties["rescale"] = v
+        else:
+            self.properties.pop("rescale", None)
+
+    @property
+    def nodata(self) -> float | str | None:
+        return self.properties.get("nodata")
+
+    @nodata.setter
+    def nodata(self, v: float | str | None) -> None:
+        if v is not None:
+            self.properties["nodata"] = v
+        else:
+            self.properties.pop("nodata", None)
+
+    @property
+    def colormap_name(self) -> str | None:
+        return self.properties.get("colormap_name")
+
+    @colormap_name.setter
+    def colormap_name(self, v: str | None) -> None:
+        if v is not None:
+            self.properties["colormap_name"] = v
+        else:
+            self.properties.pop("colormap_name", None)
+
+    @property
+    def colormap(self) -> dict[str, Any] | None:
+        return self.properties.get("colormap")
+
+    @colormap.setter
+    def colormap(self, v: dict[str, Any] | None) -> None:
+        if v is not None:
+            self.properties["colormap"] = v
+        else:
+            self.properties.pop("colormap", None)
+
+    @property
+    def color_formula(self) -> str | None:
+        return self.properties.get("color_formula")
+
+    @color_formula.setter
+    def color_formula(self, v: str | None) -> None:
+        if v is not None:
+            self.properties["color_formula"] = v
+        else:
+            self.properties.pop("color_formula", None)
+
+    @property
+    def resampling(self) -> str | None:
+        return self.properties.get("resampling")
+
+    @resampling.setter
+    def resampling(self, v: str | None) -> None:
+        if v is not None:
+            self.properties["resampling"] = v
+        else:
+            self.properties.pop("resampling", None)
+
+    @property
+    def expression(self) -> str | None:
+        return self.properties.get("expression")
+
+    @expression.setter
+    def expression(self, v: str | None) -> None:
+        if v is not None:
+            self.properties["expression"] = v
+        else:
+            self.properties.pop("expression", None)
+
+    @property
+    def minmax_zoom(self) -> list[int] | None:
+        return self.properties.get("minmax_zoom")
+
+    @minmax_zoom.setter
+    def minmax_zoom(self, v: list[int] | None) -> None:
+        if v is not None:
+            self.properties["minmax_zoom"] = v
+        else:
+            self.properties.pop("minmax_zoom", None)
+
+    def apply(
+        self,
+        assets: list[str],
+        title: str | None = None,
+        rescale: list[list[float]] | None = None,
+        nodata: float | str | None = None,
+        colormap_name: str | None = None,
+        colormap: dict[str, Any] | None = None,
+        color_formula: str | None = None,
+        resampling: str | None = None,
+        expression: str | None = None,
+        minmax_zoom: list[int] | None = None,
+    ) -> None:
+        self.assets = assets
+        self.title = title
+        self.rescale = rescale
+        self.nodata = nodata
+        self.colormap_name = colormap_name
+        self.colormap = colormap
+        self.color_formula = color_formula
+        self.resampling = resampling
+        self.expression = expression
+        self.minmax_zoom = minmax_zoom
+
+    @classmethod
+    def create(
+        cls,
+        assets: list[str],
+        title: str | None = None,
+        rescale: list[list[float]] | None = None,
+        nodata: float | str | None = None,
+        colormap_name: str | None = None,
+        colormap: dict[str, Any] | None = None,
+        color_formula: str | None = None,
+        resampling: str | None = None,
+        expression: str | None = None,
+        minmax_zoom: list[int] | None = None,
+    ) -> Render:
+        c = cls({})
+        c.apply(
+            assets=assets,
+            title=title,
+            rescale=rescale,
+            nodata=nodata,
+            colormap_name=colormap_name,
+            colormap=colormap,
+            color_formula=color_formula,
+            resampling=resampling,
+            expression=expression,
+            minmax_zoom=minmax_zoom,
+        )
+        return c
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.properties
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Render):
+            raise NotImplementedError
+        return self.properties == other.properties
+
+    def __repr__(self) -> str:
+        props = " ".join(
+            [
+                f"{key}={value}"
+                for key, value in self.properties.items()
+                if value is not None
+            ]
+        )
+        return f"<Render {props}"
+
+
+class RenderExtension(
+    Generic[T],
+    PropertiesExtension,
+    ExtensionManagementMixin[pystac.Item | pystac.Collection],
+):
+    name: Literal["render"] = "render"
+
+    def apply(
+        self,
+        renders: dict[str, Render],
+    ) -> None:
+        self.renders = renders
+
+    @property
+    def renders(self) -> dict[str, Render]:
+        return get_required(
+            self._get_property(RENDERS_PROP, dict[str, Render]), self, RENDERS_PROP
+        )
+
+    @renders.setter
+    def renders(self, v: dict[str, Render]) -> None:
+        self._set_property(
+            RENDERS_PROP,
+            map_opt(lambda renders: {k: r.to_dict() for k, r in renders.items()}, v),
+            pop_if_none=False,
+        )
+
+    @classmethod
+    def get_schema_uri(cls) -> str:
+        return SCHEMA_URI_PATTERN.format(version=DEFAULT_VERSION)
+
+    @classmethod
+    def ext(cls, obj: T, add_if_missing: bool = False) -> RenderExtension[T]:
+        if isinstance(obj, pystac.Collection):
+            cls.ensure_has_extension(obj, add_if_missing)
+        if isinstance(obj, pystac.Item):
+            cls.ensure_has_extension(obj, add_if_missing)
+            return ItemRenderExtension(obj)
+        else:
+            raise pystac.ExtensionTypeError(
+                f"RenderExtension does not apply to type '{type(obj).__name__}"
+            )
+
+
+class CollectionRenderExtension(RenderExtension[pystac.Collection]):
+    def __init__(self, collection: pystac.Collection):
+        self.collection = collection
+        self.properties = collection.extra_fields
+
+    def __repr__(self) -> str:
+        return f"<CollectionRenderExtension Collection id={self.collection.id}>"
+
+
+class ItemRenderExtension(RenderExtension[pystac.Item]):
+    def __init__(self, item: pystac.Item):
+        self.item = item
+        self.properties = item.properties
+
+    def __repr__(self) -> str:
+        return f"<ItemRenderExtension Item id={self.item.id}>"
+
+
+class RenderExtensionHooks(ExtensionHooks):
+    schema_uri: str = SCHEMA_URI_PATTERN.format(version=DEFAULT_VERSION)
+    stac_object_types = {pystac.STACObjectType.COLLECTION, pystac.STACObjectType.ITEM}

tests/data-files/item/sample-item-asset-properties.json

@@ -74,6 +74,7 @@
       "start_datetime": "2017-05-01T13:22:30.040Z",
       "end_datetime": "2017-05-02T13:22:30.040Z",
       "license": "CC-BY-4.0",
+      "keywords": ["keyword_a"],
       "roles": ["a_role"],
       "providers": [
         {

tests/test_common_metadata.py

@@ -541,6 +541,28 @@ def test_updated(self) -> None:
             analytic.to_dict()["updated"], utils.datetime_to_str(set_value)
         )
 
+    def test_keywords(self) -> None:
+        item = self.item.clone()
+        cm = item.common_metadata
+        analytic = item.assets["analytic"]
+        analytic_cm = CommonMetadata(analytic)
+        thumbnail = item.assets["thumbnail"]
+        thumbnail_cm = CommonMetadata(thumbnail)
+
+        item_value = cm.keywords
+        a2_known_value = ["keyword_a"]
+
+        # Get
+        self.assertNotEqual(thumbnail_cm.keywords, item_value)
+        self.assertEqual(thumbnail_cm.keywords, a2_known_value)
+
+        # Set
+        set_value = ["keyword_b"]
+        analytic_cm.keywords = set_value
+
+        self.assertEqual(analytic_cm.keywords, set_value)
+        self.assertEqual(analytic.to_dict()["keywords"], set_value)
+
     def test_roles(self) -> None:
         item = self.item.clone()
         cm = item.common_metadata