Update File Info Extension to v2.0.0

Author: duckontheweb

pystac/extensions/file.py

@@ -3,54 +3,91 @@
 https://github.com/stac-extensions/file
 """
 
-import enum
+from enum import Enum
 from typing import Any, Dict, Generic, List, Optional, Set, TypeVar, cast
 
 import pystac
-from pystac.extensions.base import (
-    ExtensionManagementMixin,
-    PropertiesExtension,
-    SummariesExtension,
-)
+from pystac.extensions.base import ExtensionManagementMixin, PropertiesExtension
 from pystac.extensions.hooks import ExtensionHooks
 from pystac.serialization.identify import (
     OldExtensionShortIDs,
     STACJSONDescription,
     STACVersionID,
 )
-from pystac.utils import map_opt
+from pystac.utils import get_required
 
 T = TypeVar("T", pystac.Item, pystac.Asset)
 
-SCHEMA_URI = "https://stac-extensions.github.io/file/v1.0.0/schema.json"
+SCHEMA_URI = "https://stac-extensions.github.io/file/v2.0.0/schema.json"
 
 PREFIX = "file:"
-DATA_TYPE_PROP = PREFIX + "data_type"
-SIZE_PROP = PREFIX + "size"
-NODATA_PROP = PREFIX + "nodata"
+BYTE_ORDER_PROP = PREFIX + "byte_order"
 CHECKSUM_PROP = PREFIX + "checksum"
+HEADER_SIZE_PROP = PREFIX + "header_size"
+SIZE_PROP = PREFIX + "size"
+VALUES_PROP = PREFIX + "values"
+
 
+class ByteOrder(str, Enum):
+    """List of allows values for the ``"file:byte_order"`` field defined by the
+    :stac-ext:`File Info Extension <file>`."""
 
-class FileDataType(str, enum.Enum):
     def __str__(self) -> str:
         return str(self.value)
 
-    INT8 = "int8"
-    INT16 = "int16"
-    INT32 = "int32"
-    INT64 = "int64"
-    UINT8 = "uint8"
-    UINT16 = "uint16"
-    UINT32 = "uint32"
-    UINT64 = "uint64"
-    FLOAT16 = "float16"
-    FLOAT32 = "float32"
-    FLOAT64 = "float64"
-    CINT16 = "cint16"
-    CINT32 = "cint32"
-    CFLOAT32 = "cfloat32"
-    CFLOAT64 = "cfloat64"
-    OTHER = "other"
+    LITTLE_ENDIAN = "little-endian"
+    BIG_ENDIAN = "big-endian"
+
+
+class MappingObject:
+    """Represents a value map used by assets that are used as classification layers, and
+    give details about the values in the asset and their meanings."""
+
+    properties: Dict[str, Any]
+
+    def __init__(self, properties: Dict[str, Any]) -> None:
+        self.properties = properties
+
+    def apply(self, values: List[Any], summary: str) -> None:
+        """Sets the properties for this :class:`~MappingObject` instance.
+
+        Args:
+            values : The value(s) in the file. At least one array element is required.
+            summary : A short description of the value(s).
+        """
+        self.values = values
+        self.summary = summary
+
+    @classmethod
+    def create(cls, values: List[Any], summary: str) -> "MappingObject":
+        """Creates a new :class:`~MapptingObject` instance.
+
+        Args:
+            values : The value(s) in the file. At least one array element is required.
+            summary : A short description of the value(s).
+        """
+        m = cls({})
+        m.apply(values=values, summary=summary)
+        return m
+
+    @property
+    def values(self) -> List[Any]:
+        """Gets or sets the list of value(s) in the file. At least one array element is
+        required."""
+        return get_required(self.properties["values"], self, "values")
+
+    @values.setter
+    def values(self, v: List[Any]) -> None:
+        self.properties["values"] = v
+
+    @property
+    def summary(self) -> str:
+        """Gets or sets the short description of the value(s)."""
+        return get_required(self.properties["summary"], self, "summary")
+
+    @summary.setter
+    def summary(self, v: str) -> None:
+        self.properties["summary"] = v
 
 
 class FileExtension(
@@ -73,62 +110,81 @@ class FileExtension(
 
     def apply(
         self,
-        data_type: Optional[FileDataType] = None,
-        size: Optional[int] = None,
-        nodata: Optional[List[Any]] = None,
+        byte_order: Optional[ByteOrder] = None,
         checksum: Optional[str] = None,
+        header_size: Optional[int] = None,
+        size: Optional[int] = None,
+        values: Optional[List[MappingObject]] = None,
     ) -> None:
         """Applies file extension properties to the extended Item.
 
         Args:
