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 = 'other', keywords: list[str] | None = None, providers: list[Provider] | None = None, summaries: Summaries | None = None, assets: dict[str, Asset] | None = None, strategy: HrefLayoutStrategy | 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, 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, 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.

  • strategy – The layout strategy to use for setting the HREFs of the catalog child objects and items. If not provided, it will default to strategy of the parent and fallback to BestPracticesLayoutStrategy.

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 the layout strategy of the parent or root and falls back 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 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 = True, 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 – By default, STAC objects and extensions are migrated to their latest supported version. Set this to False to disable this behavior.

  • 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

classmethod from_items(items: Iterable[Item] | pystac.ItemCollection, *, id: str | None = None, strategy: HrefLayoutStrategy | None = None) → Collection[source]

Create a Collection from iterable of items or an ItemCollection.

Will try to pull collection attributes from extra_fields and items when possible.

Parameters:

  • items – Iterable of Item instances to include in the Collection. This can be a ItemCollection.

  • id – Identifier for the collection. If not set, must be available on the items and they must all match.

  • strategy – The layout strategy to use for setting the HREFs of the catalog child objects and items. If not provided, it will default to strategy of the parent and fallback to BestPracticesLayoutStrategy.

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.

property item_assets: dict[str, ItemAssetDefinition]

Accessor for item_assets on this collection.

Example:

.. code-block:: python

>>> print(collection.item_assets)
{'thumbnail': <pystac.item_assets.ItemAssetDefinition at 0x72aea0420750>,
 'metadata': <pystac.item_assets.ItemAssetDefinition at 0x72aea017dc90>,
 'B5': <pystac.item_assets.ItemAssetDefinition at 0x72aea017efd0>,
 'B6': <pystac.item_assets.ItemAssetDefinition at 0x72aea016d5d0>,
 'B7': <pystac.item_assets.ItemAssetDefinition at 0x72aea016e050>,
 'B8': <pystac.item_assets.ItemAssetDefinition at 0x72aea016da90>}
>>> collection.item_assets["thumbnail"].title
'Thumbnail'

Set attributes on ItemAssetDefinition objects

>>> collection.item_assets["thumbnail"].title = "New Title"

Add to the item_assets dict:

>>> collection.item_assets["B4"] = {
    'type': 'image/tiff; application=geotiff; profile=cloud-optimized',
    'eo:bands': [{'name': 'B4', 'common_name': 'red'}]
}
>>> collection.item_assets["B4"].owner == collection
True
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.C#

Generalized version of Collection

alias of TypeVar(‘C’, bound=Collection)

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: list[list[float | int]] | 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[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: list[list[datetime]] | list[list[datetime | None]] | 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]] | list[list[datetime | None]]#

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