pystac.asset

class pystac.asset.Asset(href: str, title: str | None = None, description: str | None = None, media_type: str | None = None, roles: list[str] | None = None, extra_fields: dict[str, Any] | None = None)

An object that contains a link to data associated with an Item or Collection that can be downloaded or streamed.

Parameters:

• href – Link to the asset object. Relative and absolute links are both allowed.

• title – Optional displayed title for clients and users.

• description – A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

• media_type – Optional description of the media type. Registered Media Types are preferred. See MediaType for common media types.

• roles – Optional, Semantic roles (i.e. thumbnail, overview, data, metadata) of the asset.

• extra_fields – Optional, additional fields for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.

clone() → Asset

Clones this asset. Makes a deepcopy of the extra_fields.

Returns:

The clone of this asset.

Return type:

Asset

property common_metadata: CommonMetadata

Access the asset’s common metadata fields as a CommonMetadata object.

copy(href: str) → Asset

Copies this asset’s file to a new location on the local filesystem, setting the asset href accordingly.

Modifies the asset in place, and returns the same asset.

Parameters:

href – The new asset location. Must be a local path. If relative it must be relative to the owner object.

Returns:

The asset with the updated href.

Return type:

Asset

delete() → None

Delete this asset’s file. Does not delete the asset from the item that owns it. See delete_asset() for that.

Does not modify the asset.

description: str | None

A description of the Asset providing additional details, such as how it was processed or created. CommonMark 0.29 syntax MAY be used for rich text representation.

property ext: AssetExt

Accessor for extension classes on this asset

Example:

asset.ext.proj.epsg = 4326

extra_fields: dict[str, Any]

Optional, additional fields for this asset. This is used by extensions as a way to serialize and deserialize properties on asset object JSON.

classmethod from_dict(d: dict[str, Any]) → A

Constructs an Asset from a dict.

Returns:

The Asset deserialized from the JSON dict.

Return type:

Asset

get_absolute_href() → str | None

Gets the absolute href for this asset, if possible.

If this Asset has no associated Item, and the asset HREF is a relative path,

this method will return None. If the Item that owns the Asset has no self HREF, this will also return None.

Returns:

The absolute HREF of this asset, or None if an absolute HREF could not

be determined.

Return type:

str

has_role(role: str) → bool

Check if a role exists in the Asset role list.

Parameters:

role – Role to check for existence.

Returns:

True if role exists, else False.

Return type:

bool

href: str

Link to the asset object. Relative and absolute links are both allowed.

media_type: str | None

Optional description of the media type. Registered Media Types are preferred. See MediaType for common media types.

move(href: str) → Asset

Moves this asset’s file to a new location on the local filesystem, setting the asset href accordingly.

Modifies the asset in place, and returns the same asset.

Parameters:

href – The new asset location. Must be a local path. If relative it must be relative to the owner object.

Returns:

The asset with the updated href.

Return type:

Asset

owner: Assets | None

The Item or Collection that this asset belongs to, or None if it has no owner.

roles: list[str] | None

Optional, Semantic roles (i.e. thumbnail, overview, data, metadata) of the asset.

set_owner(obj: Assets) → None

Sets the owning item of this Asset.

The owning item will be used to resolve relative HREFs of this asset.

Parameters:

obj – The Collection or Item that owns this asset.

title: str | None

Optional displayed title for clients and users.

to_dict() → dict[str, Any]

Returns this Asset as a dictionary.

Returns:

A serialization of the Asset.

Return type:

dict

class pystac.asset.Assets(*args, **kwargs)

Protocol, with functionality, for STAC objects that have assets.

add_asset(key: str, asset: Asset) → None

Adds an Asset to this object.

Parameters:

• key – The unique key of this asset.

• asset – The Asset to add.

assets: dict[str, Asset]

The asset dictionary.

delete_asset(key: str) → None

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”].

Parameters:

key – The unique key of this asset.

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

Get this object’s assets.

Parameters:

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

A dictionary of assets that match media_type

and/or role if set or else all of this object’s assets.

Return type:

Dict[str, Asset]

get_self_href() → str | None

Abstract definition of STACObject.get_self_href.

Needed to make the make_asset_hrefs_{absolute|relative} methods pass type checking. Refactoring out all the link behavior in STACObject to its own protocol would be too heavy, so we just use this stub instead.

make_asset_hrefs_absolute() → Assets

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:

self

Return type:

Assets

make_asset_hrefs_relative() → Assets

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

Returns:

self

Return type:

Item