Skip to main content
`Ctrl`+`K`

# pystac

PySTAC is a library for working with SpatioTemporal Asset Catalogs (STACs)

`STACObject`(stac_extensions) | A base class for other PySTAC classes that contains a variety of useful methods for dealing with links, copying objects, accessing extensions, and reading and writing files.
`Catalog`(id, description[, title, ...]) | A PySTAC Catalog represents a STAC catalog in memory.
`Collection`(id, description, extent[, title, ...]) | A Collection extends the Catalog spec with additional metadata that helps enable discovery.
`Extent`(spatial, temporal[, extra_fields]) | Describes the spatiotemporal extents of a Collection.
`SpatialExtent`(bboxes[, extra_fields]) | Describes the spatial extent of a Collection.
`TemporalExtent`(intervals[, extra_fields]) | Describes the temporal extent of a Collection.
`Provider`(name[, description, roles, url, ...]) | Provides information about a provider of STAC data.
`Summaries`(summaries[, maxcount]) |
`Item`(id, geometry, bbox, datetime, properties) | An Item is the core granular entity in a STAC, containing the core metadata that enables any client to search or crawl online catalogs of spatial 'assets' - satellite imagery, derived data, DEM's, etc.
`Asset`(href[, title, description, ...]) | An object that contains a link to data associated with an Item or Collection that can be downloaded or streamed.
`ItemAssetDefinition`(properties[, owner]) | Implementation of the Item Asset Definition Object for use as values in the `item_assets` dict.
`CommonMetadata`(object) | Object containing fields that are not included in core item schema but are still commonly used.
`ItemCollection`(items[, extra_fields, ...]) | Implementation of a GeoJSON FeatureCollection whose features are all STAC Items, as defined by STAC API - ItemCollection Fragment.
`Link`(rel, target[, media_type, title, ...]) | A link connects a `STACObject` to another entity.
`StacIO`([headers]) |
`read_file`(href[, stac_io]) | Reads a STAC object from a file.
`write_file`(obj[, include_self_link, ...]) | Writes a STACObject to a file.
`read_dict`(d[, href, root, stac_io]) | Reads a `STACObject` or `ItemCollection` from a JSON-like dict representing a serialized STAC object.
`set_stac_version`(stac_version) | Sets the STAC version that PySTAC should use.
`get_stac_version`() | Returns the STAC version PySTAC writes as the "stac_version" property for any object it serializes into JSON.

pystac.get_stac_version() → str

  Returns the STAC version PySTAC writes as the “stac_version” property for any object it serializes into JSON.

  If a call to `set_stac_version` was made, this will return the value it was called with. Next it will check the environment for a PYSTAC_STAC_VERSION_OVERRIDE variable. Otherwise, it will return the latest STAC version that this version of PySTAC supports.

  Returns:

    The STAC Version PySTAC is set up to use.

  Return type:

    str

pystac.read_dict(d: dict[str, Any], href: str | None = None, root: Catalog | None = None, stac_io: StacIO | None = None) → STACObject

  Reads a `STACObject` or `ItemCollection` from a JSON-like dict representing a serialized STAC object.

  This method will return either a `Catalog`, `Collection`, or :class`~Item` based on the contents of the dict.

  This is a convenience method for either `StacIO.stac_object_from_dict`.

  Parameters:

    - d – The dict to parse.

    - href – Optional href that is the file location of the object being parsed.

    - root – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.

    - stac_io – Optional `StacIO` instance to use for reading. If `None`, the default instance will be used.

  Raises:

    STACTypeError – If the `d` dictionary does not represent a valid `STACObject`. Note that an `ItemCollection` is not a `STACObject` and must be read using `ItemCollection.from_dict`

pystac.read_file(href: str | PathLike[str], stac_io: StacIO | None = None) → STACObject

  Reads a STAC object from a file.

  This method will return either a Catalog, a Collection, or an Item based on what the file contains.

  This is a convenience method for `StacIO.read_stac_object`

  Parameters:

    - href – The HREF to read the object from.

    - stac_io – Optional `StacIO` instance to use for I/O operations. If not provided, will use `StacIO.default()` to create an instance.

  Returns:

    The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.

  Raises:

    STACTypeError – If the file at `href` does not represent a valid `STACObject`. Note that an `ItemCollection` is not a `STACObject` and must be read using `ItemCollection.from_file`

pystac.set_stac_version(stac_version: str | None) → None

  Sets the STAC version that PySTAC should use.

  This is the version that will be set as the “stac_version” property on any JSON STAC objects written by PySTAC. If set to None, the override version will be cleared if previously set and the default or an override taken from the environment will be used.

  You can also set the environment variable PYSTAC_STAC_VERSION_OVERRIDE to override the version.

  Parameters:

    stac_version – The STAC version to use instead of the latest STAC version that PySTAC supports (described in STACVersion.DEFAULT_STAC_VERSION). If None, clear to use the default for this version of PySTAC.

  Note

  Setting the STAC version to something besides the default version will not affect the format of STAC read or written; it will only override the `stac_version` property of the objects being written. Setting this incorrectly can produce invalid STAC.

pystac.write_file(obj: STACObject, include_self_link: bool = True, dest_href: str | PathLike[str] | None = None, stac_io: StacIO | None = None) → None

  Writes a STACObject to a file.

  This will write only the Catalog, Collection or Item `obj`. It will not attempt to write any other objects that are linked to `obj`; if you’d like functionality to save off catalogs recursively see `Catalog.save`.

  This method will write the JSON of the object to the object’s assigned “self” link or to the dest_href if provided. To set the self link, see `STACObject.set_self_href`.

  Convenience method for `STACObject.from_file`

  Parameters:

    - obj – The STACObject to save.

    - include_self_link – If `True`, include the `"self"` link with this object. Otherwise, leave out the self link.

    - dest_href – Optional HREF to save the file to. If `None`, the object will be saved to the object’s `"self"` href.

    - stac_io – Optional `StacIO` instance to use for I/O operations. If not provided, will use `StacIO.default()` to create an instance.

# STACObject

