pystac.stac_object#

class pystac.stac_object.STACObject(stac_extensions: List[str])[source]

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: pystac.stac_object.STACObjectType
add_link(link: pystac.link.Link) → None[source]

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

Parameters

link – The link to add.

add_links(links: List[pystac.link.Link]) → None[source]

Add links to this object’s set of links.

Parameters

links – The links to add.

clear_links(rel: Optional[Union[str, pystac.rel_type.RelType]] = None) → None[source]

Clears all Link instances associated with this object.

Parameters

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

abstract clone() → pystac.stac_object.STACObject[source]

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 STACObject.full_copy.

Returns

The clone of this object.

Return type

STACObject

abstract classmethod from_dict(d: Dict[str, Any], href: Optional[str] = None, root: Optional[Catalog_Type] = None, migrate: bool = False, preserve_dict: bool = True) → STACObject[source]

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 – Use True if this dict represents JSON from an older STAC object, so that migrations are run against it.

  • 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 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, stac_io: Optional[pystac.stac_io.StacIO] = None) → pystac.stac_object.STACObject[source]

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: Optional[Catalog_Type] = None, parent: Optional[Catalog_Type] = None) → STACObject[source]

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: Optional[Union[str, pystac.rel_type.RelType]] = None, media_type: Optional[Union[str, pystac.media_type.MediaType]] = None) → List[pystac.link.Link][source]

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

Returns

A list of links that match rel if set,

or else all links associated with this object.

Return type

List[Link]

get_parent() → Optional[Catalog_Type][source]

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() → Optional[Catalog_Type][source]

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() → Optional[pystac.link.Link][source]

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() → Optional[str][source]

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: Union[str, pystac.rel_type.RelType], media_type: Optional[Union[str, pystac.media_type.MediaType]] = None) → Optional[pystac.link.Link][source]

Get single link that match the given rel and, optionally, media_type. If media_type is None, then the link is matched only on the rel value.

Parameters

  • rel – The Link rel to match on.

  • media_type – The MediaType media_type to match on

get_stac_objects(rel: Union[str, pystac.rel_type.RelType], typ: Optional[Type[pystac.stac_object.STACObject]] = None) → Iterable[pystac.stac_object.STACObject][source]

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.

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[STACObjects]

id: str

The ID of the STAC Object.

links: List[pystac.link.Link]

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

abstract classmethod matches_object_type(d: Dict[str, Any]) → bool[source]

Returns a boolean indicating whether the given dictionary represents a valid instance of this STACObject sub-class.

Parameters

d – A dictionary to identify

remove_links(rel: Union[str, pystac.rel_type.RelType]) → None[source]

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[source]

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: Optional[str] = None, stac_io: Optional[pystac.stac_io.StacIO] = None) → None[source]

Saves this STAC Object 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: Optional[Catalog_Type]) → None[source]

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: Optional[Catalog_Type]) → None[source]

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: Optional[str]) → None[source]

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.

abstract to_dict(include_self_link: bool = True, transform_hrefs: bool = True) → Dict[str, Any][source]

Generate a dictionary representing the JSON of this serialized object.

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 that can be written out as JSON.

validate() → List[Any][source]

Validate this STACObject.

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

Raises

STACValidationError –

class pystac.stac_object.STACObjectType(value)[source]

An enumeration.

CATALOG = 'Catalog'
COLLECTION = 'Collection'
ITEM = 'Feature'

previous

pystac.stac_io

next

pystac.summaries