Source code for pystac.collection

from __future__ import annotations

import warnings
from collections.abc import Iterable
from copy import deepcopy
from datetime import datetime, timezone
from typing import (
    TYPE_CHECKING,
    Any,
    Optional,
    TypeVar,
    Union,
    cast,
)

from dateutil import tz

import pystac
from pystac import CatalogType, STACObjectType
from pystac.asset import Asset, Assets
from pystac.catalog import Catalog
from pystac.errors import DeprecatedWarning, ExtensionNotImplemented, STACTypeError
from pystac.layout import HrefLayoutStrategy
from pystac.link import Link
from pystac.provider import Provider
from pystac.serialization import (
    identify_stac_object,
    identify_stac_object_type,
    migrate_to_latest,
)
from pystac.summaries import Summaries
from pystac.utils import (
    datetime_to_str,
    str_to_datetime,
)

if TYPE_CHECKING:
    from pystac.extensions.ext import CollectionExt
    from pystac.item import Item

C = TypeVar("C", bound="Collection")

Bboxes = list[list[Union[float, int]]]
TemporalIntervals = Union[list[list[datetime]], list[list[Optional[datetime]]]]
TemporalIntervalsLike = Union[
    TemporalIntervals, list[datetime], list[Optional[datetime]]
]


[docs] class SpatialExtent: """Describes the spatial extent of a Collection. Args: bboxes : A list of bboxes that represent the spatial extent of the collection. Each bbox can be 2D or 3D. The length of the bbox array must be 2*n where n is the number of dimensions. For example, a 2D Collection with only one bbox would be [[xmin, ymin, xmax, ymax]] extra_fields : Dictionary containing additional top-level fields defined on the Spatial Extent object. """ bboxes: Bboxes """A list of bboxes that represent the spatial extent of the collection. Each bbox can be 2D or 3D. The length of the bbox array must be 2*n where n is the number of dimensions. For example, a 2D Collection with only one bbox would be [[xmin, ymin, xmax, ymax]]""" extra_fields: dict[str, Any] """Dictionary containing additional top-level fields defined on the Spatial Extent object.""" def __init__( self, bboxes: Bboxes | list[float | int], extra_fields: dict[str, Any] | None = None, ) -> None: if not isinstance(bboxes, list): raise TypeError("bboxes must be a list") # A common mistake is to pass in a single bbox instead of a list of bboxes. # Account for this by transforming the input in that case. if isinstance(bboxes[0], (float, int)): self.bboxes = [cast(list[Union[float, int]], bboxes)] else: self.bboxes = cast(Bboxes, bboxes) self.extra_fields = extra_fields or {}
[docs] def to_dict(self) -> dict[str, Any]: """Returns this spatial extent as a dictionary. Returns: dict: A serialization of the SpatialExtent. """ d = {"bbox": self.bboxes, **self.extra_fields} return d
[docs] def clone(self) -> SpatialExtent: """Clones this object. Returns: SpatialExtent: The clone of this object. """ cls = self.__class__ return cls( bboxes=deepcopy(self.bboxes), extra_fields=deepcopy(self.extra_fields) )
[docs] @staticmethod def from_dict(d: dict[str, Any]) -> SpatialExtent: """Constructs a SpatialExtent from a dict. Returns: SpatialExtent: The SpatialExtent deserialized from the JSON dict. """ return SpatialExtent( bboxes=d["bbox"], extra_fields={k: v for k, v in d.items() if k != "bbox"} )
[docs] @staticmethod def from_coordinates( coordinates: list[Any], extra_fields: dict[str, Any] | None = None ) -> SpatialExtent: """Constructs a SpatialExtent from a set of coordinates. This method will only produce a single bbox that covers all points in the coordinate set. Args: coordinates : Coordinates to derive the bbox from. extra_fields : Dictionary containing additional top-level fields defined on the SpatialExtent object. Returns: SpatialExtent: A SpatialExtent with a single bbox that covers the given coordinates. """ def process_coords( coord_lists: list[Any], xmin: float | None = None, ymin: float | None = None, xmax: float | None = None, ymax: float | None = None, ) -> tuple[float | None, float | None, float | None, float | None]: for coord in coord_lists: if isinstance(coord[0], list): xmin, ymin, xmax, ymax = process_coords( coord, xmin, ymin, xmax, ymax ) else: x, y = coord if xmin is None or x < xmin: xmin = x elif xmax is None or xmax < x: xmax = x if ymin is None or y < ymin: ymin = y elif ymax is None or ymax < y: ymax = y return xmin, ymin, xmax, ymax xmin, ymin, xmax, ymax = process_coords(coordinates) if xmin is None or ymin is None or xmax is None or ymax is None: raise ValueError( f"Could not determine bounds from coordinate sequence {coordinates}" ) return SpatialExtent( bboxes=[[xmin, ymin, xmax, ymax]], extra_fields=extra_fields )
[docs] class TemporalExtent: """Describes the temporal extent of a Collection. Args: intervals : A list of two datetimes wrapped in a list, representing the temporal extent of a Collection. Open date ranges are supported by setting either the start (the first element of the interval) or the end (the second element of the interval) to None. extra_fields : Dictionary containing additional top-level fields defined on the Temporal Extent object. Note: Datetimes are required to be in UTC. """ intervals: TemporalIntervals """A list of two datetimes wrapped in a list, representing the temporal extent of a Collection. Open date ranges are represented by either the start (the first element of the interval) or the end (the second element of the interval) being None.""" extra_fields: dict[str, Any] """Dictionary containing additional top-level fields defined on the Temporal Extent object.""" def __init__( self, intervals: TemporalIntervals | list[datetime | None], extra_fields: dict[str, Any] | None = None, ): if not isinstance(intervals, list): raise TypeError("intervals must be a list") # A common mistake is to pass in a single interval instead of a # list of intervals. Account for this by transforming the input # in that case. if isinstance(intervals[0], datetime) or intervals[0] is None: self.intervals = [cast(list[Optional[datetime]], intervals)] else: self.intervals = cast(TemporalIntervals, intervals) self.extra_fields = extra_fields or {}
[docs] def to_dict(self) -> dict[str, Any]: """Returns this temporal extent as a dictionary. Returns: dict: A serialization of the TemporalExtent. """ encoded_intervals: list[list[str | None]] = [] for i in self.intervals: start = None end = None if i[0] is not None: start = datetime_to_str(i[0]) if i[1] is not None: end = datetime_to_str(i[1]) encoded_intervals.append([start, end]) d = {"interval": encoded_intervals, **self.extra_fields} return d
[docs] def clone(self) -> TemporalExtent: """Clones this object. Returns: TemporalExtent: The clone of this object. """ cls = self.__class__ return cls( intervals=deepcopy(self.intervals), extra_fields=deepcopy(self.extra_fields) )
[docs] @staticmethod def from_dict(d: dict[str, Any]) -> TemporalExtent: """Constructs an TemporalExtent from a dict. Returns: TemporalExtent: The TemporalExtent deserialized from the JSON dict. """ parsed_intervals: list[list[datetime | None]] = [] for i in d["interval"]: if isinstance(i, str): # d["interval"] is a list of strings, so we correct the list and # try again # https://github.com/stac-utils/pystac/issues/1221 warnings.warn( "A collection's temporal extent should be a list of lists, but " "is instead a " "list of strings. pystac is fixing this issue and continuing " "deserialization, but note that the source " "collection is invalid STAC.", UserWarning, ) d["interval"] = [d["interval"]] return TemporalExtent.from_dict(d) start = None end = None if i[0]: start = str_to_datetime(i[0]) if i[1]: end = str_to_datetime(i[1]) parsed_intervals.append([start, end]) return TemporalExtent( intervals=parsed_intervals, extra_fields={k: v for k, v in d.items() if k != "interval"}, )
[docs] @staticmethod def from_now() -> TemporalExtent: """Constructs an TemporalExtent with a single open interval that has the start time as the current time. Returns: TemporalExtent: The resulting TemporalExtent. """ return TemporalExtent( intervals=[[datetime.now(timezone.utc).replace(microsecond=0), None]] )
[docs] class Extent: """Describes the spatiotemporal extents of a Collection. Args: spatial : Potential spatial extent covered by the collection. temporal : Potential temporal extent covered by the collection. extra_fields : Dictionary containing additional top-level fields defined on the Extent object. """ spatial: SpatialExtent """Potential spatial extent covered by the collection.""" temporal: TemporalExtent """Potential temporal extent covered by the collection.""" extra_fields: dict[str, Any] """Dictionary containing additional top-level fields defined on the Extent object.""" def __init__( self, spatial: SpatialExtent, temporal: TemporalExtent, extra_fields: dict[str, Any] | None = None, ): self.spatial = spatial self.temporal = temporal self.extra_fields = extra_fields or {}
[docs] def to_dict(self) -> dict[str, Any]: """Returns this extent as a dictionary. Returns: dict: A serialization of the Extent. """ d = { "spatial": self.spatial.to_dict(), "temporal": self.temporal.to_dict(), **self.extra_fields, } return d
[docs] def clone(self) -> Extent: """Clones this object. Returns: Extent: The clone of this extent. """ cls = self.__class__ return cls( spatial=self.spatial.clone(), temporal=self.temporal.clone(), extra_fields=deepcopy(self.extra_fields), )
[docs] @staticmethod def from_dict(d: dict[str, Any]) -> Extent: """Constructs an Extent from a dict. Returns: Extent: The Extent deserialized from the JSON dict. """ return Extent( spatial=SpatialExtent.from_dict(d["spatial"]), temporal=TemporalExtent.from_dict(d["temporal"]), extra_fields={ k: v for k, v in d.items() if k not in {"spatial", "temporal"} }, )
[docs] @staticmethod def from_items( items: Iterable[Item], extra_fields: dict[str, Any] | None = None ) -> Extent: """Create an Extent based on the datetimes and bboxes of a list of items. Args: items : A list of items to derive the extent from. extra_fields : Optional dictionary containing additional top-level fields defined on the Extent object. Returns: Extent: An Extent that spatially and temporally covers all of the given items. """ bounds_values: list[list[float]] = [ [float("inf")], [float("inf")], [float("-inf")], [float("-inf")], ] datetimes: list[datetime] = [] starts: list[datetime] = [] ends: list[datetime] = [] for item in items: if item.bbox is not None: for i in range(0, 4): bounds_values[i].append(item.bbox[i]) if item.datetime is not None: datetimes.append(item.datetime) if item.common_metadata.start_datetime is not None: starts.append(item.common_metadata.start_datetime) if item.common_metadata.end_datetime is not None: ends.append(item.common_metadata.end_datetime) if not any(datetimes + starts): start_timestamp = None else: start_timestamp = min( [ dt if dt.tzinfo else dt.replace(tzinfo=tz.UTC) for dt in datetimes + starts ] ) if not any(datetimes + ends): end_timestamp = None else: end_timestamp = max( [ dt if dt.tzinfo else dt.replace(tzinfo=tz.UTC) for dt in datetimes + ends ] ) spatial = SpatialExtent( [ [ min(bounds_values[0]), min(bounds_values[1]), max(bounds_values[2]), max(bounds_values[3]), ] ] ) temporal = TemporalExtent([[start_timestamp, end_timestamp]]) return Extent(spatial=spatial, temporal=temporal, extra_fields=extra_fields)
[docs] class Collection(Catalog, Assets): """A Collection extends the Catalog spec with additional metadata that helps enable discovery. Args: id : Identifier for the collection. Must be unique within the STAC. description : Detailed multi-line description to fully explain the collection. `CommonMark 0.29 syntax <https://commonmark.org/>`_ MAY be used for rich text representation. extent : Spatial and temporal extents that describe the bounds of all items contained within this Collection. title : Optional short descriptive one-line title for the collection. stac_extensions : Optional list of extensions the Collection implements. href : Optional HREF for this collection, which be set as the collection's self link's HREF. catalog_type : Optional catalog type for this catalog. Must 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'. keywords : Optional list of keywords describing the collection. providers : Optional list of providers of this Collection. summaries : An optional map of property summaries, either a set of values or statistics such as a range. extra_fields : Extra fields that are part of the top-level JSON properties of the Collection. assets : A dictionary mapping string keys to :class:`~pystac.Asset` objects. All :class:`~pystac.Asset` values in the dictionary will have their :attr:`~pystac.Asset.owner` attribute set to the created Collection. strategy : The layout strategy to use for setting the HREFs of the catalog child objections and items. If not provided, it will default to strategy of the parent and fallback to :class:`~pystac.layout.BestPracticesLayoutStrategy`. """ description: str """Detailed multi-line description to fully explain the collection.""" extent: Extent """Spatial and temporal extents that describe the bounds of all items contained within this Collection.""" id: str """Identifier for the collection.""" stac_extensions: list[str] """List of extensions the Collection implements.""" title: str | None """Optional short descriptive one-line title for the collection.""" keywords: list[str] | None """Optional list of keywords describing the collection.""" providers: list[Provider] | None """Optional list of providers of this Collection.""" summaries: Summaries """A map of property summaries, either a set of values or statistics such as a range.""" links: list[Link] """A list of :class:`~pystac.Link` objects representing all links associated with this Collection.""" extra_fields: dict[str, Any] """Extra fields that are part of the top-level JSON properties of the Collection.""" STAC_OBJECT_TYPE = STACObjectType.COLLECTION DEFAULT_FILE_NAME = "collection.json" """Default file name that will be given to this STAC object in a canonical format.""" def __init__( self, id: str, description: str, extent: Extent, title: str | None = None, stac_extensions: list[str] | None = None, href: str | None = None, extra_fields: dict[str, Any] | None = None, catalog_type: CatalogType | None = None, license: str = "proprietary", keywords: list[str] | None = None, providers: list[Provider] | None = None, summaries: Summaries | None = None, assets: dict[str, Asset] | None = None, strategy: HrefLayoutStrategy | None = None, ): super().__init__( id, description, title, stac_extensions, extra_fields, href, catalog_type or CatalogType.ABSOLUTE_PUBLISHED, strategy, ) self.extent = extent self.license = license self.stac_extensions: list[str] = stac_extensions or [] self.keywords = keywords self.providers = providers self.summaries = summaries or Summaries.empty() self.assets = {} if assets is not None: for k, asset in assets.items(): self.add_asset(k, asset) def __repr__(self) -> str: return f"<Collection id={self.id}>"
[docs] def add_item( self, item: Item, title: str | None = None, strategy: HrefLayoutStrategy | None = None, set_parent: bool = True, ) -> Link: link = super().add_item(item, title, strategy, set_parent) item.set_collection(self) return link
[docs] def to_dict( self, include_self_link: bool = True, transform_hrefs: bool = True ) -> dict[str, Any]: d = super().to_dict( include_self_link=include_self_link, transform_hrefs=transform_hrefs ) d["extent"] = self.extent.to_dict() d["license"] = self.license if self.stac_extensions: d["stac_extensions"] = self.stac_extensions if self.keywords: d["keywords"] = self.keywords if self.providers: d["providers"] = list(map(lambda x: x.to_dict(), self.providers)) if not self.summaries.is_empty(): d["summaries"] = self.summaries.to_dict() if any(self.assets): d["assets"] = {k: v.to_dict() for k, v in self.assets.items()} return d
[docs] def clone(self) -> Collection: cls = self.__class__ clone = cls( id=self.id, description=self.description, extent=self.extent.clone(), title=self.title, stac_extensions=self.stac_extensions.copy(), extra_fields=deepcopy(self.extra_fields), catalog_type=self.catalog_type, license=self.license, keywords=self.keywords.copy() if self.keywords is not None else None, providers=deepcopy(self.providers), summaries=self.summaries.clone(), assets={k: asset.clone() for k, asset in self.assets.items()}, ) clone._resolved_objects.cache(clone) for link in self.links: if link.rel == pystac.RelType.ROOT: # Collection __init__ sets correct root to clone; don't reset # if the root link points to self root_is_self = link.is_resolved() and link.target is self if not root_is_self: clone.set_root(None) clone.add_link(link.clone()) else: clone.add_link(link.clone()) return clone
[docs] @classmethod def from_dict( cls: type[C], d: dict[str, Any], href: str | None = None, root: Catalog | None = None, migrate: bool = False, preserve_dict: bool = True, ) -> C: from pystac.extensions.version import CollectionVersionExtension if migrate: info = identify_stac_object(d) d = migrate_to_latest(d, info) if not cls.matches_object_type(d): raise STACTypeError(d, cls) catalog_type = CatalogType.determine_type(d) if preserve_dict: d = deepcopy(d) id = d.pop("id") description = d.pop("description") license = d.pop("license") extent = Extent.from_dict(d.pop("extent")) title = d.pop("title", None) stac_extensions = d.pop("stac_extensions", None) keywords = d.pop("keywords", None) providers = d.pop("providers", None) if providers is not None: providers = list(map(lambda x: pystac.Provider.from_dict(x), providers)) summaries = d.pop("summaries", None) if summaries is not None: summaries = Summaries(summaries) assets = d.pop("assets", None) if assets: assets = {k: Asset.from_dict(v) for k, v in assets.items()} links = d.pop("links") d.pop("stac_version") collection = cls( id=id, description=description, extent=extent, title=title, stac_extensions=stac_extensions, extra_fields=d, license=license, keywords=keywords, providers=providers, summaries=summaries, href=href, catalog_type=catalog_type, assets=assets, ) for link in links: if link["rel"] == pystac.RelType.ROOT: # Remove the link that's generated in Catalog's constructor. collection.remove_links(pystac.RelType.ROOT) if link["rel"] != pystac.RelType.SELF or href is None: collection.add_link(Link.from_dict(link)) if root: collection.set_root(root) try: version = CollectionVersionExtension.ext(collection) if version.deprecated: warnings.warn( f"The collection '{collection.id}' is deprecated.", DeprecatedWarning, ) # Collection asset deprecation checks pending version extension support except ExtensionNotImplemented: pass return collection
[docs] def get_item(self, id: str, recursive: bool = False) -> Item | None: """Returns an item with a given ID. Args: id : The ID of the item to find. recursive : If True, search this collection and all children for the item; otherwise, only search the items of this collection. Defaults to False. Return: Item or None: The item with the given ID, or None if not found. """ try: return next(self.get_items(id, recursive=recursive), None) except TypeError as e: if any("recursive" in arg for arg in e.args): # For inherited classes that do not yet support recursive # See https://github.com/stac-utils/pystac-client/issues/485 return super().get_item(id, recursive=recursive) raise e
[docs] def update_extent_from_items(self) -> None: """ Update datetime and bbox based on all items to a single bbox and time window. """ self.extent = Extent.from_items(self.get_items(recursive=True))
[docs] def full_copy( self, root: Catalog | None = None, parent: Catalog | None = None ) -> Collection: return cast(Collection, super().full_copy(root, parent))
[docs] @classmethod def matches_object_type(cls, d: dict[str, Any]) -> bool: return identify_stac_object_type(d) == STACObjectType.COLLECTION
@property def ext(self) -> CollectionExt: """Accessor for extension classes on this collection Example:: print(collection.ext.xarray) """ from pystac.extensions.ext import CollectionExt return CollectionExt(stac_object=self)