pystac.link#
- pystac.link.HIERARCHICAL_LINKS = [root, child, parent, collection, item, items]
Hierarchical links provide structure to STAC catalogs.
- 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)[source]
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
Link.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 [source]
Creates a canonical link to an Item or Collection.
- classmethod child(c: Catalog, title: str | None = None) L [source]
Creates a link to a child Catalog or Collection.
- clone() Link [source]
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:
- classmethod collection(c: Collection) L [source]
Creates a link to an item’s Collection.
- classmethod derived_from(item: Item | str, title: str | None = None) L [source]
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 [source]
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:
- get_absolute_href() str | None [source]
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:
- get_href(transform_href: bool = True) str | None [source]
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:
- get_target_str() str | None [source]
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 [source]
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 [source]
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:
- is_resolved() bool [source]
Determines if the link’s target is a resolved STACObject.
- Returns:
True if this link is resolved.
- Return type:
- 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.
- 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 [source]
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.
- set_owner(owner: STACObject | None) Link [source]
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] [source]
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: