Skip to main content
`Ctrl`+`K`

# 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)

  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 objections 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

    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

    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

    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

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

    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

    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

    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]

    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

    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)

  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

    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

    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

    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]

    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)

  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

    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

    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

    Constructs a SpatialExtent from a dict.

    Returns:

      The SpatialExtent deserialized from the JSON dict.

    Return type:

      SpatialExtent

  to_dict() → dict[str, Any]

    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)

  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

    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

    Constructs an TemporalExtent from a dict.

    Returns:

      The TemporalExtent deserialized from the JSON dict.

    Return type:

      TemporalExtent

  static from_now() → TemporalExtent

    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]

    Returns this temporal extent as a dictionary.

    Returns:

      A serialization of the TemporalExtent.

    Return type:

      dict