pystac.link#
- class pystac.link.Link(rel: Union[str, pystac.rel_type.RelType], target: Union[str, STACObject_Type], media_type: Optional[str] = None, title: Optional[str] = None, extra_fields: Optional[Dict[str, Any]] = 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: Union[Item_Type, Collection_Type], title: Optional[str] = None) Link [source]
Creates a canonical link to an Item or Collection.
- classmethod child(c: Catalog_Type, title: Optional[str] = None) Link [source]
Creates a link to a child Catalog or Collection.
- clone() pystac.link.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
- 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]) pystac.link.Link [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() Optional[str] [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) Optional[str] [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() Optional[str] [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_resolved() bool [source]
Determines if the link’s target is a resolved STACObject.
- Returns
True if this link is resolved.
- Return type
- classmethod item(item: Item_Type, title: Optional[str] = None) Link [source]
Creates a link to an Item.
- media_type: Optional[str]
Optional description of the media type. Registered Media Types are preferred. See
MediaType
for common media types.
- owner: Optional[STACObject_Type]
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: Union[str, pystac.rel_type.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: Optional[Catalog_Type] = 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.
- classmethod self_href(href: Union[str, os.PathLike]) pystac.link.Link [source]
Creates a self link to a file’s location.
- set_owner(owner: Optional[STACObject_Type]) Link [source]
Sets the owner of this link.
- Parameters
owner – The owner of this link. Pass None to clear.
- property target: Union[str, STACObject_Type]
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: Optional[str]
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]
Generate a dictionary representing the JSON of this serialized 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
A serialization of the Link that can be written out as JSON.
- Return type