-            data_type : The data type of the file.
-            size : size of the file in bytes.
-            nodata : Value(s) for no-data.
-            checksum : Multihash for the corresponding file,
+            byte_order : Optional byte order of integer values in the file. One of
+                ``"big-endian"`` or ``"little-endian"``.
+            checksum : Optional multihash for the corresponding file,
                 encoded as hexadecimal (base 16) string with lowercase letters.
+            header_size : Optional header size of the file, in bytes.
+            size : Optional size of the file, in bytes.
+            values : Optional list of :class:`~MappingObject` instances that lists the
+                values that are in the file and describe their meaning. See the
+                :stac-ext:`Mapping Object <file#mapping-object>` docs for an example.
+                If given, at least one array element is required.
         """
-        self.data_type = data_type
-        self.size = size
-        self.nodata = nodata
+        self.byte_order = byte_order
         self.checksum = checksum
+        self.header_size = header_size
+        self.size = size
+        self.values = values
+
+    @property
+    def byte_order(self) -> Optional[ByteOrder]:
+        """Gets or sets the byte order of integer values in the file. One of big-endian
+        or little-endian."""
+        return self._get_property(BYTE_ORDER_PROP, ByteOrder)
+
+    @byte_order.setter
+    def byte_order(self, v: Optional[ByteOrder]) -> None:
+        self._set_property(BYTE_ORDER_PROP, v)
 
     @property
-    def data_type(self) -> Optional[FileDataType]:
-        """Get or sets the data_type of the file."""
-        return map_opt(
-            lambda s: FileDataType(s), self._get_property(DATA_TYPE_PROP, str)
-        )
+    def checksum(self) -> Optional[str]:
+        """Get or sets the multihash for the corresponding file, encoded as hexadecimal
+        (base 16) string with lowercase letters."""
+        return self._get_property(CHECKSUM_PROP, str)
+
+    @checksum.setter
+    def checksum(self, v: Optional[str]) -> None:
+        self._set_property(CHECKSUM_PROP, v)
+
+    @property
+    def header_size(self) -> Optional[int]:
+        """Get or sets the header size of the file, in bytes."""
+        return self._get_property(HEADER_SIZE_PROP, int)
 
-    @data_type.setter
-    def data_type(self, v: Optional[FileDataType]) -> None:
-        self._set_property(DATA_TYPE_PROP, str(v))
+    @header_size.setter
+    def header_size(self, v: Optional[int]) -> None:
+        self._set_property(HEADER_SIZE_PROP, v)
 
     @property
     def size(self) -> Optional[int]:
-        """Get or sets the size in bytes of the file."""
+        """Get or sets the size of the file, in bytes."""
         return self._get_property(SIZE_PROP, int)
 
     @size.setter
     def size(self, v: Optional[int]) -> None:
         self._set_property(SIZE_PROP, v)
 
     @property
-    def nodata(self) -> Optional[List[Any]]:
-        """Get or sets the no data values."""
-        return self._get_property(NODATA_PROP, List[Any])
+    def values(self) -> Optional[List[MappingObject]]:
+        """Get or sets the list of :class:`~MappingObject` instances that lists the
+        values that are in the file and describe their meaning. See the
+        :stac-ext:`Mapping Object <file#mapping-object>` docs for an example. If given,
+        at least one array element is required."""
+        return self._get_property(VALUES_PROP, List[MappingObject])
 
-    @nodata.setter
-    def nodata(self, v: Optional[List[Any]]) -> None:
-        self._set_property(NODATA_PROP, v)
-
-    @property
-    def checksum(self) -> Optional[str]:
-        """Get or sets the checksum"""
-        return self._get_property(CHECKSUM_PROP, str)
-
-    @checksum.setter
-    def checksum(self, v: Optional[str]) -> None:
-        self._set_property(CHECKSUM_PROP, v)
+    @values.setter
+    def values(self, v: Optional[List[MappingObject]]) -> None:
+        self._set_property(VALUES_PROP, v)
 
     @classmethod
     def get_schema_uri(cls) -> str:
@@ -155,10 +211,6 @@ def ext(obj: T) -> "FileExtension[T]":
                 f"File extension does not apply to type {type(obj)}"
             )
 
-    @staticmethod
-    def summaries(obj: pystac.Collection) -> "SummariesFileExtension":
-        return SummariesFileExtension(obj)
-
 
 class ItemFileExtension(FileExtension[pystac.Item]):
     """A concrete implementation of :class:`FileExtension` on an :class:`~pystac.Item`