class pystac.STACObject(stac_extensions: list[str])

  A base class for other PySTAC classes that contains a variety of useful methods for dealing with links, copying objects, accessing extensions, and reading and writing files. You shouldn’t use STACObject directly, but instead access this functionality through the implementing classes.

  STAC_OBJECT_TYPE: STACObjectType
  add_link(link: Link) → None

    Add a link to this object’s set of links.

    Parameters:

      link – The link to add.

  add_links(links: list[Link]) → None

    Add links to this object’s set of links.

    Parameters:

      links – The links to add.

  clear_links(rel: str | RelType | None = None) → None

    Clears all `Link` instances associated with this object.

    Parameters:

      rel – If set, only clear links that match this relationship.

  abstractmethod clone() → STACObject

    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

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

    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 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_file(href: str | PathLike[str], stac_io: StacIO | None = None) → S

    Reads a STACObject implementation from a file.

    Parameters:

      - href – The HREF to read the object from.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the default instance.

    Returns:

      The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.

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

    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_links(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → list[Link]

    Gets the `Link` instances associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      A list of links that match `rel` and/

        or `media_type` if set, or else all links associated with this object.

    Return type:

      List[`Link`]

  get_parent() → Catalog | None

    Get the `Catalog` or `Collection` to the parent for this object. The root is represented by a `Link` with `rel == 'parent'`.

    Returns:

      The parent object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root() → Catalog | None

    Get the `Catalog` or `Collection` to the root for this object. The root is represented by a `Link` with `rel == 'root'`.

    Returns:

      The root object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root_link() → Link | None

    Get the `Link` representing the root for this object.

    Returns:

      The root link for this object, or `None` if no root link is set.

    Return type:

      `Link` or None

  get_self_href() → str | None

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Returns:

      The absolute HREF of this object, or `None` if there is no self link defined.

    Return type:

      str or None

    Note

    A self link can exist for objects, even if the link is not read or written to the JSON-serialized version of the object. Any object read from `STACObject.from_file` will have the HREF the file was read from set as it’s self HREF. All self links have absolute (as opposed to relative) HREFs.

  get_single_link(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → Link | None

    Get a single `Link` instance associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      First link that matches `rel`

        and/or `media_type`, or else the first link associated with this object.

    Return type:

      `Link` | None

  get_stac_objects(rel: str | RelType, typ: type[STACObject] | None = None, modify_links: Callable[[list[Link]], list[Link]] | None = None) → Iterable[STACObject]

    Gets the `STACObject` instances that are linked to by links with their `rel` property matching the passed in argument.

    Parameters:

      - rel – The relation to match each `Link`’s `rel` property against.

      - typ – If not `None`, objects will only be yielded if they are instances of `typ`.

      - modify_links – A function that modifies the list of links before they are iterated over. For instance, this option can be used to sort the list so that links matching a particular pattern are earlier in the iterator.

    Returns:

      A possibly empty iterable of STACObjects that are

        connected to this object through links with the given `rel` and are of type `typ` (if given).

    Return type:

      Iterable[STACObject]

  id: str

    The ID of the STAC Object.

  links: list[Link]

    A list of `Link` objects representing all links associated with this STAC Object.

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

    Returns a boolean indicating whether the given dictionary represents a valid instance of this `STACObject` subclass.

    Parameters:

      d – A dictionary to identify

  remove_hierarchical_links(add_canonical: bool = False) → list[Link]

    Removes all hierarchical links from this object.

    See `pystac.link.HIERARCHICAL_LINKS` for a list of all hierarchical links. If the object has a `self` href and `add_canonical` is True, a link with `rel="canonical"` is added.

    Parameters:

      add_canonical – If true, and this item has a `self` href, that href is used to build a `canonical` link.

    Returns:

      All removed links

    Return type:

      List[Link]

  remove_links(rel: str | RelType) → None

    Remove links to this object’s set of links that match the given `rel`.

    Parameters:

      rel – The `Link` `rel` to match on.

  resolve_links() → None

    Ensure all STACObjects linked to by this STACObject are resolved. This is important for operations such as changing HREFs.

    This method mutates the entire catalog tree.

  save_object(include_self_link: bool = True, dest_href: str | None = None, stac_io: StacIO | None = None) → None

    Saves this `STACObject` to it’s ‘self’ HREF.

    Parameters:

      - include_self_link – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.

      - dest_href – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the instance set on the object’s root if available, otherwise will use the default instance.

    Raises:

      STACError – If no self href is set, this error will be raised.

    Note

    When to include a self link is described in the Use of Links section of the STAC best practices document

  property self_href: str

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Raises:

      ValueError – If the self_href is not set, this method will throw a ValueError. Use get_self_href if there may not be an HREF set.

  set_parent(parent: Catalog | None) → None

    Sets the parent `Catalog` or `Collection` for this object.

    Parameters:

      parent – The parent object to set. Passing in None will clear the parent.

  set_root(root: Catalog | None) → None

    Sets the root `Catalog` or `Collection` for this object.

    Parameters:

      root – The root object to set. Passing in None will clear the root.

  set_self_href(href: str | None) → None

    Sets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Parameters:

      href – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.

  stac_extensions: list[str]

    A list of schema URIs for STAC Extensions implemented by this STAC Object.

  target_in_hierarchy(target: str | STACObject) → bool

    Determine if target is somewhere in the hierarchical link tree of a STACObject.

    Parameters:

      target – A string or STACObject to search for

    Returns:

      Returns True if the target was found in the hierarchical link tree

        for the current STACObject

    Return type:

      bool

  abstractmethod 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.

  validate(validator: STACValidator | None = None) → list[Any]

    Validate this STACObject.

    Returns a list of validation results, which depends on the validation implementation. For JSON Schema validation (default validator), this will be a list of schema URIs that were used during validation.

    Parameters:

      validator – A custom validator to use for validation of the object. If omitted, the default validator from `RegisteredValidator` will be used instead.

    Raises:

      STACValidationError –

class pystac.STACObjectType(*values)
  CATALOG = 'Catalog'
  COLLECTION = 'Collection'
  ITEM = 'Feature'

# Catalog

class pystac.Catalog(id: str, description: str, title: str | None = None, stac_extensions: list[str] | None = None, extra_fields: dict[str, Any] | None = None, href: str | None = None, catalog_type: CatalogType = 'ABSOLUTE_PUBLISHED', strategy: HrefLayoutStrategy | None = None)

  A PySTAC Catalog represents a STAC catalog in memory.

  A Catalog is a `STACObject` that may contain children, which are instances of `Catalog` or `Collection`, as well as `Item` s.

  Parameters:

    - id – Identifier for the catalog. Must be unique within the STAC.

    - description – Detailed multi-line description to fully explain the catalog. CommonMark 0.29 syntax MAY be used for rich text representation.

    - title – Optional short descriptive one-line title for the catalog.

    - stac_extensions – Optional list of extensions the Catalog implements.

    - href – Optional HREF for this catalog, which be set as the catalog’s self link’s HREF.

    - catalog_type – Optional catalog type for this catalog. Must be one of the values in `CatalogType`.

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

  DEFAULT_FILE_NAME = 'catalog.json'

    Default file name that will be given to this STAC object in a canonical format.

  STAC_OBJECT_TYPE: STACObjectType = 'Catalog'
  add_child(child: Catalog | Collection, title: str | None = None, strategy: HrefLayoutStrategy | None = None, set_parent: bool = True) → Link

    Adds a link to a child `Catalog` or `Collection`.

    This method will set the child’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:

      - child – The child to add.

      - title – Optional title to give to the `Link`

      - strategy – The layout strategy to use for setting the self href of the child. 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 child as well. Defaults to True.

    Returns:

      The link created for the child

    Return type:

      Link

  add_children(children: Iterable[Catalog | Collection], strategy: HrefLayoutStrategy | None = None) → list[Link]

    Adds links to multiple `Catalog` or ~pystac.Collection objects. This method will set each child’s parent to this object, and their root to this Catalog’s root.

    Parameters:

      - children – The children to add.

      - strategy – The layout strategy to use for setting the self href of the children. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`.

    Returns:

      An array of links created for the children

    Return type:

      List[Link]

  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

  add_items(items: Iterable[Item], strategy: HrefLayoutStrategy | None = None) → list[Link]

    Adds links to multiple `Items`.

    This method will set each item’s parent to this object, and their root to this Catalog’s root.

    Parameters:

      - items – The items to add.

      - strategy – The layout strategy to use for setting the self href of the items. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`.

    Returns:

      A list of links created for the item

    Return type:

      List[Link]

  add_link(link: Link) → None

    Add a link to this object’s set of links.

    Parameters:

      link – The link to add.

  add_links(links: list[Link]) → None

    Add links to this object’s set of links.

    Parameters:

      links – The links to add.

  catalog_type: CatalogType

    The catalog type. Defaults to `CatalogType.ABSOLUTE_PUBLISHED`.

  clear_children() → None

    Removes all children from this catalog.

    Returns:

      Returns `self`

    Return type:

      Catalog

  clear_items() → None

    Removes all items from this catalog.

    Returns:

      Returns `self`

    Return type:

      Catalog

  clear_links(rel: str | RelType | None = None) → None

    Clears all `Link` instances associated with this object.

    Parameters:

      rel – If set, only clear links that match this relationship.

  clone() → Catalog

    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

  describe(include_hrefs: bool = False, _indent: int = 0) → None

    Prints out information about this Catalog and all contained STACObjects.

    Parameters:

      include_hrefs (bool) – HREF along with the object ID.

  description: str

    Detailed multi-line description to fully explain the catalog.

  property ext: CatalogExt

    Accessor for extension classes on this catalog

    Example:

        print(collection.ext.version)

  extra_fields: dict[str, Any]

    Extra fields that are part of the top-level JSON properties of the Catalog.

  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 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_file(href: str | PathLike[str], stac_io: StacIO | None = None) → C

    Reads a STACObject implementation from a file.

    Parameters:

      - href – The HREF to read the object from.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the default instance.

    Returns:

      The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.

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

    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

  fully_resolve() → None

    Resolves every link in this catalog.

    Useful if, e.g., you’d like to read a catalog from a filesystem, upgrade every object in the catalog to the latest STAC version, and save it back to the filesystem. By default, `save()` skips unresolved links.

  generate_subcatalogs(template: str, defaults: dict[str, Any] | None = None, parent_ids: list[str] | None = None) → list[Catalog]

    Walks through the catalog and generates subcatalogs for items based on the template string.

    See `LayoutTemplate` for details on the construction of template strings. This template string will be applied to the items, and subcatalogs will be created that separate and organize the items based on template values.

    Parameters:

      - template – A template string that can be consumed by a `LayoutTemplate`

      - defaults – Default values for the template variables that will be used if the property cannot be found on the item.

      - parent_ids – Optional list of the parent catalogs’ identifiers. If the bottom-most subcatalogs already match the template, no subcatalog is added.

    Returns:

      List of new catalogs created

    Return type:

      list[Catalog]

  get_all_collections() → Iterable[Collection]

    Get all collections from this catalog and all subcatalogs. Will traverse any subcatalogs recursively.

  get_all_items() → Iterator[Item]

    DEPRECATED.

    Deprecated since version 1.8: Use `pystac.Catalog.get_items(recursive=True)` instead.

    Get all items from this catalog and all subcatalogs. Will traverse any subcatalogs recursively.

    Returns:

      All items that belong to this catalog, and all

        catalogs or collections connected to this catalog through child links.

    Return type:

      Generator[Item]

  get_child(id: str, recursive: bool = False, sort_links_by_id: bool = True) → Catalog | Collection | None

    Gets the child of this catalog with the given ID, if it exists.

    Parameters:

      - id – The ID of the child to find.

      - recursive – If True, search this catalog and all children for the item; otherwise, only search the children of this catalog. Defaults to False.

      - sort_links_by_id – If True, links containing the ID will be checked first. If links do not contain the ID then setting this to False will improve performance. Defaults to True.

    Returns:

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

    Return type:

      Catalog or Collection or None

  get_child_links() → list[Link]

    Return all child links of this catalog.

    Returns:

      List of links of this catalog with `rel == 'child'`

    Return type:

      List[Link]

  get_children() → Iterable[Catalog | Collection]

    Return all children of this catalog.

    Returns:

      Iterable of children whose parent is this catalog.

    Return type:

      Iterable[Catalog or Collection]

  get_collections() → Iterable[Collection]

    Return all children of this catalog that are `Collection` instances.

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

    DEPRECATED.

    Deprecated since version 1.8: Use `next(pystac.Catalog.get_items(id), None)` instead.

    Returns an item with a given ID.

    Parameters:

      - id – The ID of the item to find.

      - recursive – If True, search this catalog and all children for the item; otherwise, only search the items of this catalog. Defaults to False.

    Returns:

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

    Return type:

      Item or None

  get_item_links() → list[Link]

    Return all item links of this catalog.

    Returns:

      List of links of this catalog with `rel == 'item'`

    Return type:

      List[Link]

  get_items(*ids: str, recursive: bool = False) → Iterator[Item]

    Return all items or specific items of this catalog.

    Parameters:

      - *ids – The IDs of the items to include.

      - recursive – If True, search this catalog and all children for the item; otherwise, only search the items of this catalog. Defaults to False.

    Returns:

      Generator of items whose parent is this catalog, and

        (if recursive) all catalogs or collections connected to this catalog through child links.

    Return type:

      Iterator[Item]

  get_links(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → list[Link]

    Gets the `Link` instances associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      A list of links that match `rel` and/

        or `media_type` if set, or else all links associated with this object.

    Return type:

      List[`Link`]

  get_parent() → Catalog | None

    Get the `Catalog` or `Collection` to the parent for this object. The root is represented by a `Link` with `rel == 'parent'`.

    Returns:

      The parent object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root() → Catalog | None

    Get the `Catalog` or `Collection` to the root for this object. The root is represented by a `Link` with `rel == 'root'`.

    Returns:

      The root object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root_link() → Link | None

    Get the `Link` representing the root for this object.

    Returns:

      The root link for this object, or `None` if no root link is set.

    Return type:

      `Link` or None

  get_self_href() → str | None

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Returns:

      The absolute HREF of this object, or `None` if there is no self link defined.

    Return type:

      str or None

    Note

    A self link can exist for objects, even if the link is not read or written to the JSON-serialized version of the object. Any object read from `STACObject.from_file` will have the HREF the file was read from set as it’s self HREF. All self links have absolute (as opposed to relative) HREFs.

  get_single_link(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → Link | None

    Get a single `Link` instance associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      First link that matches `rel`

        and/or `media_type`, or else the first link associated with this object.

    Return type:

      `Link` | None

  get_stac_objects(rel: str | RelType, typ: type[STACObject] | None = None, modify_links: Callable[[list[Link]], list[Link]] | None = None) → Iterable[STACObject]

    Gets the `STACObject` instances that are linked to by links with their `rel` property matching the passed in argument.

    Parameters:

      - rel – The relation to match each `Link`’s `rel` property against.

      - typ – If not `None`, objects will only be yielded if they are instances of `typ`.

      - modify_links – A function that modifies the list of links before they are iterated over. For instance, this option can be used to sort the list so that links matching a particular pattern are earlier in the iterator.

    Returns:

      A possibly empty iterable of STACObjects that are

        connected to this object through links with the given `rel` and are of type `typ` (if given).

    Return type:

      Iterable[STACObject]

  id: str

    Identifier for the catalog.

  is_relative() → bool
  links: list[Link]

    A list of `Link` objects representing all links associated with this Catalog.

  make_all_asset_hrefs_absolute() → None

    Recursively makes all the HREFs of assets in this catalog absolute

  make_all_asset_hrefs_relative() → None

    Recursively makes all the HREFs of assets in this catalog relative

  map_assets(asset_mapper: Callable[[str, Asset], Asset | tuple[str, Asset] | dict[str, Asset]]) → Catalog

    Creates a copy of a catalog, with each Asset for each Item passed through the asset_mapper function.

    Parameters:

      asset_mapper – A function that takes in a key and an Asset, and returns either an Asset, a (key, Asset), or a dictionary of Assets with unique keys. The Asset that is passed into the item_mapper is a copy, so the method can mutate it safely.

    Returns:

      A full copy of this catalog, with assets manipulated according to the asset_mapper function.

    Return type:

      Catalog

  map_items(item_mapper: Callable[[Item], Item | list[Item]]) → Catalog

    Creates a copy of a catalog, with each item passed through the item_mapper function.

    Parameters:

      item_mapper – A function that takes in an item, and returns either an item or list of items. The item that is passed into the item_mapper is a copy, so the method can mutate it safely.

    Returns:

      A full copy of this catalog, with items manipulated according to the item_mapper function.

    Return type:

      Catalog

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

    Returns a boolean indicating whether the given dictionary represents a valid instance of this `STACObject` subclass.

    Parameters:

      d – A dictionary to identify

  normalize_and_save(root_href: str, catalog_type: CatalogType | None = None, strategy: HrefLayoutStrategy | None = None, stac_io: StacIO | None = None, skip_unresolved: bool = False) → None

    Normalizes link HREFs to the given root_href, and saves the catalog.

    This is a convenience method that simply calls `Catalog.normalize_hrefs` and `Catalog.save` in sequence.

    Parameters:

      - root_href – The absolute HREF that all links will be normalized against.

      - catalog_type – The catalog type that dictates the structure of the catalog to save. Use a member of `CatalogType`. Defaults to the root catalog.catalog_type or the current catalog catalog_type if there is no root catalog.

      - strategy – The layout strategy to use in setting the HREFS for this catalog. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`

      - stac_io – Optional instance of `StacIO` to use. If not provided, will use the instance set while reading in the catalog, or the default instance if this is not available.

      - skip_unresolved – Skip unresolved links when normalizing the tree. Defaults to False. Because unresolved links are not saved, this argument can be used to normalize and save only newly-added objects.

  normalize_hrefs(root_href: str, strategy: HrefLayoutStrategy | None = None, skip_unresolved: bool = False) → None

    Normalize HREFs will regenerate all link HREFs based on an absolute root_href and the canonical catalog layout as specified in the STAC specification’s best practices.

    This method mutates the entire catalog tree, unless `skip_unresolved` is True, in which case only resolved links are modified. This is useful in the case when you have loaded a large catalog and you’ve added a few items/children, and you only want to update those newly-added objects, not the whole tree.

    Parameters:

      - root_href – The absolute HREF that all links will be normalized against.

      - strategy – The layout strategy to use in setting the HREFS for this catalog. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`

      - skip_unresolved – Skip unresolved links when normalizing the tree. Defaults to False.

    See:

      STAC best practices document for the canonical layout of a STAC.

  remove_child(child_id: str) → None

    Removes a child from this catalog.

    Parameters:

      child_id – The ID of the child to remove.

  remove_hierarchical_links(add_canonical: bool = False) → list[Link]

    Removes all hierarchical links from this object.

    See `pystac.link.HIERARCHICAL_LINKS` for a list of all hierarchical links. If the object has a `self` href and `add_canonical` is True, a link with `rel="canonical"` is added.

    Parameters:

      add_canonical – If true, and this item has a `self` href, that href is used to build a `canonical` link.

    Returns:

      All removed links

    Return type:

      List[Link]

  remove_item(item_id: str) → None

    Removes an item from this catalog.

    Parameters:

      item_id – The ID of the item to remove.

  remove_links(rel: str | RelType) → None

    Remove links to this object’s set of links that match the given `rel`.

    Parameters:

      rel – The `Link` `rel` to match on.

  resolve_links() → None

    Ensure all STACObjects linked to by this STACObject are resolved. This is important for operations such as changing HREFs.

    This method mutates the entire catalog tree.

  save(catalog_type: CatalogType | None = None, dest_href: str | None = None, stac_io: StacIO | None = None) → None

    Save this catalog and all it’s children/item to files determined by the object’s self link HREF or a specified path.

    Parameters:

      - catalog_type – The catalog type that dictates the structure of the catalog to save. Use a member of `CatalogType`. If not supplied, the catalog_type of this catalog will be used. If that attribute is not set, an exception will be raised.

      - dest_href – The location where the catalog is to be saved. If not supplied, the catalog’s self link HREF is used to determine the location of the catalog file and children’s files.

      - stac_io – Optional instance of `StacIO` to use. If not provided, will use the instance set while reading in the catalog, or the default instance if this is not available.

    Note

    If the catalog type is `CatalogType.ABSOLUTE_PUBLISHED`, all self links will be included, and hierarchical links be absolute URLs. If the catalog type is `CatalogType.RELATIVE_PUBLISHED`, this catalog’s self link will be included, but no child catalog will have self links, and hierarchical links will be relative URLs If the catalog type is `CatalogType.SELF_CONTAINED`, no self links will be included and hierarchical links will be relative URLs.

  save_object(include_self_link: bool = True, dest_href: str | None = None, stac_io: StacIO | None = None) → None

    Saves this `STACObject` to it’s ‘self’ HREF.

    Parameters:

      - include_self_link – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.

      - dest_href – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the instance set on the object’s root if available, otherwise will use the default instance.

    Raises:

      STACError – If no self href is set, this error will be raised.

    Note

    When to include a self link is described in the Use of Links section of the STAC best practices document

  property self_href: str

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Raises:

      ValueError – If the self_href is not set, this method will throw a ValueError. Use get_self_href if there may not be an HREF set.

  set_parent(parent: Catalog | None) → None

    Sets the parent `Catalog` or `Collection` for this object.

    Parameters:

      parent – The parent object to set. Passing in None will clear the parent.

  set_root(root: Catalog | None) → None

    Sets the root `Catalog` or `Collection` for this object.

    Parameters:

      root – The root object to set. Passing in None will clear the root.

  set_self_href(href: str | None) → None

    Sets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Parameters:

      href – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.

  stac_extensions: list[str]

    List of extensions the Catalog implements.

  strategy: HrefLayoutStrategy | None
  target_in_hierarchy(target: str | STACObject) → bool

    Determine if target is somewhere in the hierarchical link tree of a STACObject.

    Parameters:

      target – A string or STACObject to search for

    Returns:

      Returns True if the target was found in the hierarchical link tree

        for the current STACObject

    Return type:

      bool

  title: str | None

    Optional short descriptive one-line title for the catalog.

  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.

  validate(validator: STACValidator | None = None) → list[Any]

    Validate this STACObject.

    Returns a list of validation results, which depends on the validation implementation. For JSON Schema validation (default validator), this will be a list of schema URIs that were used during validation.

    Parameters:

      validator – A custom validator to use for validation of the object. If omitted, the default validator from `RegisteredValidator` will be used instead.

    Raises:

      STACValidationError –

  validate_all(max_items: int | None = None, recursive: bool = True) → int

    Validates each catalog, collection, item contained within this catalog.

    Walks through the children and items of the catalog and validates each stac object.

    Parameters:

      - max_items – The maximum number of STAC items to validate. Default is None which means, validate them all.

      - recursive – Whether to validate catalog, collections, and items contained within child objects.

    Returns:

      Number of STAC items validated.

    Return type:

      int

    Raises:

      STACValidationError – Raises this error on any item that is invalid. Will raise on the first invalid stac object encountered.

  walk() → Iterable[tuple[Catalog, Iterable[Catalog], Iterable[Item]]]

    Walks through children and items of catalogs.

    For each catalog in the STAC’s tree rooted at this catalog (including this catalog itself), it yields a 3-tuple (root, subcatalogs, items). The root in that 3-tuple refers to the current catalog being walked, the subcatalogs are any catalogs or collections for which the root is a parent, and items represents any items that have the root as a parent.

    This has similar functionality to Python’s `os.walk()`.

    Returns:

      A generator that yields a 3-tuple (parent_catalog, children, items).

    Return type:

      Generator[(Catalog, Generator[Catalog], Generator[Item])]

# CatalogType

class pystac.CatalogType(*values)
  ABSOLUTE_PUBLISHED = 'ABSOLUTE_PUBLISHED'

    Absolute Published Catalog is a catalog that uses absolute links for everything, both in the links objects and in the asset hrefs.

    See:

      The best practices documentation on published catalogs

  RELATIVE_PUBLISHED = 'RELATIVE_PUBLISHED'

    Relative Published Catalog is a catalog that uses relative links for everything, but includes an absolute self link at the root catalog, to identify its online location.

    See:

      The best practices documentation on published catalogs

  SELF_CONTAINED = 'SELF_CONTAINED'

    A ‘self-contained catalog’ is one that is designed for portability. Users may want to download an online catalog from and be able to use it on their local computer, so all links need to be relative.

    See:

      The best practices documentation on self-contained catalogs

  capitalize()

    Return a capitalized version of the string.

    More specifically, make the first character have upper case and the rest lower case.

  casefold()

    Return a version of the string suitable for caseless comparisons.

  center(width, fillchar=' ', /)

    Return a centered string of length width.

    Padding is done using the specified fill character (default is a space).

  count()

    Return the number of non-overlapping occurrences of substring sub in string S[start:end].

    Optional arguments start and end are interpreted as in slice notation.

  classmethod determine_type(stac_json: dict[str, Any]) → CatalogType | None

    Determines the catalog type based on a STAC JSON dict.

    Only applies to Catalogs or Collections

    Parameters:

      stac_json – The STAC JSON dict to determine the catalog type

    Returns:

      The catalog type of the catalog or collection. Will return None if it cannot be determined.

    Return type:

      Optional[CatalogType]

  encode(encoding='utf-8', errors='strict')

    Encode the string using the codec registered for encoding.

    encoding

      The encoding in which to encode the string.

    errors

      The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

  endswith()

    Return True if the string ends with the specified suffix, False otherwise.

    suffix

      A string or a tuple of strings to try.

    start

      Optional start position. Default: start of the string.

    end

      Optional stop position. Default: end of the string.

  expandtabs(tabsize=8)

    Return a copy where all tab characters are expanded using spaces.

    If tabsize is not given, a tab size of 8 characters is assumed.

  find()

    Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

    Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

  format(*args, **kwargs)

    Return a formatted version of the string, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

  format_map(mapping, /)

    Return a formatted version of the string, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

  index()

    Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

    Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

  isalnum()

    Return True if the string is an alpha-numeric string, False otherwise.

    A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

  isalpha()

    Return True if the string is an alphabetic string, False otherwise.

    A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

  isascii()

    Return True if all characters in the string are ASCII, False otherwise.

    ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

  isdecimal()

    Return True if the string is a decimal string, False otherwise.

    A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

  isdigit()

    Return True if the string is a digit string, False otherwise.

    A string is a digit string if all characters in the string are digits and there is at least one character in the string.

  isidentifier()

    Return True if the string is a valid Python identifier, False otherwise.

    Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

  islower()

    Return True if the string is a lowercase string, False otherwise.

    A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

  isnumeric()

    Return True if the string is a numeric string, False otherwise.

    A string is numeric if all characters in the string are numeric and there is at least one character in the string.

  isprintable()

    Return True if all characters in the string are printable, False otherwise.

    A character is printable if repr() may use it in its output.

  isspace()

    Return True if the string is a whitespace string, False otherwise.

    A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

  istitle()

    Return True if the string is a title-cased string, False otherwise.

    In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

  isupper()

    Return True if the string is an uppercase string, False otherwise.

    A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

  join(iterable, /)

    Concatenate any number of strings.

    The string whose method is called is inserted in between each given string. The result is returned as a new string.

    Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

  ljust(width, fillchar=' ', /)

    Return a left-justified string of length width.

    Padding is done using the specified fill character (default is a space).

  lower()

    Return a copy of the string converted to lowercase.

  lstrip(chars=None, /)

    Return a copy of the string with leading whitespace removed.

    If chars is given and not None, remove characters in chars instead.

  static maketrans()

    Return a translation table usable for str.translate().

    If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

  partition(sep, /)

    Partition the string into three parts using the given separator.

    This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

    If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

  removeprefix(prefix, /)

    Return a str with the given prefix string removed if present.

    If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

  removesuffix(suffix, /)

    Return a str with the given suffix string removed if present.

    If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

  replace(old, new, /, count=-1)

    Return a copy with all occurrences of substring old replaced by new.

    > count

    >   Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

    If the optional argument count is given, only the first count occurrences are replaced.

  rfind()

    Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

    Optional arguments start and end are interpreted as in slice notation. Return -1 on failure.

  rindex()

    Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].

    Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

  rjust(width, fillchar=' ', /)

    Return a right-justified string of length width.

    Padding is done using the specified fill character (default is a space).

  rpartition(sep, /)

    Partition the string into three parts using the given separator.

    This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

    If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

  rsplit(sep=None, maxsplit=-1)

    Return a list of the substrings in the string, using sep as the separator string.

    > sep

    >   The separator used to split the string.

    >   When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

    > maxsplit

    >   Maximum number of splits. -1 (the default value) means no limit.

    Splitting starts at the end of the string and works to the front.

  rstrip(chars=None, /)

    Return a copy of the string with trailing whitespace removed.

    If chars is given and not None, remove characters in chars instead.

  split(sep=None, maxsplit=-1)

    Return a list of the substrings in the string, using sep as the separator string.

    > sep

    >   The separator used to split the string.

    >   When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

    > maxsplit

    >   Maximum number of splits. -1 (the default value) means no limit.

    Splitting starts at the front of the string and works to the end.

    Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

  splitlines(keepends=False)

    Return a list of the lines in the string, breaking at line boundaries.

    Line breaks are not included in the resulting list unless keepends is given and true.

  startswith()

    Return True if the string starts with the specified prefix, False otherwise.

    prefix

      A string or a tuple of strings to try.

    start

      Optional start position. Default: start of the string.

    end

      Optional stop position. Default: end of the string.

  strip(chars=None, /)

    Return a copy of the string with leading and trailing whitespace removed.

    If chars is given and not None, remove characters in chars instead.

  swapcase()

    Convert uppercase characters to lowercase and lowercase characters to uppercase.

  title()

    Return a version of the string where each word is titlecased.

    More specifically, words start with uppercased characters and all remaining cased characters have lower case.

  translate(table, /)

    Replace each character in the string using the given translation table.

    > table

    >   Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

    The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

  upper()

    Return a copy of the string converted to uppercase.

  zfill(width, /)

    Pad a numeric string with zeros on the left, to fill a field of the given width.

    The string is never truncated.

# Collection

class pystac.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 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_asset(key: str, asset: Asset) → None

    Adds an Asset to this object.

    Parameters:

      - key – The unique key of this asset.

      - asset – The Asset to add.

  add_child(child: Catalog | Collection, title: str | None = None, strategy: HrefLayoutStrategy | None = None, set_parent: bool = True) → Link

    Adds a link to a child `Catalog` or `Collection`.

    This method will set the child’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:

      - child – The child to add.

      - title – Optional title to give to the `Link`

      - strategy – The layout strategy to use for setting the self href of the child. 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 child as well. Defaults to True.

    Returns:

      The link created for the child

    Return type:

      Link

  add_children(children: Iterable[Catalog | Collection], strategy: HrefLayoutStrategy | None = None) → list[Link]

    Adds links to multiple `Catalog` or ~pystac.Collection objects. This method will set each child’s parent to this object, and their root to this Catalog’s root.

    Parameters:

      - children – The children to add.

      - strategy – The layout strategy to use for setting the self href of the children. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`.

    Returns:

      An array of links created for the children

    Return type:

      List[Link]

  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

  add_items(items: Iterable[Item], strategy: HrefLayoutStrategy | None = None) → list[Link]

    Adds links to multiple `Items`.

    This method will set each item’s parent to this object, and their root to this Catalog’s root.

    Parameters:

      - items – The items to add.

      - strategy – The layout strategy to use for setting the self href of the items. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`.

    Returns:

      A list of links created for the item

    Return type:

      List[Link]

  add_link(link: Link) → None

    Add a link to this object’s set of links.

    Parameters:

      link – The link to add.

  add_links(links: list[Link]) → None

    Add links to this object’s set of links.

    Parameters:

      links – The links to add.

  assets: dict[str, Asset]

    The asset dictionary.

  catalog_type: CatalogType

    The catalog type. Defaults to `CatalogType.ABSOLUTE_PUBLISHED`.

  clear_children() → None

    Removes all children from this catalog.

    Returns:

      Returns `self`

    Return type:

      Catalog

  clear_items() → None

    Removes all items from this catalog.

    Returns:

      Returns `self`

    Return type:

      Catalog

  clear_links(rel: str | RelType | None = None) → None

    Clears all `Link` instances associated with this object.

    Parameters:

      rel – If set, only clear links that match this relationship.

  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

  delete_asset(key: str) → None

    Deletes the asset at the given key, and removes the asset’s data file from the local filesystem.

    It is an error to attempt to delete an asset’s file if it is on a remote filesystem.

    To delete the asset without removing the file, use del item.assets[“key”].

    Parameters:

      key – The unique key of this asset.

  describe(include_hrefs: bool = False, _indent: int = 0) → None

    Prints out information about this Catalog and all contained STACObjects.

    Parameters:

      include_hrefs (bool) – HREF along with the object ID.

  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 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_file(href: str | PathLike[str], stac_io: StacIO | None = None) → C

    Reads a STACObject implementation from a file.

    Parameters:

      - href – The HREF to read the object from.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the default instance.

    Returns:

      The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.

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

    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

    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

  fully_resolve() → None

    Resolves every link in this catalog.

    Useful if, e.g., you’d like to read a catalog from a filesystem, upgrade every object in the catalog to the latest STAC version, and save it back to the filesystem. By default, `save()` skips unresolved links.

  generate_subcatalogs(template: str, defaults: dict[str, Any] | None = None, parent_ids: list[str] | None = None) → list[Catalog]

    Walks through the catalog and generates subcatalogs for items based on the template string.

    See `LayoutTemplate` for details on the construction of template strings. This template string will be applied to the items, and subcatalogs will be created that separate and organize the items based on template values.

    Parameters:

      - template – A template string that can be consumed by a `LayoutTemplate`

      - defaults – Default values for the template variables that will be used if the property cannot be found on the item.

      - parent_ids – Optional list of the parent catalogs’ identifiers. If the bottom-most subcatalogs already match the template, no subcatalog is added.

    Returns:

      List of new catalogs created

    Return type:

      list[Catalog]

  get_all_collections() → Iterable[Collection]

    Get all collections from this catalog and all subcatalogs. Will traverse any subcatalogs recursively.

  get_all_items() → Iterator[Item]

    DEPRECATED.

    Deprecated since version 1.8: Use `pystac.Catalog.get_items(recursive=True)` instead.

    Get all items from this catalog and all subcatalogs. Will traverse any subcatalogs recursively.

    Returns:

      All items that belong to this catalog, and all

        catalogs or collections connected to this catalog through child links.

    Return type:

      Generator[Item]

  get_assets(media_type: str | MediaType | None = None, role: str | None = None) → dict[str, Asset]

    Get this object’s assets.

    Parameters:

      - media_type – If set, filter the assets such that only those with a matching `media_type` are returned.

      - role – If set, filter the assets such that only those with a matching `role` are returned.

    Returns:

      A dictionary of assets that match `media_type`

        and/or `role` if set or else all of this object’s assets.

    Return type:

      Dict[str, Asset]

  get_child(id: str, recursive: bool = False, sort_links_by_id: bool = True) → Catalog | Collection | None

    Gets the child of this catalog with the given ID, if it exists.

    Parameters:

      - id – The ID of the child to find.

      - recursive – If True, search this catalog and all children for the item; otherwise, only search the children of this catalog. Defaults to False.

      - sort_links_by_id – If True, links containing the ID will be checked first. If links do not contain the ID then setting this to False will improve performance. Defaults to True.

    Returns:

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

    Return type:

      Catalog or Collection or None

  get_child_links() → list[Link]

    Return all child links of this catalog.

    Returns:

      List of links of this catalog with `rel == 'child'`

    Return type:

      List[Link]

  get_children() → Iterable[Catalog | Collection]

    Return all children of this catalog.

    Returns:

      Iterable of children whose parent is this catalog.

    Return type:

      Iterable[Catalog or Collection]

  get_collections() → Iterable[Collection]

    Return all children of this catalog that are `Collection` instances.

  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

  get_item_links() → list[Link]

    Return all item links of this catalog.

    Returns:

      List of links of this catalog with `rel == 'item'`

    Return type:

      List[Link]

  get_items(*ids: str, recursive: bool = False) → Iterator[Item]

    Return all items or specific items of this catalog.

    Parameters:

      - *ids – The IDs of the items to include.

      - recursive – If True, search this catalog and all children for the item; otherwise, only search the items of this catalog. Defaults to False.

    Returns:

      Generator of items whose parent is this catalog, and

        (if recursive) all catalogs or collections connected to this catalog through child links.

    Return type:

      Iterator[Item]

  get_links(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → list[Link]

    Gets the `Link` instances associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      A list of links that match `rel` and/

        or `media_type` if set, or else all links associated with this object.

    Return type:

      List[`Link`]

  get_parent() → Catalog | None

    Get the `Catalog` or `Collection` to the parent for this object. The root is represented by a `Link` with `rel == 'parent'`.

    Returns:

      The parent object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root() → Catalog | None

    Get the `Catalog` or `Collection` to the root for this object. The root is represented by a `Link` with `rel == 'root'`.

    Returns:

      The root object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root_link() → Link | None

    Get the `Link` representing the root for this object.

    Returns:

      The root link for this object, or `None` if no root link is set.

    Return type:

      `Link` or None

  get_self_href() → str | None

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Returns:

      The absolute HREF of this object, or `None` if there is no self link defined.

    Return type:

      str or None

    Note

    A self link can exist for objects, even if the link is not read or written to the JSON-serialized version of the object. Any object read from `STACObject.from_file` will have the HREF the file was read from set as it’s self HREF. All self links have absolute (as opposed to relative) HREFs.

  get_single_link(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → Link | None

    Get a single `Link` instance associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      First link that matches `rel`

        and/or `media_type`, or else the first link associated with this object.

    Return type:

      `Link` | None

  get_stac_objects(rel: str | RelType, typ: type[STACObject] | None = None, modify_links: Callable[[list[Link]], list[Link]] | None = None) → Iterable[STACObject]

    Gets the `STACObject` instances that are linked to by links with their `rel` property matching the passed in argument.

    Parameters:

      - rel – The relation to match each `Link`’s `rel` property against.

      - typ – If not `None`, objects will only be yielded if they are instances of `typ`.

      - modify_links – A function that modifies the list of links before they are iterated over. For instance, this option can be used to sort the list so that links matching a particular pattern are earlier in the iterator.

    Returns:

      A possibly empty iterable of STACObjects that are

        connected to this object through links with the given `rel` and are of type `typ` (if given).

    Return type:

      Iterable[STACObject]

  id: str

    Identifier for the collection.

  is_relative() → bool
  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.

  make_all_asset_hrefs_absolute() → None

    Recursively makes all the HREFs of assets in this catalog absolute

  make_all_asset_hrefs_relative() → None

    Recursively makes all the HREFs of assets in this catalog relative

  make_asset_hrefs_absolute() → Assets

    Modify each asset’s HREF to be absolute.

    Any asset HREFs that are relative will be modified to absolute based on this item’s self HREF.

    Returns:

      self

    Return type:

      Assets

  make_asset_hrefs_relative() → Assets

    Modify each asset’s HREF to be relative to this object’s self HREF.

    Returns:

      self

    Return type:

      Item

  map_assets(asset_mapper: Callable[[str, Asset], Asset | tuple[str, Asset] | dict[str, Asset]]) → Catalog

    Creates a copy of a catalog, with each Asset for each Item passed through the asset_mapper function.

    Parameters:

      asset_mapper – A function that takes in a key and an Asset, and returns either an Asset, a (key, Asset), or a dictionary of Assets with unique keys. The Asset that is passed into the item_mapper is a copy, so the method can mutate it safely.

    Returns:

      A full copy of this catalog, with assets manipulated according to the asset_mapper function.

    Return type:

      Catalog

  map_items(item_mapper: Callable[[Item], Item | list[Item]]) → Catalog

    Creates a copy of a catalog, with each item passed through the item_mapper function.

    Parameters:

      item_mapper – A function that takes in an item, and returns either an item or list of items. The item that is passed into the item_mapper is a copy, so the method can mutate it safely.

    Returns:

      A full copy of this catalog, with items manipulated according to the item_mapper function.

    Return type:

      Catalog

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

    Returns a boolean indicating whether the given dictionary represents a valid instance of this `STACObject` subclass.

    Parameters:

      d – A dictionary to identify

  normalize_and_save(root_href: str, catalog_type: CatalogType | None = None, strategy: HrefLayoutStrategy | None = None, stac_io: StacIO | None = None, skip_unresolved: bool = False) → None

    Normalizes link HREFs to the given root_href, and saves the catalog.

    This is a convenience method that simply calls `Catalog.normalize_hrefs` and `Catalog.save` in sequence.

    Parameters:

      - root_href – The absolute HREF that all links will be normalized against.

      - catalog_type – The catalog type that dictates the structure of the catalog to save. Use a member of `CatalogType`. Defaults to the root catalog.catalog_type or the current catalog catalog_type if there is no root catalog.

      - strategy – The layout strategy to use in setting the HREFS for this catalog. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`

      - stac_io – Optional instance of `StacIO` to use. If not provided, will use the instance set while reading in the catalog, or the default instance if this is not available.

      - skip_unresolved – Skip unresolved links when normalizing the tree. Defaults to False. Because unresolved links are not saved, this argument can be used to normalize and save only newly-added objects.

  normalize_hrefs(root_href: str, strategy: HrefLayoutStrategy | None = None, skip_unresolved: bool = False) → None

    Normalize HREFs will regenerate all link HREFs based on an absolute root_href and the canonical catalog layout as specified in the STAC specification’s best practices.

    This method mutates the entire catalog tree, unless `skip_unresolved` is True, in which case only resolved links are modified. This is useful in the case when you have loaded a large catalog and you’ve added a few items/children, and you only want to update those newly-added objects, not the whole tree.

    Parameters:

      - root_href – The absolute HREF that all links will be normalized against.

      - strategy – The layout strategy to use in setting the HREFS for this catalog. If not provided, defaults to the layout strategy of the parent or root and falls back to `BestPracticesLayoutStrategy`

      - skip_unresolved – Skip unresolved links when normalizing the tree. Defaults to False.

    See:

      STAC best practices document for the canonical layout of a STAC.

  providers: list[Provider] | None

    Optional list of providers of this Collection.

  remove_child(child_id: str) → None

    Removes a child from this catalog.

    Parameters:

      child_id – The ID of the child to remove.

  remove_hierarchical_links(add_canonical: bool = False) → list[Link]

    Removes all hierarchical links from this object.

    See `pystac.link.HIERARCHICAL_LINKS` for a list of all hierarchical links. If the object has a `self` href and `add_canonical` is True, a link with `rel="canonical"` is added.

    Parameters:

      add_canonical – If true, and this item has a `self` href, that href is used to build a `canonical` link.

    Returns:

      All removed links

    Return type:

      List[Link]

  remove_item(item_id: str) → None

    Removes an item from this catalog.

    Parameters:

      item_id – The ID of the item to remove.

  remove_links(rel: str | RelType) → None

    Remove links to this object’s set of links that match the given `rel`.

    Parameters:

      rel – The `Link` `rel` to match on.

  resolve_links() → None

    Ensure all STACObjects linked to by this STACObject are resolved. This is important for operations such as changing HREFs.

    This method mutates the entire catalog tree.

  save(catalog_type: CatalogType | None = None, dest_href: str | None = None, stac_io: StacIO | None = None) → None

    Save this catalog and all it’s children/item to files determined by the object’s self link HREF or a specified path.

    Parameters:

      - catalog_type – The catalog type that dictates the structure of the catalog to save. Use a member of `CatalogType`. If not supplied, the catalog_type of this catalog will be used. If that attribute is not set, an exception will be raised.

      - dest_href – The location where the catalog is to be saved. If not supplied, the catalog’s self link HREF is used to determine the location of the catalog file and children’s files.

      - stac_io – Optional instance of `StacIO` to use. If not provided, will use the instance set while reading in the catalog, or the default instance if this is not available.

    Note

    If the catalog type is `CatalogType.ABSOLUTE_PUBLISHED`, all self links will be included, and hierarchical links be absolute URLs. If the catalog type is `CatalogType.RELATIVE_PUBLISHED`, this catalog’s self link will be included, but no child catalog will have self links, and hierarchical links will be relative URLs If the catalog type is `CatalogType.SELF_CONTAINED`, no self links will be included and hierarchical links will be relative URLs.

  save_object(include_self_link: bool = True, dest_href: str | None = None, stac_io: StacIO | None = None) → None

    Saves this `STACObject` to it’s ‘self’ HREF.

    Parameters:

      - include_self_link – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.

      - dest_href – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the instance set on the object’s root if available, otherwise will use the default instance.

    Raises:

      STACError – If no self href is set, this error will be raised.

    Note

    When to include a self link is described in the Use of Links section of the STAC best practices document

  property self_href: str

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Raises:

      ValueError – If the self_href is not set, this method will throw a ValueError. Use get_self_href if there may not be an HREF set.

  set_parent(parent: Catalog | None) → None

    Sets the parent `Catalog` or `Collection` for this object.

    Parameters:

      parent – The parent object to set. Passing in None will clear the parent.

  set_root(root: Catalog | None) → None

    Sets the root `Catalog` or `Collection` for this object.

    Parameters:

      root – The root object to set. Passing in None will clear the root.

  set_self_href(href: str | None) → None

    Sets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Parameters:

      href – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.

  stac_extensions: list[str]

    List of extensions the Collection implements.

  strategy: HrefLayoutStrategy | None
  summaries: Summaries

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

  target_in_hierarchy(target: str | STACObject) → bool

    Determine if target is somewhere in the hierarchical link tree of a STACObject.

    Parameters:

      target – A string or STACObject to search for

    Returns:

      Returns True if the target was found in the hierarchical link tree

        for the current STACObject

    Return type:

      bool

  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.

  validate(validator: STACValidator | None = None) → list[Any]

    Validate this STACObject.

    Returns a list of validation results, which depends on the validation implementation. For JSON Schema validation (default validator), this will be a list of schema URIs that were used during validation.

    Parameters:

      validator – A custom validator to use for validation of the object. If omitted, the default validator from `RegisteredValidator` will be used instead.

    Raises:

      STACValidationError –

  validate_all(max_items: int | None = None, recursive: bool = True) → int

    Validates each catalog, collection, item contained within this catalog.

    Walks through the children and items of the catalog and validates each stac object.

    Parameters:

      - max_items – The maximum number of STAC items to validate. Default is None which means, validate them all.

      - recursive – Whether to validate catalog, collections, and items contained within child objects.

    Returns:

      Number of STAC items validated.

    Return type:

      int

    Raises:

      STACValidationError – Raises this error on any item that is invalid. Will raise on the first invalid stac object encountered.

  walk() → Iterable[tuple[Catalog, Iterable[Catalog], Iterable[Item]]]

    Walks through children and items of catalogs.

    For each catalog in the STAC’s tree rooted at this catalog (including this catalog itself), it yields a 3-tuple (root, subcatalogs, items). The root in that 3-tuple refers to the current catalog being walked, the subcatalogs are any catalogs or collections for which the root is a parent, and items represents any items that have the root as a parent.

    This has similar functionality to Python’s `os.walk()`.

    Returns:

      A generator that yields a 3-tuple (parent_catalog, children, items).

    Return type:

      Generator[(Catalog, Generator[Catalog], Generator[Item])]

# Extent

class pystac.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

# SpatialExtent

class pystac.SpatialExtent(bboxes: list[list[float | int]] | Sequence[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

# TemporalExtent

class pystac.TemporalExtent(intervals: list[list[datetime]] | list[list[datetime | None]] | Sequence[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

# ProviderRole

class pystac.ProviderRole(*values)

  Enumerates the allows values of the Provider “role” field.

  HOST = 'host'
  LICENSOR = 'licensor'
  PROCESSOR = 'processor'
  PRODUCER = 'producer'

# Provider

class pystac.Provider(name: str, description: str | None = None, roles: list[ProviderRole] | None = None, url: str | None = None, extra_fields: dict[str, Any] | None = None)

  Provides information about a provider of STAC data. A provider is any of the organizations that captured or processed the content of the collection and therefore influenced the data offered by this collection. May also include information about the final storage provider hosting the data.

  Parameters:

    - name – The name of the organization or the individual.

    - description – Optional multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information.

    - roles – Optional roles of the provider. Any of licensor, producer, processor or host.

    - url – Optional homepage on which the provider describes the dataset and publishes contact information.

    - extra_fields – Optional dictionary containing additional top-level fields defined on the Provider object.

  description: str | None

    Optional multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information.

  extra_fields: dict[str, Any]

    Dictionary containing additional top-level fields defined on the Provider object.

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

    Constructs a Provider from a dict.

    Returns:

      The Provider deserialized from the JSON dict.

    Return type:

      Provider

  name: str

    The name of the organization or the individual.

  roles: list[ProviderRole] | None

    Optional roles of the provider. Any of licensor, producer, processor or host.

  to_dict() → dict[str, Any]

    Returns this provider as a dictionary.

    Returns:

      A serialization of the Provider.

    Return type:

      dict

  url: str | None

    Optional homepage on which the provider describes the dataset and publishes contact information.

# Summaries

class pystac.Summaries(summaries: dict[str, Any], maxcount: int = 25)
  add(prop_key: str, summary: list[Any] | RangeSummary[Any] | dict[str, Any]) → None
  clone() → Summaries

    Clones this object.

    Returns:

      The clone of this object

    Return type:

      Summaries

  combine(summaries: Summaries) → None
  classmethod empty() → Summaries
  get_list(prop: str) → list[Any] | None
  get_range(prop: str) → RangeSummary[Any] | None
  get_schema(prop: str) → dict[str, Any] | None
  is_empty() → bool
  lists: dict[str, list[Any]]
  maxcount: int
  other: dict[str, Any]
  ranges: dict[str, RangeSummary[Any]]
  remove(prop_key: str) → None
  schemas: dict[str, dict[str, Any]]
  to_dict() → dict[str, Any]
  update(summaries: Summaries) → None

# Item

class pystac.Item(id: str, geometry: dict[str, Any] | None, bbox: list[float] | None, datetime: Datetime | None, properties: dict[str, Any], start_datetime: Datetime | None = None, end_datetime: Datetime | None = None, stac_extensions: list[str] | None = None, href: str | None = None, collection: str | Collection | None = None, extra_fields: dict[str, Any] | None = None, assets: dict[str, Asset] | None = None)

  An Item is the core granular entity in a STAC, containing the core metadata that enables any client to search or crawl online catalogs of spatial ‘assets’ - satellite imagery, derived data, DEM’s, etc.

  Parameters:

    - id – Provider identifier. Must be unique within the STAC.

    - geometry – Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).

    - bbox – Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array must be 2*n where n is the number of dimensions. Could also be None in the case of a null geometry.

    - datetime – datetime associated with this item. If None, a start_datetime and end_datetime must be supplied.

    - properties – A dictionary of additional metadata for the item.

    - start_datetime – Optional inclusive start datetime, part of common metadata. This value will override any start_datetime key in properties.

    - end_datetime – Optional inclusive end datetime, part of common metadata. This value will override any end_datetime key in properties.

    - stac_extensions – Optional list of extensions the Item implements.

    - href – Optional HREF for this item, which be set as the item’s self link’s HREF.

    - collection – The Collection or Collection ID that this item belongs to.

    - extra_fields – Extra fields that are part of the top-level JSON properties of the Item.

    - assets – A dictionary mapping string keys to `Asset` objects. All `Asset` values in the dictionary will have their `owner` attribute set to the created Item.

  STAC_OBJECT_TYPE: STACObjectType = 'Feature'
  add_asset(key: str, asset: Asset) → None

    Adds an Asset to this object.

    Parameters:

      - key – The unique key of this asset.

      - asset – The Asset to add.

  add_derived_from(*items: Item | str) → Item

    Add one or more items that this is derived from.

    This method will add to any existing “derived_from” links.

    Parameters:

      items – Items (or href of items) to add to derived_from links.

    Returns:

      self

    Return type:

      Item

  add_link(link: Link) → None

    Add a link to this object’s set of links.

    Parameters:

      link – The link to add.

  add_links(links: list[Link]) → None

    Add links to this object’s set of links.

    Parameters:

      links – The links to add.

  assets: dict[str, Asset]

    Dictionary of `Asset` objects, each with a unique key.

  bbox: list[float] | None

    Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array is 2*n where n is the number of dimensions. Could also be None in the case of a null geometry.

  clear_links(rel: str | RelType | None = None) → None

    Clears all `Link` instances associated with this object.

    Parameters:

      rel – If set, only clear links that match this relationship.

  clone() → Item

    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

  collection: Collection | None

    `Collection` to which this Item belongs, if any.

  collection_id: str | None

    The Collection ID that this item belongs to, if any.

  property common_metadata: CommonMetadata

    Access the item’s common metadata fields as a `CommonMetadata` object.

  datetime: Datetime | None

    Datetime associated with this item. If `None`, then `start_datetime` and `end_datetime` in `common_metadata` will supply the datetime range of the Item.

  delete_asset(key: str) → None

    Deletes the asset at the given key, and removes the asset’s data file from the local filesystem.

    It is an error to attempt to delete an asset’s file if it is on a remote filesystem.

    To delete the asset without removing the file, use del item.assets[“key”].

    Parameters:

      key – The unique key of this asset.

  property ext: ItemExt

    Accessor for extension classes on this item

    Example:

        item.ext.proj.code = "EPSG:4326"

  extra_fields: dict[str, Any]

    Extra fields that are part of the top-level JSON fields the Item.

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

    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 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_file(href: str | PathLike[str], stac_io: StacIO | None = None) → S

    Reads a STACObject implementation from a file.

    Parameters:

      - href – The HREF to read the object from.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the default instance.

    Returns:

      The specific STACObject implementation class that is represented by the JSON read from the file located at HREF.

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

    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

  geometry: dict[str, Any] | None

    Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).

  get_assets(media_type: str | MediaType | None = None, role: str | None = None) → dict[str, Asset]

    Get this object’s assets.

    Parameters:

      - media_type – If set, filter the assets such that only those with a matching `media_type` are returned.

      - role – If set, filter the assets such that only those with a matching `role` are returned.

    Returns:

      A dictionary of assets that match `media_type`

        and/or `role` if set or else all of this object’s assets.

    Return type:

      Dict[str, Asset]

  get_collection() → Collection | None

    Gets the collection of this item, if one exists.

    Returns:

      If this item belongs to a collection, returns a reference to the collection. Otherwise returns None.

    Return type:

      Collection or None

  get_datetime(asset: Asset | None = None) → Datetime | None

    Gets an Item or an Asset datetime.

    If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.

    Returns:

      datetime or None

  get_derived_from() → list[Item]

    Get the items that this is derived from.

    Returns:

      Returns a reference to the derived_from items.

    Return type:

      List[Item]

  get_links(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → list[Link]

    Gets the `Link` instances associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      A list of links that match `rel` and/

        or `media_type` if set, or else all links associated with this object.

    Return type:

      List[`Link`]

  get_parent() → Catalog | None

    Get the `Catalog` or `Collection` to the parent for this object. The root is represented by a `Link` with `rel == 'parent'`.

    Returns:

      The parent object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root() → Catalog | None

    Get the `Catalog` or `Collection` to the root for this object. The root is represented by a `Link` with `rel == 'root'`.

    Returns:

      The root object for this object, or `None` if no root link is set.

    Return type:

      Catalog, Collection, or None

  get_root_link() → Link | None

    Get the `Link` representing the root for this object.

    Returns:

      The root link for this object, or `None` if no root link is set.

    Return type:

      `Link` or None

  get_self_href() → str | None

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Returns:

      The absolute HREF of this object, or `None` if there is no self link defined.

    Return type:

      str or None

    Note

    A self link can exist for objects, even if the link is not read or written to the JSON-serialized version of the object. Any object read from `STACObject.from_file` will have the HREF the file was read from set as it’s self HREF. All self links have absolute (as opposed to relative) HREFs.

  get_single_link(rel: str | RelType | None = None, media_type: str | MediaType | None | Iterable[str | MediaType | None] = None) → Link | None

    Get a single `Link` instance associated with this object.

    Parameters:

      - rel – If set, filter links such that only those matching this relationship are returned.

      - media_type – If set, filter the links such that only those matching media_type are returned. media_type can be a single value or a list of values.

    Returns:

      First link that matches `rel`

        and/or `media_type`, or else the first link associated with this object.

    Return type:

      `Link` | None

  get_stac_objects(rel: str | RelType, typ: type[STACObject] | None = None, modify_links: Callable[[list[Link]], list[Link]] | None = None) → Iterable[STACObject]

    Gets the `STACObject` instances that are linked to by links with their `rel` property matching the passed in argument.

    Parameters:

      - rel – The relation to match each `Link`’s `rel` property against.

      - typ – If not `None`, objects will only be yielded if they are instances of `typ`.

      - modify_links – A function that modifies the list of links before they are iterated over. For instance, this option can be used to sort the list so that links matching a particular pattern are earlier in the iterator.

    Returns:

      A possibly empty iterable of STACObjects that are

        connected to this object through links with the given `rel` and are of type `typ` (if given).

    Return type:

      Iterable[STACObject]

  id: str

    Provider identifier. Unique within the STAC.

  links: list[Link]

    A list of `Link` objects representing all links associated with this Item.

  make_asset_hrefs_absolute() → Assets

    Modify each asset’s HREF to be absolute.

    Any asset HREFs that are relative will be modified to absolute based on this item’s self HREF.

    Returns:

      self

    Return type:

      Assets

  make_asset_hrefs_relative() → Assets

    Modify each asset’s HREF to be relative to this object’s self HREF.

    Returns:

      self

    Return type:

      Item

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

    Returns a boolean indicating whether the given dictionary represents a valid instance of this `STACObject` subclass.

    Parameters:

      d – A dictionary to identify

  properties: dict[str, Any]

    A dictionary of additional metadata for the Item.

  remove_derived_from(item_id: str) → None

    Remove an item that this is derived from.

    This method will remove from existing “derived_from” links.

    Parameters:

      item_id – ID of item to remove from derived_from links.

  remove_hierarchical_links(add_canonical: bool = False) → list[Link]

    Removes all hierarchical links from this object.

    See `pystac.link.HIERARCHICAL_LINKS` for a list of all hierarchical links. If the object has a `self` href and `add_canonical` is True, a link with `rel="canonical"` is added.

    Parameters:

      add_canonical – If true, and this item has a `self` href, that href is used to build a `canonical` link.

    Returns:

      All removed links

    Return type:

      List[Link]

  remove_links(rel: str | RelType) → None

    Remove links to this object’s set of links that match the given `rel`.

    Parameters:

      rel – The `Link` `rel` to match on.

  resolve_links() → None

    Ensure all STACObjects linked to by this STACObject are resolved. This is important for operations such as changing HREFs.

    This method mutates the entire catalog tree.

  save_object(include_self_link: bool = True, dest_href: str | None = None, stac_io: StacIO | None = None) → None

    Saves this `STACObject` to it’s ‘self’ HREF.

    Parameters:

      - include_self_link – If this is true, include the ‘self’ link with this object. Otherwise, leave out the self link.

      - dest_href – Optional HREF to save the file to. If None, the object will be saved to the object’s self href.

      - stac_io – Optional instance of StacIO to use. If not provided, will use the instance set on the object’s root if available, otherwise will use the default instance.

    Raises:

      STACError – If no self href is set, this error will be raised.

    Note

    When to include a self link is described in the Use of Links section of the STAC best practices document

  property self_href: str

    Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Raises:

      ValueError – If the self_href is not set, this method will throw a ValueError. Use get_self_href if there may not be an HREF set.

  set_collection(collection: Collection | None) → Item

    Set the collection of this item.

    This method will replace any existing Collection link and attribute for this item.

    Parameters:

      collection – The collection to set as this item’s collection. If None, will clear the collection.

    Returns:

      self

    Return type:

      Item

  set_datetime(datetime: Datetime, asset: Asset | None = None) → None

    Set an Item or an Asset datetime.

    If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

  set_parent(parent: Catalog | None) → None

    Sets the parent `Catalog` or `Collection` for this object.

    Parameters:

      parent – The parent object to set. Passing in None will clear the parent.

  set_root(root: Catalog | None) → None

    Sets the root `Catalog` or `Collection` for this object.

    Parameters:

      root – The root object to set. Passing in None will clear the root.

  set_self_href(href: str | None) → None

    Sets the absolute HREF that is represented by the `rel == 'self'` `Link`.

    Changing the self HREF of the item will ensure that all asset HREFs remain valid. If asset HREFs are relative, the HREFs will change to point to the same location based on the new item self HREF, either by making them relative to the new location or making them absolute links if the new location does not share the same protocol as the old location.

    Parameters:

      href – The absolute HREF of this object. If the given HREF is not absolute, it will be transformed to an absolute HREF based on the current working directory. If this is None the call will clear the self HREF link.

  stac_extensions: list[str]

    List of extensions the Item implements.

  target_in_hierarchy(target: str | STACObject) → bool

    Determine if target is somewhere in the hierarchical link tree of a STACObject.

    Parameters:

      target – A string or STACObject to search for

    Returns:

      Returns True if the target was found in the hierarchical link tree

        for the current STACObject

    Return type:

      bool

  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.

  validate(validator: STACValidator | None = None) → list[Any]

    Validate this STACObject.

    Returns a list of validation results, which depends on the validation implementation. For JSON Schema validation (default validator), this will be a list of schema URIs that were used during validation.

    Parameters:

      validator – A custom validator to use for validation of the object. If omitted, the default validator from `RegisteredValidator` will be used instead.

    Raises:

      STACValidationError –

# Asset

class pystac.Asset(href: str, title: str | None = None, description: str | None = None, media_type: str | None = None, roles: list[str] | None = None, extra_fields: dict[str, Any] | None = None)

  An object that contains a link to data associated with an Item or Collection that can be downloaded or streamed.

  Parameters:

    - href – Link to the asset object. Relative and absolute links are both allowed.

    - title – Optional displayed title for clients and users.

    - description – A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

    - media_type – Optional description of the media type. Registered Media Types are preferred. See `MediaType` for common media types.

    - roles – Optional, Semantic roles (i.e. thumbnail, overview, data, metadata) of the asset.

    - extra_fields – Optional, additional fields for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.

  clone() → Asset

    Clones this asset. Makes a `deepcopy` of the `extra_fields`.

    Returns:

      The clone of this asset.

    Return type:

      Asset

  property common_metadata: CommonMetadata

    Access the asset’s common metadata fields as a `CommonMetadata` object.

  copy(href: str) → Asset

    Copies this asset’s file to a new location on the local filesystem, setting the asset href accordingly.

    Modifies the asset in place, and returns the same asset.

    Parameters:

      href – The new asset location. Must be a local path. If relative it must be relative to the owner object.

    Returns:

      The asset with the updated href.

    Return type:

      Asset

  delete() → None

    Delete this asset’s file. Does not delete the asset from the item that owns it. See `delete_asset()` for that.

    Does not modify the asset.

  description: str | None

    A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

  property ext: AssetExt

    Accessor for extension classes on this asset

    Example:

        asset.ext.proj.code = "EPSG:4326"

  extra_fields: dict[str, Any]

    Optional, additional fields for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.

  classmethod from_dict(d: dict[str, Any]) → A

    Constructs an Asset from a dict.

    Returns:

      The Asset deserialized from the JSON dict.

    Return type:

      Asset

  get_absolute_href() → str | None

    Gets the absolute href for this asset, if possible.

    If this Asset has no associated Item, and the asset HREF is a relative path,

      this method will return `None`. If the Item that owns the Asset has no self HREF, this will also return `None`.

    Returns:

      The absolute HREF of this asset, or None if an absolute HREF could not

        be determined.

    Return type:

      str

  has_role(role: str) → bool

    Check if a role exists in the Asset role list.

    Parameters:

      role – Role to check for existence.

    Returns:

      True if role exists, else False.

    Return type:

      bool

  href: str

    Link to the asset object. Relative and absolute links are both allowed.

  media_type: str | None

    Optional description of the media type. Registered Media Types are preferred. See `MediaType` for common media types.

  move(href: str) → Asset

    Moves this asset’s file to a new location on the local filesystem, setting the asset href accordingly.

    Modifies the asset in place, and returns the same asset.

    Parameters:

      href – The new asset location. Must be a local path. If relative it must be relative to the owner object.

    Returns:

      The asset with the updated href.

    Return type:

      Asset

  owner: Assets | None

    The `Item` or `Collection` that this asset belongs to, or `None` if it has no owner.

  roles: list[str] | None

    Optional, Semantic roles (i.e. thumbnail, overview, data, metadata) of the asset.

  set_owner(obj: Assets) → None

    Sets the owning item of this Asset.

    The owning item will be used to resolve relative HREFs of this asset.

    Parameters:

      obj – The Collection or Item that owns this asset.

  title: str | None

    Optional displayed title for clients and users.

  to_dict() → dict[str, Any]

    Returns this Asset as a dictionary.

    Returns:

      A serialization of the Asset.

    Return type:

      dict

# ItemAssetDefinition

class pystac.ItemAssetDefinition(properties: dict[str, Any], owner: Collection | None = None)

  Implementation of the Item Asset Definition Object for use as values in the `item_assets` dict.

  apply(title: str | None, description: str | None, media_type: str | None, roles: list[str] | None, extra_fields: dict[str, Any] | None = None) → None

    Sets the properties for this asset definition.

    Parameters:

      - title – Displayed title for clients and users.

      - description – Description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

      - media_type – media type of the asset.

      - roles – semantic roles of the asset, similar to the use of rel in links.

      - extra_fields – Additional fields on the asset definition, e.g. from extensions.

  classmethod create(title: str | None, description: str | None, media_type: str | None, roles: list[str] | None, extra_fields: dict[str, Any] | None = None) → ItemAssetDefinition

    Creates a new asset definition.

    Parameters:

      - title – Displayed title for clients and users.

      - description – Description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

      - media_type – media type of the asset.

      - roles – semantic roles of the asset, similar to the use of rel in links.

      - extra_fields – Additional fields on the asset definition, e.g. from extensions.

  create_asset(href: str) → Asset

    Creates a new `Asset` instance using the fields from this `ItemAssetDefinition` and the given `href`.

  property description: str | None

    Gets or sets a description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

  property ext: ItemAssetExt

    Accessor for extension classes on this item_asset

    Example:

        collection.item_assets["data"].ext.proj.epsg = 4326

  property media_type: str | None

    Gets or sets the media type of the asset.

  owner: Collection | None
  properties: dict[str, Any]
  property roles: list[str] | None

    Gets or sets the semantic roles of the asset, similar to the use of rel in links.

  set_owner(obj: Collection) → None

    Sets the owning item of this ItemAssetDefinition.

    The owning item will be used to resolve relative HREFs of this asset.

    Parameters:

      obj – The Collection that owns this asset.

  property title: str | None

    Gets or sets the displayed title for clients and users.

  to_dict() → dict[str, Any]

    Returns a dictionary representing this `ItemAssetDefinition`.

# CommonMetadata

class pystac.CommonMetadata(object: Asset | Item)

  Object containing fields that are not included in core item schema but are still commonly used. All attributes are defined within the properties of this item and are optional

  Parameters:

    properties – Dictionary of attributes that is the Item’s properties

  property constellation: str | None

    Gets or set the name of the constellation associate with an object.

  property created: datetime | None

    Get or set the metadata file’s creation date. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string.

    Note

    `created` has a different meaning depending on the type of STAC object. On an `Item`, it refers to the creation time of the metadata. On an `Asset`, it refers to the creation time of the actual data linked to in `href`.

  property description: str | None

    Gets or set the object’s description.

  property end_datetime: datetime | None

    Get or set the item’s end_datetime.

    Note

    `end_datetime` is an inclusive datetime.

  property gsd: float | None

    Gets or sets the Ground Sample Distance at the sensor.

  property instruments: list[str] | None

    Gets or sets the names of the instruments used.

  property keywords: list[str] | None

    Get or set the keywords describing the STAC entity.

  property license: str | None

    Get or set the current license. License should be provided as a SPDX License identifier, or other. If object includes data with multiple different licenses, use other and add a link for each.

    Note

    The licenses various and proprietary are deprecated.

  property mission: str | None

    Gets or set the name of the mission associated with an object.

  object: Asset | Item

    The object from which common metadata is obtained.

  property platform: str | None

    Gets or set the object’s platform attribute.

  property providers: list[Provider] | None

    Get or set a list of the object’s providers.

  property roles: list[str] | None

    Get or set the semantic roles of the entity.

  property start_datetime: datetime | None

    Get or set the object’s start_datetime.

    Note

    `start_datetime` is an inclusive datetime.

  property title: str | None

    Gets or set the object’s title.

  property updated: datetime | None

    Get or set the metadata file’s update date. All datetime attributes have setters that can take either a string or a datetime, but always stores the attribute as a string

    Note

    `updated` has a different meaning depending on the type of STAC object. On an `Item`, it refers to the update time of the metadata. On an `Asset`, it refers to the update time of the actual data linked to in `href`.

# ItemCollection

class pystac.ItemCollection(items: Iterable[Item | dict[str, Any]], extra_fields: dict[str, Any] | None = None, clone_items: bool = True)

  Implementation of a GeoJSON FeatureCollection whose features are all STAC Items, as defined by STAC API - ItemCollection Fragment.

  All `Item` instances passed to the `ItemCollection` instance during instantiation are cloned and have their `"root"` URL cleared. Instances of this class implement the abstract methods of `typing.Collection` and can also be added together (see below for examples using these methods).

  Any additional top-level fields in the FeatureCollection are retained in `extra_fields` by the `from_dict()` and `from_file()` methods and will be present in the serialized file from `save_object()`.

  Parameters:

    - items – List of `Item` instances to include in the `ItemCollection`.

    - extra_fields – Dictionary of additional top-level fields included in the `ItemCollection`.

    - clone_items – Optional flag indicating whether `Item` instances should be cloned before storing in the `ItemCollection`. Setting to `False` will result in faster instantiation, but changes made to `Item` instances in the `ItemCollection` will mutate the original `Item`. Defaults to `True`.

  Examples

  Loop over all items in the :class`ItemCollection`

      >>> item_collection: ItemCollection = ...
      >>> for item in item_collection:
      ...     ...

  Get the number of `Item` instances in the `ItemCollection`

      >>> length: int = len(item_collection)

  Check if an `Item` is in the `ItemCollection`. Note that the `clone_items` argument must be `False` for this to return `True`, since equality of PySTAC objects is currently evaluated using default object equality (i.e. `item_1 is item_2`).

      >>> item: Item = ...
      >>> item_collection = ItemCollection(items=[item], clone_items=False)
      >>> assert item in item_collection

  Combine `ItemCollection` instances

      >>> item_1: Item = ...
      >>> item_2: Item = ...
      >>> item_3: Item = ...
      >>> item_collection_1 = ItemCollection(items=[item_1, item_2])
      >>> item_collection_2 = ItemCollection(items=[item_2, item_3])
      >>> combined = item_collection_1 + item_collection_2
      >>> assert len(combined) == 4
      # If an item is present in both ItemCollections it will occur twice

  clone() → ItemCollection

    Creates a clone of this instance. This clone is a deep copy; all `Item` instances are cloned and all additional top-level fields are deep copied.

  extra_fields: dict[str, Any]

    Dictionary of additional top-level fields for the GeoJSON FeatureCollection.

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

    Creates a `ItemCollection` instance from a dictionary.

    Parameters:

      - d – The dictionary from which the `ItemCollection` will be created

      - 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 in a deepcopy of the parameter. Set to False when possible to avoid the performance hit of a deepcopy.

  classmethod from_file(href: str | PathLike[str], stac_io: StacIO | None = None) → C

    Reads a `ItemCollection` from a JSON file.

    Parameters:

      - href – Path to the file.

      - stac_io – A `StacIO` instance to use for file I/O

  static is_item_collection(d: dict[str, Any]) → bool

    Checks if the given dictionary represents a valid `ItemCollection`.

    Parameters:

      d – Dictionary to check

  items: list[Item]

    List of `pystac.Item` instances contained in this `ItemCollection`.

  save_object(dest_href: str, stac_io: StacIO | None = None) → None

    Saves this instance to the `dest_href` location.

    Parameters:

      - dest_href – Location to which the file will be saved.

      - stac_io – Optional `StacIO` instance to use. If not provided, will use the default instance.

  to_dict(transform_hrefs: bool = False) → dict[str, Any]

    Serializes an `ItemCollection` instance to a dictionary.

    Parameters:

      transform_hrefs – If True, transform the HREF of hierarchical links of Items based on the type of catalog the Item belongs to (if any). I.e. if the item 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. This can be slow if the Items have root links that have not yet been resolved. Defaults to False.

# Link

class pystac.Link(rel: str | pystac.RelType, target: str | STACObject, media_type: str | pystac.MediaType | None = None, title: str | None = None, extra_fields: dict[str, Any] | None = None)

  A link connects a `STACObject` to another entity.

  The target of a link can be either another STACObject, or an HREF. When serialized, links always refer to the HREF of the target. Links are lazily deserialized - this is, when you read in a link, it does not automatically load in the STACObject that is the target (if the link is pointing to a STACObject). When a user is crawling through a catalog or when additional metadata is required, PySTAC uses the `resolve_stac_object()` method to load in and deserialize STACObjects. This mechanism is used within the PySTAC codebase and normally does not need to be considered by the user - ideally the lazy deserialization of STACObjects is transparent to clients of PySTAC.

  Parameters:

    - rel – The relation of the link (e.g. ‘child’, ‘item’). Registered rel Types are preferred. See `RelType` for common media types.

    - target – The target of the link. If the link is unresolved, or the link is to something that is not a STACObject, the target is an HREF. If resolved, the target is a STACObject.

    - media_type – Optional description of the media type. Registered Media Types are preferred. See `MediaType` for common media types.

    - title – Optional title for this link.

    - extra_fields – Optional, additional fields for this link. This is used by extensions as a way to serialize and deserialize properties on link object JSON.

  property absolute_href: str

    Returns the absolute HREF for this link.

    If the href is None, this will throw an exception. Use get_absolute_href if there may not be an HREF set.

  classmethod canonical(item_or_collection: Item | Collection, title: str | None = None) → L

    Creates a canonical link to an Item or Collection.

  classmethod child(c: Catalog, title: str | None = None) → L

    Creates a link to a child Catalog or Collection.

  clone() → Link

    Clones this link.

    This makes a copy of all link information, but does not clone a STACObject if one is the target of this link.

    Returns:

      The cloned link.

    Return type:

      Link

  classmethod collection(c: Collection) → L

    Creates a link to a Collection.

  classmethod derived_from(item: Item | str, title: str | None = None) → L

    Creates a link to a derived_from Item.

  property ext: LinkExt

    Accessor for extension classes on this link

    Example:

        link.ext.file.size = 8675309

  extra_fields: dict[str, Any]

    Optional, additional fields for this link. This is used by extensions as a way to serialize and deserialize properties on link object JSON.

  classmethod from_dict(d: dict[str, Any]) → L

    Deserializes a `Link` from a dict.

    Parameters:

      d – The dict that represents the Link in JSON

    Returns:

      Link instance constructed from the dict.

    Return type:

      Link

  get_absolute_href() → str | None

    Gets the absolute href for this link, if possible.

    Returns:

      Returns this link’s HREF. It attempts to derive an absolute HREF from this link; however, if the link is relative, has no owner, and has an unresolved target, this will return a relative HREF.

    Return type:

      str

  get_href(transform_href: bool = True) → str | None

    Gets the HREF for this link.

    Parameters:

      transform_href – If True, transform the HREF based on the type of catalog the owner belongs to (if any). I.e. if the link owner belongs to a root catalog that is RELATIVE_PUBLISHED or SELF_CONTAINED, the HREF will be transformed to be relative to the catalog root if this is a hierarchical link relation.

    Returns:

      Returns this link’s HREF. If there is an owner of the link and the root catalog (if there is one) is of type RELATIVE_PUBLISHED, then the HREF returned will be relative. In all other cases, this method will return an absolute HREF.

    Return type:

      str

  get_target_str() → str | None

    Returns this link’s target as a string.

    If a string href was provided, returns that. If not, tries to resolve the self link of the target object.

  has_target_href() → bool

    Returns true if this link has a string href in its target information.

  property href: str

    Returns the HREF for this link.

    If the href is None, this will throw an exception. Use get_href if there may not be an HREF.

  is_hierarchical() → bool

    Returns true if this link’s rel type is hierarchical.

    Hierarchical links are used to build relationships in STAC, e.g. “parent”, “child”, “item”, etc. For a complete list of hierarchical relation types, see `HIERARCHICAL_LINKS`.

    Returns:

      True if the link’s rel type is hierarchical.

    Return type:

      bool

  is_resolved() → bool

    Determines if the link’s target is a resolved STACObject.

    Returns:

      True if this link is resolved.

    Return type:

      bool

  classmethod item(item: Item, title: str | None = None) → L

    Creates a link to an Item.

  media_type: str | pystac.MediaType | None

    Optional description of the media type. Registered Media Types are preferred. See `MediaType` for common media types.

  owner: STACObject | None

    The owner of this link. The link will use its owner’s root catalog `ResolvedObjectCache` to resolve objects, and will create absolute HREFs from relative HREFs against the owner’s self HREF.

  classmethod parent(c: Catalog) → L

    Creates a link to a parent Catalog or Collection.

  rel: str | pystac.RelType

    The relation of the link (e.g. ‘child’, ‘item’). Registered rel Types are preferred. See `RelType` for common media types.

  resolve_stac_object(root: Catalog | None = None) → Link

    Resolves a STAC object from the HREF of this link, if the link is not already resolved.

    Parameters:

      root – Optional root of the catalog for this link. If provided, the root’s resolved object cache is used to search for previously resolved instances of the STAC object.

  classmethod root(c: Catalog) → L

    Creates a link to a root Catalog or Collection.

  classmethod self_href(href: str | PathLike[str]) → L

    Creates a self link to a file’s location.

  set_owner(owner: STACObject | None) → Link

    Sets the owner of this link.

    Parameters:

      owner – The owner of this link. Pass None to clear.

  property target: str | STACObject

    The target of the link. If the link is unresolved, or the link is to something that is not a STACObject, the target is an HREF. If resolved, the target is a STACObject.

  property title: str | None

    Optional title for this link. If not provided during instantiation, this will attempt to get the title from the STAC object that the link references.

  to_dict(transform_href: bool = True) → dict[str, Any]

    Returns this link as a dictionary.

    Parameters:

      transform_href – If `True`, transform the HREF based on the type of catalog the owner belongs to (if any). I.e. if the link owner belongs to a root catalog that is RELATIVE_PUBLISHED or SELF_CONTAINED, the HREF will be transformed to be relative to the catalog root if this is a hierarchical link relation.

    Returns:

      A serialization of the Link.

    Return type:

      dict

# MediaType

class pystac.MediaType(*values)

  A list of common media types that can be used in STAC Asset and Link metadata.

  COG = 'image/tiff; application=geotiff; profile=cloud-optimized'
  COPC = 'application/vnd.laszip+copc'
  FLATGEOBUF = 'application/vnd.flatgeobuf'
  GEOJSON = 'application/geo+json'
  GEOPACKAGE = 'application/geopackage+sqlite3'
  GEOTIFF = 'image/tiff; application=geotiff'
  HDF = 'application/x-hdf'
  HDF5 = 'application/x-hdf5'
  HTML = 'text/html'
  JPEG = 'image/jpeg'
  JPEG2000 = 'image/jp2'
  JSON = 'application/json'
  KML = 'application/vnd.google-earth.kml+xml'
  NETCDF = 'application/netcdf'
  PARQUET = 'application/x-parquet'
  PDF = 'application/pdf'
  PNG = 'image/png'
  TEXT = 'text/plain'
  TIFF = 'image/tiff'
  VND_APACHE_PARQUET = 'application/vnd.apache.parquet'
  VND_PMTILES = 'application/vnd.pmtiles'
  VND_ZARR = 'application/vnd.zarr'
  XML = 'application/xml'
  ZARR = 'application/vnd+zarr'

# RelType

class pystac.RelType(*values)

  A list of common rel types that can be used in STAC Link metadata. See “Using Relation Types in the STAC Best Practices for guidelines on using relation types. You may also want to refer to the “Relation type” documentation for Catalogs, Collections, or Items for relation types specific to those STAC objects.

  ALTERNATE = 'alternate'
  CANONICAL = 'canonical'
  CHILD = 'child'
  COLLECTION = 'collection'
  DERIVED_FROM = 'derived_from'
  ITEM = 'item'
  ITEMS = 'items'
  LICENSE = 'license'
  NEXT = 'next'
  PARENT = 'parent'
  PREV = 'prev'
  PREVIEW = 'preview'
  ROOT = 'root'
  SELF = 'self'
  VIA = 'via'

# StacIO

class pystac.StacIO(headers: dict[str, str] | None = None)
  classmethod default() → StacIO
  json_dumps(json_dict: dict[str, Any], *args: Any, **kwargs: Any) → str

    Method used internally by `StacIO` instances to serialize a dictionary to a JSON string.

    This method may be overwritten in `StacIO` subclasses to provide custom serialization logic. The method accepts arbitrary keyword arguments. These are not used by the default implementation, but may be used by subclass implementations.

    Parameters:

      json_dict – The dictionary to serialize

  json_loads(txt: str, *args: Any, **kwargs: Any) → dict[str, Any]

    Method used internally by `StacIO` instances to deserialize a dictionary from a JSON string.

    This method may be overwritten in `StacIO` subclasses to provide custom deserialization logic. The method accepts arbitrary keyword arguments. These are not used by the default implementation, but may be used by subclass implementations.

    Parameters:

      txt – The JSON string to deserialize to a dictionary.

  read_json(source: str | PathLike[str], *args: Any, **kwargs: Any) → dict[str, Any]

    Read a dict from the given source.

    See `StacIO.read_text` for usage of str vs Link as a parameter.

    Parameters:

      - source – The source from which to read.

      - *args – Additional positional arguments to be passed to `StacIO.read_text()`.

      - **kwargs – Additional keyword arguments to be passed to `StacIO.read_text()`.

    Returns:

      A dict representation of the JSON contained in the file at the given source.

    Return type:

      dict

  read_stac_object(source: HREF, root: Catalog | None = None, *args: Any, **kwargs: Any) → STACObject

    Read a STACObject from a JSON file at the given source.

    See `StacIO.read_text` for usage of str vs Link as a parameter.

    Parameters:

      - source – The source from which to read.

      - root – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.

      - *args – Additional positional arguments to be passed to `StacIO.read_json()`.

      - **kwargs – Additional keyword arguments to be passed to `StacIO.read_json()`.

    Returns:

      The deserialized STACObject from the serialized JSON contained in the file at the given uri.

    Return type:

      STACObject

  abstractmethod read_text(source: str | PathLike[str], *args: Any, **kwargs: Any) → str

    Read text from the given URI.

    The source to read from can be specified as a string or `os.PathLike` object (`Link` is a path-like object). If it is a string, it must be a URI or local path from which to read. Using a `Link` enables implementations to use additional link information, such as paging information contained in the extended links described in the STAC API spec.

    Parameters:

      - source – The source to read from.

      - *args – Arbitrary positional arguments that may be utilized by the concrete implementation.

      - **kwargs – Arbitrary keyword arguments that may be utilized by the concrete implementation.

    Returns:

      The text contained in the file at the location specified by the uri.

    Return type:

      str

  save_json(dest: str | PathLike[str], json_dict: dict[str, Any], *args: Any, **kwargs: Any) → None

    Write a dict to the given URI as JSON.

    See `StacIO.write_text` for usage of str vs Link as a parameter.

    Parameters:

      - dest – The destination file to write the text to.

      - json_dict – The JSON dict to write.

      - *args – Additional positional arguments to be passed to `StacIO.json_dumps()`.

      - **kwargs – Additional keyword arguments to be passed to `StacIO.json_dumps()`.

  classmethod set_default(stac_io_class: Callable[[], StacIO]) → None

    Set the default StacIO instance to use.

  stac_object_from_dict(d: dict[str, Any], href: HREF | None = None, root: Catalog | None = None, preserve_dict: bool = True) → STACObject

    Deserializes a `STACObject` subclass instance from a dictionary.

    Parameters:

      - d – The dictionary to deserialize

      - href – Optional href to associate with the STAC object

      - root – Optional root `Catalog` to associate with the STAC object.

      - 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 in a deepcopy of the parameter. Set to `False` when possible to avoid the performance hit of a deepcopy.

  abstractmethod write_text(dest: str | PathLike[str], txt: str, *args: Any, **kwargs: Any) → None

    Write the given text to a file at the given URI.

    The destination to write to can be specified as a string or `os.PathLike` object (`Link` is a path-like object). If it is a string, it must be a URI or local path from which to read. Using a `Link` enables implementations to use additional link information.

    Parameters:

      - dest – The destination to write to.

      - txt – The text to write.

# Errors

## STACError

class pystac.STACError

  A STACError is raised for errors relating to STAC, e.g. for invalid formats or trying to operate on a STAC that does not have the required information available.

## STACTypeError

class pystac.STACTypeError(bad_dict: dict[str, Any], expected: type, extra_message: str | None = '')

  A STACTypeError is raised when encountering a representation of a STAC entity that is not correct for the context; for example, if a Catalog JSON was read in as an Item.

## DuplicateObjectKeyError

class pystac.DuplicateObjectKeyError

  Raised when deserializing a JSON object containing a duplicate key.

## ExtensionAlreadyExistsError

class pystac.ExtensionAlreadyExistsError

  An ExtensionAlreadyExistsError is raised when extension hooks are registered with PySTAC if there are already hooks registered for an extension with the same ID.

## ExtensionTypeError

class pystac.ExtensionTypeError

  An ExtensionTypeError is raised when an extension is used against an object that the extension does not apply to

## ExtensionNotImplemented

class pystac.ExtensionNotImplemented

  Attempted to extend a STAC object that does not implement the given extension.

## RequiredPropertyMissing

class pystac.RequiredPropertyMissing(obj: str | Any, prop: str, msg: str | None = None)

  This error is raised when a required value was expected to be there but was missing or None. This will happen, for example, in an extension that has required properties, where the required property is missing from the extended object

  Parameters:

    - obj – Description of the object that will have a property missing. Should include a __repr__ that identifies the object for the error message, or be a string that describes the object.

    - prop – The property that is missing

## STACValidationError

class pystac.STACValidationError(message: str, source: Any | None = None)

  Represents a validation error. Thrown by validation calls if the STAC JSON is invalid.

  Parameters:

    source – Source of the exception. Type will be determined by the validation implementation. For the default JsonSchemaValidator this will be `jsonschema.ValidationError`.

## TemplateError

class pystac.TemplateError

  Exception thrown when an error occurs during converting a template string into data for `LayoutTemplate`

## DeprecatedWarning

class pystac.DeprecatedWarning

  Issued when converting a dictionary to a STAC Item or Collection and the version extension `deprecated` field is present and set to `True`.