pystac.collection#

class pystac.collection.Collection(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)[source]

A Collection extends the Catalog spec with additional metadata that helps enable discovery.

Parameters:

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 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, 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 Asset objects. All Asset values in the dictionary will have their owner attribute set to the created Collection.

DEFAULT_FILE_NAME = 'collection.json': Default file name that will be given to this STAC object in a canonical format.

STAC_OBJECT_TYPE: STACObjectType = 'Collection'

add_item(item: Item, title: str | None = None, strategy: HrefLayoutStrategy | None = None, set_parent: bool = True) → Link[source]

Adds a link to an Item.

This method will set the item’s parent to this object and potentially override its self_link (unless set_parent is False)

It will always set its root to this Catalog’s root.

Parameters:

item – The item to add.
title – Optional title to give to the Link
strategy – The layout strategy to use for setting the self href of the item. If not provided, defaults to BestPracticesLayoutStrategy.
set_parent – Whether to set the parent on the item as well. Defaults to True.

Returns:

The link created for the item

Return type:

Link

clone() → Collection[source]

Clones this object.

Cloning an object will make a copy of all properties and links of the object; however, it will not make copies of the targets of links (i.e. it is not a deep copy). To copy a STACObject fully, with all linked elements also copied, use STACObject.full_copy.

Returns:: The clone of this object.
Return type:: STACObject

description: str: Detailed multi-line description to fully explain the collection.

property ext: CollectionExt

Accessor for extension classes on this collection

Example:

print(collection.ext.xarray)

extent: Extent: Spatial and temporal extents that describe the bounds of all items contained within this Collection.

extra_fields: dict[str, Any]: Extra fields that are part of the top-level JSON properties of the Collection.

classmethod from_dict(d: dict[str, Any], href: str | None = None, root: Catalog | None = None, migrate: bool = False, preserve_dict: bool = True) → C[source]

Parses this STACObject from the passed in dictionary.

Parameters:

d – The dict to parse.
href – Optional href that is the file location of the object being parsed.
root – Optional root catalog for this object. If provided, the root of the returned STACObject will be set to this parameter.
migrate – Use True if this dict represents JSON from an older STAC object, so that migrations are run against it.
preserve_dict – If False, the dict parameter d may be modified during this method call. Otherwise the dict is not mutated. Defaults to True, which results results in a deepcopy of the parameter. Set to False when possible to avoid the performance hit of a deepcopy.

Returns:

The STACObject parsed from this dict.

Return type:

STACObject

full_copy(root: Catalog | None = None, parent: Catalog | None = None) → Collection[source]

Create a full copy of this STAC object and any stac objects linked to by this object.

Parameters:

root – Optional root to set as the root of the copied object, and any other copies that are contained by this object.
parent – Optional parent to set as the parent of the copy of this object.

Returns:

A full copy of this object, as well as any objects this object links to.

Return type:

STACObject

get_item(id: str, recursive: bool = False) → Item | None[source]

Returns an item with a given ID.

Parameters:

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.

Returns:

The item with the given ID, or None if not found.

Return type:

Item or None

id: str: Identifier for the collection.

keywords: list[str] | None: Optional list of keywords describing the collection.

links: list[Link]: A list of Link objects representing all links associated with this Collection.

classmethod matches_object_type(d: dict[str, Any]) → bool[source]

Returns a boolean indicating whether the given dictionary represents a valid instance of this STACObject sub-class.

Parameters:: d – A dictionary to identify

providers: list[Provider] | None: Optional list of providers of this Collection.

stac_extensions: list[str]: List of extensions the Collection implements.

summaries: Summaries: A map of property summaries, either a set of values or statistics such as a range.

title: str | None: Optional short descriptive one-line title for the collection.

to_dict(include_self_link: bool = True, transform_hrefs: bool = True) → dict[str, Any][source]

Returns this object as a dictionary.

Parameters:

