Skip to main content
`Ctrl`+`K`

# pystac.link

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

pystac.link.HIERARCHICAL_LINKS = ['root', 'child', 'parent', 'collection', 'item', 'items']

  Hierarchical links provide structure to STAC catalogs.

class pystac.link.L

  Generalized version of `Link`

  alias of TypeVar(‘L’, bound=`Link`)