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. AllAsset
values in the dictionary will have theirowner
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:
- 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:
- 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:
- 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:
- 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.
- 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
- summaries: Summaries
A map of property summaries, either a set of values or statistics such as a range.
- 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.
- 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.
- 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:
- 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:
- spatial: SpatialExtent
Potential spatial extent covered by the collection.
- temporal: TemporalExtent
Potential temporal extent covered by the collection.
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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.