Update and clarify description, license, datetime properties (#1445)

* fix docstrings for license #1377

* clarify datetime range is inclusive #1382

* ensure description is not empty #1381

* pass tests

* test empty description

* update changelog

* Update pystac/collection.py

* Update pystac/common_metadata.py

---------

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

Author: tylanderson

CHANGELOG.md

@@ -23,6 +23,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

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/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"