Merge pull request #513 from duckontheweb/update/timestamps-extension

Update Timestamps Extension

Author: Jon Duckworth

CHANGELOG.md

@@ -10,6 +10,9 @@
 -  `LabelMethod` enum in `pystac.extensions.label` with recommended values for
   `"label:methods"` field ([#484](https://github.com/stac-utils/pystac/pull/484))
 - Label Extension summaries ([#484](https://github.com/stac-utils/pystac/pull/484))
+- Timestamps Extension summaries ([#513](https://github.com/stac-utils/pystac/pull/513))
+- Define equality and `__repr__` of `RangeSummary` instances based on `to_dict`
+  representation ([#513](https://github.com/stac-utils/pystac/pull/513))
 
 ### Changed
 

docs/api.rst

@@ -536,17 +536,29 @@ ItemScientificExtension
 Timestamps Extension
 --------------------
 
-Implements the :stac-ext:`Timestamps Extension <timestamps>`.
+These classes are representations of the :stac-ext:`Timestamps Extension Spec
+<timestamps>`.
 
-TimestampsItemExt
-~~~~~~~~~~~~~~~~~
+TimestampsExtension
+~~~~~~~~~~~~~~~~~~~
 
-**TEMPORARILY REMOVED**
+.. autoclass:: pystac.extensions.timestamps.TimestampsExtension
+   :members:
+   :show-inheritance:
 
-.. .. autoclass:: pystac.extensions.timestamps.TimestampsItemExt
-..    :members:
-..    :undoc-members:
-..    :show-inheritance:
+ItemTimestampsExtension
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: pystac.extensions.timestamps.ItemTimestampsExtension
+   :members:
+   :show-inheritance:
+
+AssetTimestampsExtension
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: pystac.extensions.timestamps.AssetTimestampsExtension
+   :members:
+   :show-inheritance:
 
 SAR Extension
 -------------

pystac/extensions/eo.py

@@ -278,10 +278,11 @@ class EOExtension(
     Generic[T], PropertiesExtension, ExtensionManagementMixin[pystac.Item]
 ):
     """An abstract class that can be used to extend the properties of an
-    :class:`~pystac.Item` or :class:`~pystac.Collection` with properties from the
+    :class:`~pystac.Item` or :class:`~pystac.Asset` with properties from the
     :stac-ext:`Electro-Optical Extension <eo>`. This class is generic over the type of
     STAC Object to be extended (e.g. :class:`~pystac.Item`,
-    :class:`~pystac.Collection`).
+    :class:`~pystac.
+    Asset`).
 
     To create a concrete instance of :class:`EOExtension`, use the
     :meth:`EOExtension.ext` method. For example:

pystac/extensions/timestamps.py

@@ -4,12 +4,14 @@
 """
 
 from datetime import datetime as Datetime
-from typing import Generic, Optional, Set, TypeVar, cast
+from pystac.summaries import RangeSummary
+from typing import Dict, Any, Generic, Iterable, Optional, Set, TypeVar, cast
 
 import pystac
 from pystac.extensions.base import (
     ExtensionManagementMixin,
     PropertiesExtension,
+    SummariesExtension,
 )
 from pystac.extensions.hooks import ExtensionHooks
 from pystac.utils import datetime_to_str, map_opt, str_to_datetime
@@ -26,8 +28,18 @@
 class TimestampsExtension(
     Generic[T], PropertiesExtension, ExtensionManagementMixin[pystac.Item]
 ):
-    """TimestampsItemExt is the extension of an Item in that
-    allows to specify additional timestamps for assets and metadata.
+    """An abstract class that can be used to extend the properties of an
+    :class:`~pystac.Item` or :class:`~pystac.Asset` with properties from the
+    :stac-ext:`Timestamps Extension <timestamps>`. This class is generic over the type
+    of STAC Object to be extended (e.g. :class:`~pystac.Item`, :class:`~pystac.Asset`).
+
+    To create a concrete instance of :class:`TimestampsExtension`, use the
+    :meth:`TimestampsExtension.ext` method. For example:
+
+    .. code-block:: python
+
+       >>> item: pystac.Item = ...
+       >>> ts_ext = TimestampsExtension.ext(item)
     """
 
     def apply(
@@ -52,18 +64,13 @@ def apply(
 
     @property
     def published(self) -> Optional[Datetime]:
-        """Get or sets a datetime objects that represent
-            the date and time that the corresponding data
-            was published the first time.
-
-        'Published'
-        has a different meaning depending on where it is used. If available in
-        the asset properties, it refers to the timestamps valid for the actual data
-        linked to the Asset Object. If it comes from the Item properties, it's
-        referencing to the timestamp valid for the metadata.
-
-        Returns:
-            datetime
+        """Gets or sets a datetime object that represents the date and time that the
+        corresponding data was published the first time.
+
+        'Published' has a different meaning depending on where it is used. If available
+        in the asset properties, it refers to the timestamps valid for the actual data
+        linked to the Asset Object. If it comes from the Item properties, it refers to
+        timestamp valid for the metadata.
         """
         return map_opt(str_to_datetime, self._get_property(PUBLISHED_PROP, str))
 
@@ -73,18 +80,13 @@ def published(self, v: Optional[Datetime]) -> None:
 
     @property
     def expires(self) -> Optional[Datetime]:
-        """Get or sets a datetime objects that represent
-            the date and time the corresponding data
-            expires (is not valid any longer).
-
-        'Unpublished'
-        has a different meaning depending on where it is used. If available in
-        the asset properties, it refers to the timestamps valid for the actual data
-        linked to the Asset Object. If it comes from the Item properties, it's
-        referencing to the timestamp valid for the metadata.
-
-        Returns:
-            datetime
+        """Gets or sets a datetime object that represents the date and time the
+        corresponding data expires (is not valid any longer).
+
+        'Unpublished' has a different meaning depending on where it is used. If
+        available in the asset properties, it refers to the timestamps valid for the
+        actual data linked to the Asset Object. If it comes from the Item properties,
+        it refers to to the timestamp valid for the metadata.
         """
         return map_opt(str_to_datetime, self._get_property(EXPIRES_PROP, str))
 
@@ -94,17 +96,13 @@ def expires(self, v: Optional[Datetime]) -> None:
 
     @property
     def unpublished(self) -> Optional[Datetime]:
-        """Get or sets a datetime objects that represent
-        the Date and time the corresponding data was unpublished.
-
-        'Unpublished'
-        has a different meaning depending on where it is used. If available in
-        the asset properties, it refers to the timestamps valid for the actual data
-        linked to the Asset Object. If it comes from the Item properties, it's
-        referencing to the timestamp valid for the metadata.
+        """Gets or sets a datetime object that represents the date and time the
+        corresponding data was unpublished.
 
-        Returns:
-            datetime
+        'Unpublished' has a different meaning depending on where it is used. If
+        available in the asset properties, it refers to the timestamps valid for the
+        actual data linked to the Asset Object. If it comes from the Item properties,
+        it's referencing to the timestamp valid for the metadata.
         """
         return map_opt(str_to_datetime, self._get_property(UNPUBLISHED_PROP, str))
 
@@ -118,6 +116,16 @@ def get_schema_uri(cls) -> str:
 
     @classmethod
     def ext(cls, obj: T, add_if_missing: bool = False) -> "TimestampsExtension[T]":
+        """Extends the given STAC Object with properties from the :stac-ext:`Timestamps
+        Extension <timestamps>`.
+
+        This extension can be applied to instances of :class:`~pystac.Item` or
+        :class:`~pystac.Asset`.
+
+        Raises:
+
+            pystac.ExtensionTypeError : If an invalid object type is passed.
+        """
         if isinstance(obj, pystac.Item):
             if add_if_missing:
                 cls.add_to(obj)
@@ -133,25 +141,144 @@ def ext(cls, obj: T, add_if_missing: bool = False) -> "TimestampsExtension[T]":
                 f"Timestamps extension does not apply to type '{type(obj).__name__}'"
             )
 
+    @staticmethod
+    def summaries(obj: pystac.Collection) -> "SummariesTimestampsExtension":
+        """Returns the extended summaries object for the given collection."""
+        return SummariesTimestampsExtension(obj)
+
 
 class ItemTimestampsExtension(TimestampsExtension[pystac.Item]):
+    """A concrete implementation of :class:`TimestampsExtension` on an
+    :class:`~pystac.Item` that extends the properties of the Item to include properties
+    defined in the :stac-ext:`Timestamps Extension <timestamps>`.
+
+    This class should generally not be instantiated directly. Instead, call
+    :meth:`TimestampsExtension.ext` on an :class:`~pystac.Item` to extend it.
+    """
+
+    item: pystac.Item
+    """The :class:`~pystac.Item` being extended."""
+
+    properties: Dict[str, Any]
+    """The :class:`~pystac.Item` properties, including extension properties."""
+
     def __init__(self, item: pystac.Item):
         self.item = item
         self.properties = item.properties
 
     def __repr__(self) -> str:
-        return "<ItemtimestampsExtension Item id={}>".format(self.item.id)
+        return "<ItemTimestampsExtension Item id={}>".format(self.item.id)
 
 
 class AssetTimestampsExtension(TimestampsExtension[pystac.Asset]):
+    """A concrete implementation of :class:`TimestampsExtension` on an
+    :class:`~pystac.Asset` that extends the Asset fields to include properties
+    defined in the :stac-ext:`Timestamps Extension <timestamps>`.
+
+    This class should generally not be instantiated directly. Instead, call
+    :meth:`TimestampsExtension.ext` on an :class:`~pystac.Asset` to extend it.
+    """
+
+    asset_href: str
+    """The ``href`` value of the :class:`~pystac.Asset` being extended."""
+
+    properties: Dict[str, Any]
+    """The :class:`~pystac.Asset` fields, including extension properties."""
+
+    additional_read_properties: Optional[Iterable[Dict[str, Any]]] = None
+    """If present, this will be a list containing 1 dictionary representing the
+    properties of the owning :class:`~pystac.Item`."""
+
     def __init__(self, asset: pystac.Asset):
         self.asset_href = asset.href
         self.properties = asset.properties
         if asset.owner and isinstance(asset.owner, pystac.Item):
             self.additional_read_properties = [asset.owner.properties]
 
     def __repr__(self) -> str:
-        return "<AssettimestampsExtension Asset href={}>".format(self.asset_href)
+        return "<AssetTimestampsExtension Asset href={}>".format(self.asset_href)
+
+
+class SummariesTimestampsExtension(SummariesExtension):
+    """A concrete implementation of :class:`~SummariesExtension` that extends
+    the ``summaries`` field of a :class:`~pystac.Collection` to include properties
+    defined in the :stac-ext:`Timestamps Extension <timestamps>`.
+    """
+
+    @property
+    def published(self) -> Optional[RangeSummary[Datetime]]:
+        """Get or sets the summary of :attr:`TimestampsExtension.published` values
+        for this Collection.
+        """
+
+        return map_opt(
+            lambda s: RangeSummary(
+                str_to_datetime(s.minimum), str_to_datetime(s.maximum)
+            ),
+            self.summaries.get_range(PUBLISHED_PROP),
+        )
+
+    @published.setter
+    def published(self, v: Optional[RangeSummary[Datetime]]) -> None:
+        self._set_summary(
+            PUBLISHED_PROP,
+            map_opt(
+                lambda s: RangeSummary(
+                    datetime_to_str(s.minimum), datetime_to_str(s.maximum)
+                ),
+                v,
+            ),
+        )
+
+    @property
+    def expires(self) -> Optional[RangeSummary[Datetime]]:
+        """Get or sets the summary of :attr:`TimestampsExtension.expires` values
+        for this Collection.
+        """
+
+        return map_opt(
+            lambda s: RangeSummary(
+                str_to_datetime(s.minimum), str_to_datetime(s.maximum)
+            ),
+            self.summaries.get_range(EXPIRES_PROP),
+        )
+
+    @expires.setter
+    def expires(self, v: Optional[RangeSummary[Datetime]]) -> None:
+        self._set_summary(
+            EXPIRES_PROP,
+            map_opt(
+                lambda s: RangeSummary(
+                    datetime_to_str(s.minimum), datetime_to_str(s.maximum)
+                ),
+                v,
+            ),
+        )
+
+    @property
+    def unpublished(self) -> Optional[RangeSummary[Datetime]]:
+        """Get or sets the summary of :attr:`TimestampsExtension.unpublished` values
+        for this Collection.
+        """
+
+        return map_opt(
+            lambda s: RangeSummary(
+                str_to_datetime(s.minimum), str_to_datetime(s.maximum)
+            ),
+            self.summaries.get_range(UNPUBLISHED_PROP),
+        )
+
+    @unpublished.setter
+    def unpublished(self, v: Optional[RangeSummary[Datetime]]) -> None:
+        self._set_summary(
+            UNPUBLISHED_PROP,
+            map_opt(
+                lambda s: RangeSummary(
+                    datetime_to_str(s.minimum), datetime_to_str(s.maximum)
+                ),
+                v,
+            ),
+        )
 
 
 class TimestampsExtensionHooks(ExtensionHooks):

pystac/summaries.py

@@ -59,6 +59,15 @@ def from_dict(cls, d: Dict[str, Any]) -> "RangeSummary[T]":
         maximum: T = get_required(d.get("maximum"), "RangeSummary", "maximum")
         return cls(minimum=minimum, maximum=maximum)
 
+    def __eq__(self, o: object) -> bool:
+        if not isinstance(o, RangeSummary):
+            return NotImplemented
+
+        return self.to_dict() == o.to_dict()
+
+    def __repr__(self) -> str:
+        return self.to_dict().__repr__()
+
 
 FIELDS_JSON_URL = (
     "https://cdn.jsdelivr.net/npm/@radiantearth/stac-fields/fields-normalized.json"