include_self_link – If True, the dict will contain a self link to this object. If False, the self link will be omitted.
transform_hrefs – If True, transform the HREF of hierarchical links based on the type of catalog this object belongs to (if any). I.e. if this object belongs to a root catalog that is RELATIVE_PUBLISHED or SELF_CONTAINED, hierarchical link HREFs will be transformed to be relative to the catalog root.
dict – A serialization of the object.

update_extent_from_items() → None[source]: Update datetime and bbox based on all items to a single bbox and time window.

class pystac.collection.Extent(spatial: SpatialExtent, temporal: TemporalExtent, extra_fields: dict[str, Any] | None = None)[source]

Describes the spatiotemporal extents of a Collection.

Parameters:

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.

clone() → Extent[source]

Clones this object.

Returns:: The clone of this extent.
Return type:: Extent

extra_fields: dict[str, Any]: Dictionary containing additional top-level fields defined on the Extent object.

static from_dict(d: dict[str, Any]) → Extent[source]

Constructs an Extent from a dict.

Returns:: The Extent deserialized from the JSON dict.
Return type:: Extent

static from_items(items: Iterable[Item], extra_fields: dict[str, Any] | None = None) → Extent[source]

Create an Extent based on the datetimes and bboxes of a list of items.

Parameters:

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:

An Extent that spatially and temporally covers all of the given items.

Return type:

Extent

spatial: SpatialExtent: Potential spatial extent covered by the collection.

temporal: TemporalExtent: Potential temporal extent covered by the collection.

to_dict() → dict[str, Any][source]

Returns this extent as a dictionary.

Returns:: A serialization of the Extent.
Return type:: dict

class pystac.collection.SpatialExtent(bboxes: Bboxes | list[float | int], extra_fields: dict[str, Any] | None = None)[source]

Describes the spatial extent of a Collection.

Parameters:

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: list[list[Union[float, int]]]: 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]]

clone() → SpatialExtent[source]

Clones this object.

Returns:: The clone of this object.
Return type:: SpatialExtent

extra_fields: dict[str, Any]: Dictionary containing additional top-level fields defined on the Spatial Extent object.

static from_coordinates(coordinates: list[Any], extra_fields: dict[str, Any] | None = None) → SpatialExtent[source]

Constructs a SpatialExtent from a set of coordinates.

This method will only produce a single bbox that covers all points in the coordinate set.

Parameters:

coordinates – Coordinates to derive the bbox from.
extra_fields – Dictionary containing additional top-level fields defined on the SpatialExtent object.

Returns:

A SpatialExtent with a single bbox that covers the given coordinates.

Return type:

SpatialExtent

static from_dict(d: dict[str, Any]) → SpatialExtent[source]

Constructs a SpatialExtent from a dict.

Returns:: The SpatialExtent deserialized from the JSON dict.
Return type:: SpatialExtent

to_dict() → dict[str, Any][source]

Returns this spatial extent as a dictionary.

Returns:: A serialization of the SpatialExtent.
Return type:: dict

class pystac.collection.TemporalExtent(intervals: TemporalIntervals | list[datetime | None], extra_fields: dict[str, Any] | None = None)[source]

Describes the temporal extent of a Collection.

Parameters:

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.

clone() → TemporalExtent[source]

Clones this object.

Returns:: The clone of this object.
Return type:: TemporalExtent

extra_fields: dict[str, Any]: Dictionary containing additional top-level fields defined on the Temporal Extent object.

static from_dict(d: dict[str, Any]) → TemporalExtent[source]

Constructs an TemporalExtent from a dict.

Returns:: The TemporalExtent deserialized from the JSON dict.
Return type:: TemporalExtent

static from_now() → TemporalExtent[source]

Constructs an TemporalExtent with a single open interval that has the start time as the current time.

Returns:: The resulting TemporalExtent.
Return type:: TemporalExtent

intervals: list[list[datetime.datetime]] | list[list[Optional[datetime.datetime]]]: 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.

to_dict() → dict[str, Any][source]

Returns this temporal extent as a dictionary.

Returns:: A serialization of the TemporalExtent.
Return type:: dict