pygeodes.utils.stac.Item#

class pygeodes.utils.stac.Item(*args, **kwargs)[source]#

Bases: Item

__init__(*args, **kwargs)[source]#

Methods

`__init__`(args, *kwargs)
`add_asset`(key, asset)	Adds an Asset to this item.
`add_derived_from`(*items)	Add one or more items that this is derived from.
`add_link`(link)	Add a link to this object's set of links.
`add_links`(links)	Add links to this object's set of links.
`clear_links`([rel])	Clears all `Link` instances associated with this object.
`clone`()	Clones this object.
`delete_asset`(key)	Deletes the asset at the given key, and removes the asset's data file from the local filesystem.
`download_archive`([outfile])
`find`(key)
`from_dict`(d[, href, root, migrate, ...])	Parses this STACObject from the passed in dictionary.
`from_file`(href[, stac_io])	Reads a STACObject implementation from a file.
`full_copy`([root, parent])	Create a full copy of this STAC object and any stac objects linked to by this object.
`get_assets`([media_type, role])	Get this item's assets.
`get_collection`()	Gets the collection of this item, if one exists.
`get_datetime`([asset])	Gets an Item or an Asset datetime.
`get_derived_from`()	Get the items that this is derived from.
`get_links`([rel, media_type])	Gets the `Link` instances associated with this object.
`get_parent`()	Get the `Catalog` or `Collection` to the parent for this object.
`get_quicklook_content_in_base64`()
`get_root`()	Get the `Catalog` or `Collection` to the root for this object.
`get_root_link`()	Get the `Link` representing the root for this object.
`get_self_href`()	Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.
`get_single_link`([rel, media_type])	Get a single `Link` instance associated with this object.
`get_stac_objects`(rel[, typ, modify_links])	Gets the `STACObject` instances that are linked to by links with their `rel` property matching the passed in argument.
`list_available_keys`([with_origin])
`make_asset_hrefs_absolute`()	Modify each asset's HREF to be absolute.
`make_asset_hrefs_relative`()	Modify each asset's HREF to be relative to this item's self HREF.
`matches_object_type`(d)	Returns a boolean indicating whether the given dictionary represents a valid instance of this `STACObject` sub-class.
`remove_derived_from`(item_id)	Remove an item that this is derived from.
`remove_hierarchical_links`([add_canonical])	Removes all hierarchical links from this object.
`remove_links`(rel)	Remove links to this object's set of links that match the given `rel`.
`resolve_links`()	Ensure all STACObjects linked to by this STACObject are resolved.
`save_object`([include_self_link, dest_href, ...])	Saves this STAC Object to it's 'self' HREF.
`set_collection`(collection)	Set the collection of this item.
`set_datetime`(datetime[, asset])	Set an Item or an Asset datetime.
`set_parent`(parent)	Sets the parent `Catalog` or `Collection` for this object.
`set_root`(root)	Sets the root `Catalog` or `Collection` for this object.
`set_self_href`(href)	Sets the absolute HREF that is represented by the `rel == 'self'` `Link`.
`show_quicklook`()
`target_in_hierarchy`(target)	Determine if target is somewhere in the hierarchical link tree of a STACObject.
`to_dict`()	Returns this object as a dictionary.
`validate`()	Validate this STACObject.

Attributes

`STAC_OBJECT_TYPE`
`common_metadata`	Access the item's common metadata fields as a `CommonMetadata` object.
`data_asset`
`data_asset_checksum`
`filesize`
`quicklook_asset`
`s3_path`
`self_href`	Gets the absolute HREF that is represented by the `rel == 'self'` `Link`.
`assets`	Dictionary of `Asset` objects, each with a unique key.
`bbox`	Bounding Box of the asset represented by this item using either 2D or 3D geometries.
`collection`	`Collection` to which this Item belongs, if any.
`collection_id`	The Collection ID that this item belongs to, if any.
`datetime`	Datetime associated with this item.
`extra_fields`	Extra fields that are part of the top-level JSON fields the Item.
`geometry`	Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).
`id`	Provider identifier.
`links`	A list of `Link` objects representing all links associated with this Item.
`properties`	A dictionary of additional metadata for the Item.
`stac_extensions`	List of extensions the Item implements.

