Implement classification v2.0.0 (#1359)

* feat: implement classification v2.0.0

* Update pystac/extensions/classification.py

Co-authored-by: Julia Signell <[email protected]>

* fix: don't change arg order

* fix: allow None when returning description

* fix(docs): docstring for nodata didn't make sense

* fix: check for `None` name

---------

Co-authored-by: Julia Signell <[email protected]>

Author: gadomski

CHANGELOG.md

@@ -4,8 +4,9 @@
 
 ### Changed
 
-- Allow object ID as input for getting APILayoutStrategy hrefs and add `items`, `collections`, `search`, `conformance`, `service_desc` and `service_doc` href methods. ([#1335](https://github.com/stac-utils/pystac/pull/1335))
-- Update docstring of `name` argument to `Classification.apply` and `Classification.create` to agree with extension specification. ([#1356](https://github.com/stac-utils/pystac/pull/1356))
+- Allow object ID as input for getting APILayoutStrategy hrefs and add `items`, `collections`, `search`, `conformance`, `service_desc` and `service_doc` href methods ([#1335](https://github.com/stac-utils/pystac/pull/1335))
+- Updated classification extension to v2.0.0 ([#1359](https://github.com/stac-utils/pystac/pull/1359))
+- Update docstring of `name` argument to `Classification.apply` and `Classification.create` to agree with extension specification ([#1356](https://github.com/stac-utils/pystac/pull/1356))
 
 ### Fixed
 

pystac/extensions/classification.py

@@ -32,8 +32,8 @@
 SCHEMA_URI_PATTERN: str = (
     "https://stac-extensions.github.io/classification/v{version}/schema.json"
 )
-DEFAULT_VERSION: str = "1.1.0"
-SUPPORTED_VERSIONS: list[str] = ["1.1.0", "1.0.0"]
+DEFAULT_VERSION: str = "2.0.0"
+SUPPORTED_VERSIONS: list[str] = ["2.0.0", "1.1.0", "1.0.0"]
 
 # Field names
 PREFIX: str = "classification:"
@@ -58,9 +58,12 @@ def __init__(self, properties: dict[str, Any]) -> None:
     def apply(
         self,
         value: int,
-        description: str,
+        description: str | None = None,
         name: str | None = None,
         color_hint: str | None = None,
+        nodata: bool | None = None,
+        percentage: float | None = None,
+        count: int | None = None,
     ) -> None:
         """
         Set the properties for a new Classification.
@@ -69,21 +72,29 @@ def apply(
             value: The integer value corresponding to this class
             description: The description of this class
             name: Short name of the class for machine readability. Must consist only
-                of letters, numbers, -, and _ characters.
+                of letters, numbers, -, and _ characters. Required as of v2.0 of
+                this extension.
             color_hint: An optional hexadecimal string-encoded representation of the
                 RGB color that is suggested to represent this class (six hexadecimal
                 characters, all capitalized)
+            nodata: If set to true classifies a value as a no-data value.
+            percentage: The percentage of data values that belong to this class
+                in comparison to all data values, in percent (0-100).
+            count: The number of data values that belong to this class.
         """
         self.value = value
+        # TODO pystac v2.0: make `name` non-optional, move it before
+        # `description` in the arg list, and remove this check
+        if name is None:
+            raise Exception(
+                "As of v2.0.0 of the classification extension, 'name' is required"
+            )
         self.name = name
         self.description = description
         self.color_hint = color_hint
-
-        if color_hint is not None:
-            match = COLOR_HINT_PATTERN.match(color_hint)
-            assert (
-                color_hint is None or match is not None and match.group() == color_hint
-            ), "Must format color hints as '^([0-9A-F]{6})$'"
+        self.nodata = nodata
+        self.percentage = percentage
+        self.count = count
 
         if color_hint is not None:
             match = COLOR_HINT_PATTERN.match(color_hint)
@@ -95,28 +106,39 @@ def apply(
     def create(
         cls,
         value: int,
-        description: str,
+        description: str | None = None,
         name: str | None = None,
         color_hint: str | None = None,
+        nodata: bool | None = None,
+        percentage: float | None = None,
+        count: int | None = None,
     ) -> Classification:
         """
         Create a new Classification.
 
         Args:
             value: The integer value corresponding to this class
-            name: Short name of the class for machine readability. Must consist only
-                of letters, numbers, -, and _ characters.
             description: The optional long-form description of this class
+            name: Short name of the class for machine readability. Must consist only
+                of letters, numbers, -, and _ characters. Required as of v2.0 of
+                this extension.
             color_hint: An optional hexadecimal string-encoded representation of the
                 RGB color that is suggested to represent this class (six hexadecimal
                 characters, all capitalized)
+            nodata: If set to true classifies a value as a no-data value.
+            percentage: The percentage of data values that belong to this class
+                in comparison to all data values, in percent (0-100).
+            count: The number of data values that belong to this class.
         """
         c = cls({})
         c.apply(
             value=value,
             name=name,
             description=description,
             color_hint=color_hint,
+            nodata=nodata,
+            percentage=percentage,
+            count=count,
         )
         return c
 
@@ -134,33 +156,38 @@ def value(self, v: int) -> None:
         self.properties["value"] = v
 
     @property
-    def description(self) -> str:
+    def description(self) -> str | None:
         """Get or set the description of the class
 
         Returns:
             str
         """
-        return get_required(self.properties.get("description"), self, "description")
+        return self.properties.get("description")
 
     @description.setter
-    def description(self, v: str) -> None:
-        self.properties["description"] = v
+    def description(self, v: str | None) -> None:
+        if v is not None:
+            self.properties["description"] = v
+        else:
+            self.properties.pop("description", None)
 
     @property
-    def name(self) -> str | None:
+    def name(self) -> str:
         """Get or set the name of the class
 
         Returns:
             Optional[str]
         """
-        return self.properties.get("name")
+        return get_required(self.properties.get("name"), self, "name")
 
     @name.setter
-    def name(self, v: str | None) -> None:
-        if v is not None:
-            self.properties["name"] = v
-        else:
-            self.properties.pop("name", None)
+    def name(self, v: str) -> None:
+        if v is None:
+            raise Exception(
+                "`name` was converted to a required attribute in classification"
+                " version v2.0, so cannot be set to None"
+            )
+        self.properties["name"] = v
 
     @property
     def color_hint(self) -> str | None:
@@ -185,6 +212,54 @@ def color_hint(self, v: str | None) -> None:
         else:
             self.properties.pop("color_hint", None)
 
+    @property
+    def nodata(self) -> bool | None:
+        """Get or set the nodata value for this class.
+
+        Returns:
+            bool | None
+        """
+        return self.properties.get("nodata")
+
+    @nodata.setter
+    def nodata(self, v: bool | None) -> None:
+        if v is not None:
+            self.properties["nodata"] = v
+        else:
+            self.properties.pop("nodata", None)
+
+    @property
+    def percentage(self) -> float | None:
+        """Get or set the percentage value for this class.
+
+        Returns:
+            Optional[float]
+        """
+        return self.properties.get("percentage")
+
+    @percentage.setter
+    def percentage(self, v: float | None) -> None:
+        if v is not None:
+            self.properties["percentage"] = v
+        else:
+            self.properties.pop("percentage", None)
+
+    @property
+    def count(self) -> int | None:
+        """Get or set the count value for this class.
+
+        Returns:
+            Optional[int]
+        """
+        return self.properties.get("count")
+
+    @count.setter
+    def count(self, v: int | None) -> None:
+        if v is not None:
+            self.properties["count"] = v
+        else:
+            self.properties.pop("count", None)
+
     def to_dict(self) -> dict[str, Any]:
         """Returns the dictionary encoding of this class
 

tests/data-files/classification/collection-item-assets-raster-bands.json

@@ -115,6 +115,6 @@
     "https://stac-extensions.github.io/projection/v1.1.0/schema.json",
     "https://stac-extensions.github.io/eo/v1.1.0/schema.json",
     "https://stac-extensions.github.io/raster/v1.1.0/schema.json",
-    "https://stac-extensions.github.io/classification/v1.1.0/schema.json"
+    "https://stac-extensions.github.io/classification/v2.0.0/schema.json"
   ]
 }