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