add_asset(key: str, asset: Asset) → None[source]#

Adds an Asset to this item.

Args:: key : The unique key of this asset. asset : The Asset to add.

add_derived_from(*items: Item | str) → Item[source]#

Add one or more items that this is derived from.

This method will add to any existing “derived_from” links.

Args:: items : Items (or href of items) to add to derived_from links.
Returns:: Item: self

add_link(link: Link) → None#

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

Args:: link : The link to add.

add_links(links: List[Link]) → None#

Add links to this object’s set of links.

Args:: links : The links to add.

assets: Dict[str, Asset]#: Dictionary of Asset objects, each with a unique key.

bbox: List[float] | None#: Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array is 2*n where n is the number of dimensions. Could also be None in the case of a null geometry.

clear_links(rel: str | RelType | None = None) → None#

Clears all Link instances associated with this object.

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

clone() → Item[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:: STACObject: The clone of this object.

collection: Collection | None#: Collection to which this Item belongs, if any.

collection_id: str | None#: The Collection ID that this item belongs to, if any.

property common_metadata: CommonMetadata#: Access the item’s common metadata fields as a CommonMetadata object.

datetime: Datetime | None#: Datetime associated with this item. If None, then start_datetime and end_datetime in common_metadata will supply the datetime range of the Item.

delete_asset(key: str) → None[source]#

Deletes the asset at the given key, and removes the asset’s data file from the local filesystem.

It is an error to attempt to delete an asset’s file if it is on a remote filesystem.

To delete the asset without removing the file, use del item.assets[“key”].

Args:: key: The unique key of this asset.

extra_fields: Dict[str, Any]#: Extra fields that are part of the top-level JSON fields the Item.

classmethod from_dict(d: Dict[str, Any], href: str | None = None, root: Catalog | None = None, migrate: bool = False, preserve_dict: bool = True) → T[source]#

Parses this STACObject from the passed in dictionary.

Args:

d : The dict to parse. href : Optional href that is the file location of the object being

parsed.

rootOptional 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:

STACObject: The STACObject parsed from this dict.

classmethod from_file(href: str, stac_io: StacIO | None = None) → S#

Reads a STACObject implementation from a file.

Args:: 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) → Item[source]#

Create a full copy of this STAC object and any stac objects linked to by this object.

Args:

rootOptional root to set as the root of the copied object,: and any other copies that are contained by this object.
parentOptional parent to set as the parent of the copy: of this object.

Returns:

STACObject: A full copy of this object, as well as any objects this object links to.

geometry: Dict[str, Any] | None#: Defines the full footprint of the asset represented by this item, formatted according to RFC 7946, section 3.1 (GeoJSON).

get_assets(media_type: str | MediaType | None = None, role: str | None = None) → Dict[str, Asset][source]#

Get this item’s assets.

Args:

media_type: If set, filter the assets such that only those with a: matching media_type are returned.
role: If set, filter the assets such that only those with a matching: role are returned.

Returns:

Dict[str, Asset]: A dictionary of assets that match media_type: and/or role if set or else all of this item’s assets.

get_collection() → Collection | None[source]#

Gets the collection of this item, if one exists.

Returns:: Collection or None: If this item belongs to a collection, returns a reference to the collection. Otherwise returns None.

get_datetime(asset: Asset | None = None) → Datetime | None[source]#

Gets an Item or an Asset datetime.

If an Asset is supplied and the Item property exists on the Asset, returns the Asset’s value. Otherwise returns the Item’s value.

Returns:: datetime or None

get_derived_from() → List[Item][source]#

Get the items that this is derived from.