@@ -196,39 +248,6 @@ def __repr__(self) -> str:
         return "<AssetFileExtension Asset href={}>".format(self.asset_href)
 
 
-class SummariesFileExtension(SummariesExtension):
-    @property
-    def data_type(self) -> Optional[List[FileDataType]]:
-        """Get or sets the summary of data_type values for this Collection."""
-
-        return map_opt(
-            lambda x: [FileDataType(t) for t in x],
-            self.summaries.get_list(DATA_TYPE_PROP),
-        )
-
-    @data_type.setter
-    def data_type(self, v: Optional[List[FileDataType]]) -> None:
-        self._set_summary(DATA_TYPE_PROP, map_opt(lambda x: [str(t) for t in x], v))
-
-    @property
-    def size(self) -> Optional[pystac.RangeSummary[int]]:
-        """Get or sets the summary of size values for this Collection."""
-        return self.summaries.get_range(SIZE_PROP)
-
-    @size.setter
-    def size(self, v: Optional[pystac.RangeSummary[int]]) -> None:
-        self._set_summary(SIZE_PROP, v)
-
-    @property
-    def nodata(self) -> Optional[List[Any]]:
-        """Get or sets the summary of nodata values for this Collection."""
-        return self.summaries.get_list(NODATA_PROP)
-
-    @nodata.setter
-    def nodata(self, v: Optional[List[Any]]) -> None:
-        self._set_summary(NODATA_PROP, v)
-
-
 class FileExtensionHooks(ExtensionHooks):
     schema_uri: str = SCHEMA_URI
     prev_extension_ids: Set[str] = set(["file"])

tests/extensions/test_file.py

@@ -3,7 +3,7 @@
 
 import pystac
 from tests.utils import TestCases, assert_to_from_dict
-from pystac.extensions.file import FileExtension, FileDataType
+from pystac.extensions.file import FileExtension
 
 
 class FileTest(unittest.TestCase):
@@ -50,32 +50,6 @@ def test_asset_checksum(self) -> None:
         self.assertEqual(new_checksum, FileExtension.ext(asset).checksum)
         item.validate()
 
-    def test_asset_data_type(self) -> None:
-        item = pystac.Item.from_file(self.FILE_EXAMPLE_URI)
-        asset = item.assets["thumbnail"]
-
-        # Get
-        self.assertEqual(FileDataType.UINT8, FileExtension.ext(asset).data_type)
-
-        # Set
-        new_data_type = FileDataType.UINT16
-        FileExtension.ext(asset).data_type = new_data_type
-        self.assertEqual(new_data_type, FileExtension.ext(asset).data_type)
-        item.validate()
-
-    def test_asset_nodata(self) -> None:
-        item = pystac.Item.from_file(self.FILE_EXAMPLE_URI)
-        asset = item.assets["thumbnail"]
-
-        # Get
-        self.assertEqual([], FileExtension.ext(asset).nodata)
-
-        # Set
-        new_nodata = [-1]
-        FileExtension.ext(asset).nodata = new_nodata
-        self.assertEqual(new_nodata, FileExtension.ext(asset).nodata)
-        item.validate()
-
     def test_migrates_old_checksum(self) -> None:
         example_path = TestCases.get_path(
             "data-files/examples/1.0.0-beta.2/"