Skip to main content
`Ctrl`+`K`

# pystac.stac_object

class pystac.stac_object.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.stac_object.STACObjectType(*values)
  CATALOG = 'Catalog'
  COLLECTION = 'Collection'
  ITEM = 'Feature'

class pystac.stac_object.S

  alias of TypeVar(‘S’, bound=`STACObject`)