Returns:: List[Item]: Returns a reference to the derived_from items.

get_links(rel: str | RelType | None = None, media_type: str | MediaType | None = None) → List[Link]#

Gets the Link instances associated with this object.

Args:

relIf 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:

List[Link]: A list of links that match rel and/ or media_type if set, or else all links associated with this object.

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:

Catalog, Collection, or None:: The parent object for this object, or None if no root link is set.

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:: Catalog, Collection, or None: The root object for this object, or None if no root link is set.

get_root_link() → Link | None#

Get the Link representing the root for this object.

Returns:: Link or None: The root link for this object, or None if no root link is set.

get_self_href() → str | None#

Gets the absolute HREF that is represented by the rel == 'self' Link.

Returns:: str or None: The absolute HREF of this object, or None if there is no self link defined.
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 a single Link instance associated with this object.

Args:

relIf 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:

Optional[Link]: First link that matches rel and/or media_type, or else the first link associated with this object.

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.

Args:

relThe relation to match each Link’s: rel property against.
typIf not None, objects will only be yielded if they are instances of: typ.
modify_linksA 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:

Iterable[STACObjects]: 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).

id: str#: Provider identifier. Unique within the STAC.

links: List[Link]#: A list of Link objects representing all links associated with this Item.

make_asset_hrefs_absolute() → Item[source]#

Modify each asset’s HREF to be absolute.

Any asset HREFs that are relative will be modified to absolute based on this item’s self HREF.

Returns:: Item: self

make_asset_hrefs_relative() → Item[source]#

Modify each asset’s HREF to be relative to this item’s self HREF.

Returns:: Item: self

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.

Args:: d : A dictionary to identify

properties: Dict[str, Any]#: A dictionary of additional metadata for the Item.

remove_derived_from(item_id: str) → None[source]#

Remove an item that this is derived from.

This method will remove from existing “derived_from” links.

Args:: item_id : ID of item to remove from derived_from links.

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.

Args:

add_canonicalIf true, and this item has a self href, that: href is used to build a canonical link.

Returns:

List[Link]: All removed links

remove_links(rel: str | RelType) → None#

Remove links to this object’s set of links that match the given rel.

Args:: 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 STAC Object to it’s ‘self’ HREF.

Args:

include_self_linkIf this is true, include the ‘self’ link with: this object. Otherwise, leave out the self link.
dest_hrefOptional 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 :stac-spec:`Use of Links section of the STAC best practices document <best-practices.md#use-of-links>`

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_collection(collection: Collection | None) → Item[source]#

Set the collection of this item.

This method will replace any existing Collection link and attribute for this item.

Args:

collectionThe collection to set as this: item’s collection. If None, will clear the collection.

Returns:

Item: self

set_datetime(datetime: Datetime, asset: Asset | None = None) → None[source]#

Set an Item or an Asset datetime.

If an Asset is supplied, sets the property on the Asset. Otherwise sets the Item’s value.

set_parent(parent: Catalog | None) → None#

Sets the parent Catalog or Collection for this object.

Args:

parentThe 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.

Args:

rootThe root: object to set. Passing in None will clear the root.

set_self_href(href: str | None) → None[source]#

Sets the absolute HREF that is represented by the rel == 'self' Link.

Changing the self HREF of the item will ensure that all asset HREFs remain valid. If asset HREFs are relative, the HREFs will change to point to the same location based on the new item self HREF, either by making them relative to the new location or making them absolute links if the new location does not share the same protocol as the old location.

Args:

hrefThe 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]#: List of extensions the Item implements.

target_in_hierarchy(target: str | STACObject) → bool#

Determine if target is somewhere in the hierarchical link tree of a STACObject.

Args:

target: A string or STACObject to search for

Returns:

bool: Returns True if the target was found in the hierarchical link tree: for the current STACObject

to_dict()[source]#

Returns this object as a dictionary.

Args:

include_self_linkIf 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() → List[Any]#

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