Merge branch 'main' into 1376-move-keywords

Author: gadomski

CHANGELOG.md

@@ -14,6 +14,7 @@
 - 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
 
@@ -23,6 +24,7 @@
 - Add example of custom `StacIO` for Azure Blob Storage to docs ([#1372](https://github.com/stac-utils/pystac/pull/1372))
 - Noted that collection links can be used in non-item objects in STAC v1.1.0 ([#1393](https://github.com/stac-utils/pystac/pull/1393))
 - Move test, docs, and bench requirements out of pyproject.toml ([#1407](https://github.com/stac-utils/pystac/pull/1407))
+- Clarify inclusive datetime ranges, update default license, and ensure description is not empty ([#1445](https://github.com/stac-utils/pystac/pull/1445))
 
 ### Fixed
 

pystac/collection.py

@@ -461,9 +461,10 @@ class Collection(Catalog, Assets):
             be one of the values in :class`~pystac.CatalogType`.
         license :  Collection's license(s) as a
             `SPDX License identifier <https://spdx.org/licenses/>`_,
-            `various`, or `proprietary`. If collection includes
-            data with multiple different licenses, use `various` and add a link for
-            each. Defaults to 'proprietary'.
+            or `other`. If collection includes data with multiple
+            different licenses, use `other` and add a link for
+            each. The licenses `various` and `proprietary` are deprecated.
+            Defaults to 'other'.
         keywords : Optional list of keywords describing the collection.
         providers : Optional list of providers of this Collection.
         summaries : An optional map of property summaries,
@@ -528,7 +529,7 @@ def __init__(
         href: str | None = None,
         extra_fields: dict[str, Any] | None = None,
         catalog_type: CatalogType | None = None,
-        license: str = "proprietary",
+        license: str = "other",
         keywords: list[str] | None = None,
         providers: list[Provider] | None = None,
         summaries: Summaries | None = None,

pystac/common_metadata.py

@@ -80,12 +80,18 @@ def description(self) -> str | None:
 
     @description.setter
     def description(self, v: str | None) -> None:
+        if v == "":
+            raise ValueError("description cannot be an empty string")
         self._set_field("description", v)
 
     # Date and Time Range
     @property
     def start_datetime(self) -> datetime | None:
-        """Get or set the object's start_datetime."""
+        """Get or set the object's start_datetime.
+
+        Note:
+            ``start_datetime`` is an inclusive datetime.
+        """
         return utils.map_opt(
             utils.str_to_datetime, self._get_field("start_datetime", str)
         )
@@ -96,7 +102,11 @@ def start_datetime(self, v: datetime | None) -> None:
 
     @property
     def end_datetime(self) -> datetime | None:
-        """Get or set the item's end_datetime."""
+        """Get or set the item's end_datetime.
+
+        Note:
+            ``end_datetime`` is an inclusive datetime.
+        """
         return utils.map_opt(
             utils.str_to_datetime, self._get_field("end_datetime", str)
         )
@@ -108,7 +118,15 @@ def end_datetime(self, v: datetime | None) -> None:
     # License
     @property
     def license(self) -> str | None:
-        """Get or set the current license."""
+        """Get or set the current license. License should be provided
+        as a `SPDX License identifier <https://spdx.org/licenses/>`_,
+        or `other`. If object includes data with multiple
+        different licenses, use `other` and add a link for
+        each.
+
+        Note:
+            The licenses `various` and `proprietary` are deprecated.
+        """
         return self._get_field("license", str)
 
     @license.setter
@@ -222,3 +240,12 @@ def keywords(self) -> list[str] | None:
     @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."""
+        return self._get_field("roles", list[str])
+
+    @roles.setter
+    def roles(self, v: list[str] | None) -> None:
+        self._set_field("roles", v)

pystac/item.py

@@ -51,10 +51,10 @@ class Item(STACObject, Assets):
         datetime : datetime associated with this item. If None,
             a start_datetime and end_datetime must be supplied.
         properties : A dictionary of additional metadata for the item.
-        start_datetime : Optional start datetime, part of common metadata. This value
-            will override any `start_datetime` key in properties.
-        end_datetime : Optional end datetime, part of common metadata. This value
-            will override any `end_datetime` key in properties.
+        start_datetime : Optional inclusive start datetime, part of common metadata.
+            This value will override any `start_datetime` key in properties.
+        end_datetime : Optional inclusive end datetime, part of common metadata.
+            This value will override any `end_datetime` key in properties.
         stac_extensions : Optional list of extensions the Item implements.
         href : Optional HREF for this item, which be set as the item's
             self link's HREF.

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

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

tests/test_common_metadata.py

@@ -176,6 +176,8 @@ def test_common_metadata_basics(self) -> None:
         x.common_metadata.description = example_description
         self.assertEqual(x.common_metadata.description, example_description)
         self.assertEqual(x.properties["description"], example_description)
+        with self.assertRaises(ValueError):
+            x.common_metadata.description = ""
 
         # License
         license = "PDDL-1.0"
@@ -546,7 +548,7 @@ def test_keywords(self) -> None:
         analytic_cm = CommonMetadata(analytic)
         thumbnail = item.assets["thumbnail"]
         thumbnail_cm = CommonMetadata(thumbnail)
-
+        
         item_value = cm.keywords
         a2_known_value = ["keyword_a"]
 
@@ -560,3 +562,25 @@ def test_keywords(self) -> None:
 
         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
+        analytic = item.assets["analytic"]
+        analytic_cm = CommonMetadata(analytic)
+        thumbnail = item.assets["thumbnail"]
+        thumbnail_cm = CommonMetadata(thumbnail)
+
+        item_value = cm.roles
+        a2_known_value = ["a_role"]
+
+        # Get
+        self.assertNotEqual(thumbnail_cm.roles, item_value)
+        self.assertEqual(thumbnail_cm.roles, a2_known_value)
+
+        # Set
+        set_value = ["another_role"]
+        analytic_cm.roles = set_value
+
+        self.assertEqual(analytic_cm.roles, set_value)
+        self.assertEqual(analytic.to_dict()["roles"], set_value)