pystac-core 1.15.0__py3-none-any.whl

pystac/__init__.py

@@ -0,0 +1,260 @@
+# isort: skip_file
+"""
+PySTAC is a library for working with SpatioTemporal Asset Catalogs (STACs)
+"""
+
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
+__all__ = [
+    "__version__",
+    "TemplateError",
+    "STACError",
+    "STACTypeError",
+    "DuplicateObjectKeyError",
+    "ExtensionAlreadyExistsError",
+    "ExtensionNotImplemented",
+    "ExtensionTypeError",
+    "RequiredPropertyMissing",
+    "STACValidationError",
+    "DeprecatedWarning",
+    "MediaType",
+    "RelType",
+    "StacIO",
+    "STACObject",
+    "STACObjectType",
+    "Link",
+    "HIERARCHICAL_LINKS",
+    "Catalog",
+    "CatalogType",
+    "Collection",
+    "Extent",
+    "SpatialExtent",
+    "TemporalExtent",
+    "Summaries",
+    "CommonMetadata",
+    "RangeSummary",
+    "Item",
+    "Asset",
+    "ItemAssetDefinition",
+    "ItemCollection",
+    "Provider",
+    "ProviderRole",
+    "read_file",
+    "read_dict",
+    "write_file",
+    "get_stac_version",
+    "set_stac_version",
+]
+
+import warnings
+from typing import Any
+
+from pystac.errors import (
+    TemplateError,
+    STACError,
+    STACTypeError,
+    DuplicateObjectKeyError,
+    ExtensionAlreadyExistsError,
+    ExtensionNotImplemented,
+    ExtensionTypeError,
+    RequiredPropertyMissing,
+    STACValidationError,
+    DeprecatedWarning,
+)
+
+from pystac.version import (
+    __version__,
+    get_stac_version,
+    set_stac_version,
+)
+from pystac.media_type import MediaType
+from pystac.rel_type import RelType
+from pystac.stac_io import StacIO
+from pystac.stac_object import STACObject, STACObjectType
+from pystac.link import Link, HIERARCHICAL_LINKS
+from pystac.catalog import Catalog, CatalogType
+from pystac.collection import (
+    Collection,
+    Extent,
+    SpatialExtent,
+    TemporalExtent,
+)
+from pystac.common_metadata import CommonMetadata
+from pystac.summaries import RangeSummary, Summaries
+from pystac.asset import Asset
+from pystac.item import Item
+from pystac.item_assets import ItemAssetDefinition
+from pystac.item_collection import ItemCollection
+from pystac.provider import ProviderRole, Provider
+from pystac.utils import HREF
+
+import pystac.extensions.hooks
+import pystac.extensions.classification
+import pystac.extensions.datacube
+import pystac.extensions.eo
+import pystac.extensions.file
+import pystac.extensions.grid
+import pystac.extensions.item_assets
+
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore", category=DeprecationWarning)
+    import pystac.extensions.label
+import pystac.extensions.mgrs
+import pystac.extensions.mlm
+import pystac.extensions.pointcloud
+import pystac.extensions.projection
+import pystac.extensions.raster
+import pystac.extensions.sar
+import pystac.extensions.sat
+import pystac.extensions.scientific
+import pystac.extensions.storage
+import pystac.extensions.table
+import pystac.extensions.timestamps
+import pystac.extensions.version
+import pystac.extensions.view
+import pystac.extensions.xarray_assets
+
+EXTENSION_HOOKS = pystac.extensions.hooks.RegisteredExtensionHooks(
+    [
+        pystac.extensions.classification.CLASSIFICATION_EXTENSION_HOOKS,
+        pystac.extensions.datacube.DATACUBE_EXTENSION_HOOKS,
+        pystac.extensions.eo.EO_EXTENSION_HOOKS,
+        pystac.extensions.file.FILE_EXTENSION_HOOKS,
+        pystac.extensions.grid.GRID_EXTENSION_HOOKS,
+        pystac.extensions.item_assets.ITEM_ASSETS_EXTENSION_HOOKS,
+        pystac.extensions.label.LABEL_EXTENSION_HOOKS,
+        pystac.extensions.mgrs.MGRS_EXTENSION_HOOKS,
+        pystac.extensions.mlm.MLM_EXTENSION_HOOKS,
+        pystac.extensions.pointcloud.POINTCLOUD_EXTENSION_HOOKS,
+        pystac.extensions.projection.PROJECTION_EXTENSION_HOOKS,
+        pystac.extensions.raster.RASTER_EXTENSION_HOOKS,
+        pystac.extensions.sar.SAR_EXTENSION_HOOKS,
+        pystac.extensions.sat.SAT_EXTENSION_HOOKS,
+        pystac.extensions.scientific.SCIENTIFIC_EXTENSION_HOOKS,
+        pystac.extensions.storage.STORAGE_EXTENSION_HOOKS,
+        pystac.extensions.table.TABLE_EXTENSION_HOOKS,
+        pystac.extensions.timestamps.TIMESTAMPS_EXTENSION_HOOKS,
+        pystac.extensions.version.VERSION_EXTENSION_HOOKS,
+        pystac.extensions.view.VIEW_EXTENSION_HOOKS,
+        pystac.extensions.xarray_assets.XARRAY_ASSETS_EXTENSION_HOOKS,
+    ]
+)
+
+
+def read_file(href: HREF, stac_io: StacIO | None = None) -> STACObject:
+    """Reads a STAC object from a file.
+
+    This method will return either a Catalog, a Collection, or an Item based on what
+    the file contains.
+
+    This is a convenience method for :meth:`StacIO.read_stac_object
+    <pystac.StacIO.read_stac_object>`
+
+    Args:
+        href : The HREF to read the object from.
+        stac_io: Optional :class:`~StacIO` instance to use for I/O operations. If not
+            provided, will use :meth:`StacIO.default` to create an instance.
+
+    Returns:
+        The specific STACObject implementation class that is represented
+        by the JSON read from the file located at HREF.
+
+    Raises:
+        STACTypeError : If the file at ``href`` does not represent a valid
+            :class:`~pystac.STACObject`. Note that an :class:`~pystac.ItemCollection`
+            is not a :class:`~pystac.STACObject` and must be read using
+            :meth:`ItemCollection.from_file <pystac.ItemCollection.from_file>`
+    """
+    if stac_io is None:
+        stac_io = StacIO.default()
+    return stac_io.read_stac_object(href)
+
+
+def write_file(
+    obj: STACObject,
+    include_self_link: bool = True,
+    dest_href: HREF | None = None,
+    stac_io: StacIO | None = None,
+) -> None:
+    """Writes a STACObject to a file.
+
+    This will write only the Catalog, Collection or Item ``obj``. It will not attempt
+    to write any other objects that are linked to ``obj``; if you'd like functionality
+    to save off catalogs recursively see :meth:`Catalog.save <pystac.Catalog.save>`.
+
+    This method will write the JSON of the object to the object's assigned "self" link
+    or to the dest_href if provided. To set the self link, see
+    :meth:`STACObject.set_self_href <pystac.STACObject.set_self_href>`.
+
+    Convenience method for :meth:`STACObject.from_file <pystac.STACObject.from_file>`
+
+    Args:
+        obj : The STACObject to save.
+        include_self_link : If ``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 :class:`~StacIO` instance to use for I/O operations. If not
+            provided, will use :meth:`StacIO.default` to create an instance.
+    """
+    if stac_io is None:
+        stac_io = StacIO.default()
+    import os
+
+    dest_href = None if dest_href is None else str(os.fspath(dest_href))
+    obj.save_object(
+        include_self_link=include_self_link, dest_href=dest_href, stac_io=stac_io
+    )
+
+
+def read_dict(
+    d: dict[str, Any],
+    href: str | None = None,
+    root: Catalog | None = None,
+    stac_io: StacIO | None = None,
+) -> STACObject:
+    """Reads a :class:`~STACObject` or :class:`~ItemCollection` from a JSON-like dict
+    representing a serialized STAC object.
+
+    This method will return either a :class:`~Catalog`, :class:`~Collection`,
+    or :class`~Item` based on the contents of the dict.
+
+    This is a convenience method for either
+    :meth:`StacIO.stac_object_from_dict <pystac.StacIO.stac_object_from_dict>`.
+
+    Args:
+        d : The dict to parse.
+        href : Optional href that is the file location of the object being
+            parsed.
+        root : Optional root of the catalog for this object.
+            If provided, the root's resolved object cache can be used to search for
+            previously resolved instances of the STAC object.
+        stac_io: Optional :class:`~StacIO` instance to use for reading. If ``None``,
+            the default instance will be used.
+
+    Raises:
+        STACTypeError : If the ``d`` dictionary does not represent a valid
+            :class:`~pystac.STACObject`. Note that an :class:`~pystac.ItemCollection`
+            is not a :class:`~pystac.STACObject` and must be read using
+            :meth:`ItemCollection.from_dict <pystac.ItemCollection.from_dict>`
+    """
+    if stac_io is None:
+        stac_io = StacIO.default()
+    return stac_io.stac_object_from_dict(d, href, root)
+
+
+def __getattr__(name: str) -> Any:
+    if name == "validation":
+        import warnings
+        import pystac.validation
+
+        warnings.warn(
+            "pystac.validation will not be automatically imported to the package in "
+            "pystac v2.0. Instead, import it directly: `import pystac.validation`",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return pystac.validation
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

pystac/asset.py

@@ -0,0 +1,395 @@
+from __future__ import annotations
+
+import shutil
+from copy import copy, deepcopy
+from typing import TYPE_CHECKING, Any, Protocol, TypeVar
+
+from pystac import MediaType, STACError, common_metadata, utils
+from pystac.utils import is_absolute_href, make_absolute_href, make_relative_href
+
+if TYPE_CHECKING:
+    from pystac.common_metadata import CommonMetadata
+    from pystac.extensions.ext import AssetExt
+
+#: Generalized version of :class:`Asset`
+A = TypeVar("A", bound="Asset")
+
+
+class Asset:
+    """An object that contains a link to data associated with an Item or Collection that
+    can be downloaded or streamed.
+
+    Args:
+        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 :class:`~pystac.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.
+    """
+
+    href: str
+    """Link to the asset object. Relative and absolute links are both allowed."""
+
+    title: str | None
+    """Optional displayed title for clients and users."""
+
+    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."""
+
+    media_type: str | None
+    """Optional description of the media type. Registered Media Types are preferred.
+    See :class:`~pystac.MediaType` for common media types."""
+
+    roles: list[str] | None
+    """Optional, Semantic roles (i.e. thumbnail, overview, data, metadata) of the
+    asset."""
+
+    owner: Assets | None
+    """The :class:`~pystac.Item` or :class:`~pystac.Collection` that this asset belongs
+    to, or ``None`` if it has no owner."""
+
+    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."""
+
+    def __init__(
+        self,
+        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,
+    ) -> None:
+        self.href = utils.make_posix_style(href)
+        self.title = title
+        self.description = description
+        self.media_type = media_type
+        self.roles = roles
+        self.extra_fields = extra_fields or {}
+
+        # The Item which owns this Asset.
+        self.owner = None
+
+    def set_owner(self, obj: Assets) -> None:
+        """Sets the owning item of this Asset.
+
+        The owning item will be used to resolve relative HREFs of this asset.
+
+        Args:
+            obj: The Collection or Item that owns this asset.
+        """
+        self.owner = obj
+
+    def get_absolute_href(self) -> 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:
+            str: The absolute HREF of this asset, or None if an absolute HREF could not
+                be determined.
+        """
+        item_self = self.owner.get_self_href() if self.owner is not None else None
+        if utils.is_absolute_href(self.href, item_self):
+            return self.href
+        else:
+            if item_self is not None:
+                return utils.make_absolute_href(self.href, item_self)
+            return None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Returns this Asset as a dictionary.
+
+        Returns:
+            dict: A serialization of the Asset.
+        """
+
+        d: dict[str, Any] = {"href": self.href}
+
+        if self.media_type is not None:
+            d["type"] = self.media_type
+
+        if self.title is not None:
+            d["title"] = self.title
+
+        if self.description is not None:
+            d["description"] = self.description
+
+        if self.extra_fields is not None and len(self.extra_fields) > 0:
+            for k, v in self.extra_fields.items():
+                d[k] = v
+
+        if self.roles is not None:
+            d["roles"] = self.roles
+
+        return d
+
+    def clone(self) -> Asset:
+        """Clones this asset. Makes a ``deepcopy`` of the
+        :attr:`~pystac.Asset.extra_fields`.
+
+        Returns:
+            Asset: The clone of this asset.
+        """
+        cls = self.__class__
+        return cls(
+            href=self.href,
+            title=self.title,
+            description=self.description,
+            media_type=self.media_type,
+            roles=self.roles,
+            extra_fields=deepcopy(self.extra_fields),
+        )
+
+    def has_role(self, role: str) -> bool:
+        """Check if a role exists in the Asset role list.
+
+        Args:
+            role: Role to check for existence.
+
+        Returns:
+            bool: True if role exists, else False.
+        """
+        if self.roles is None:
+            return False
+        else:
+            return role in self.roles
+
+    @property
+    def common_metadata(self) -> CommonMetadata:
+        """Access the asset's common metadata fields as a
+        :class:`~pystac.CommonMetadata` object."""
+        return common_metadata.CommonMetadata(self)
+
+    def __repr__(self) -> str:
+        return f"<Asset href={self.href}>"
+
+    def _repr_html_(self) -> str:
+        from html import escape
+
+        from pystac.html.jinja_env import get_jinja_env
+
+        jinja_env = get_jinja_env()
+        if jinja_env:
+            template = jinja_env.get_template("JSON.jinja2")
+            return str(template.render(dict=self.to_dict(), plain=escape(repr(self))))
+        else:
+            return escape(repr(self))
+
+    @classmethod
+    def from_dict(cls: type[A], d: dict[str, Any]) -> A:
+        """Constructs an Asset from a dict.
+
+        Returns:
+            Asset: The Asset deserialized from the JSON dict.
+        """
+        d = copy(d)
+        href = d.pop("href")
+        media_type = d.pop("type", None)
+        title = d.pop("title", None)
+        description = d.pop("description", None)
+        roles = d.pop("roles", None)
+        properties = None
+        if any(d):
+            properties = d
+
+        return cls(
+            href=href,
+            media_type=media_type,
+            title=title,
+            description=description,
+            roles=roles,
+            extra_fields=properties,
+        )
+
+    def move(self, 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.
+
+        Args:
+            href: The new asset location. Must be a local path. If relative
+                it must be relative to the owner object.
+
+        Returns:
+            Asset: The asset with the updated href.
+        """
+        src = _absolute_href(self.href, self.owner, "move")
+        dst = _absolute_href(href, self.owner, "move")
+        shutil.move(src, dst)
+        self.href = href
+        return self
+
+    def copy(self, 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.
+
+        Args:
+            href: The new asset location. Must be a local path. If relative
+                it must be relative to the owner object.
+
+        Returns:
+            Asset: The asset with the updated href.
+        """
+        src = _absolute_href(self.href, self.owner, "copy")
+        dst = _absolute_href(href, self.owner, "copy")
+        shutil.copy2(src, dst)
+        self.href = href
+        return self
+
+    def delete(self) -> None:
+        """Delete this asset's file. Does not delete the asset from the item
+        that owns it. See :meth:`~pystac.Item.delete_asset` for that.
+
+        Does not modify the asset.
+        """
+        import os
+
+        href = _absolute_href(self.href, self.owner, "delete")
+        os.remove(href)
+
+    @property
+    def ext(self) -> AssetExt:
+        """Accessor for extension classes on this asset
+
+        Example::
+
+            asset.ext.proj.code = "EPSG:4326"
+        """
+        from pystac.extensions.ext import AssetExt
+
+        return AssetExt(stac_object=self)
+
+
+class Assets(Protocol):
+    """Protocol, with functionality, for STAC objects that have assets."""
+
+    assets: dict[str, Asset]
+    """The asset dictionary."""
+
+    def get_assets(
+        self,
+        media_type: str | MediaType | None = None,
+        role: str | None = None,
+    ) -> dict[str, Asset]:
+        """Get this object'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 object's assets.
+        """
+        return {
+            k: deepcopy(v)
+            for k, v in self.assets.items()
+            if (media_type is None or v.media_type == media_type)
+            and (role is None or v.has_role(role))
+        }
+
+    def add_asset(self, key: str, asset: Asset) -> None:
+        """Adds an Asset to this object.
+
+        Args:
+            key : The unique key of this asset.
+            asset : The Asset to add.
+        """
+        asset.set_owner(self)
+        self.assets[key] = asset
+
+    def delete_asset(self, 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"]`.
+
+        Args:
+            key: The unique key of this asset.
+        """
+        asset = self.assets[key]
+        asset.set_owner(self)
+        asset.delete()
+
+        del self.assets[key]
+
+    def make_asset_hrefs_relative(self) -> Assets:
+        """Modify each asset's HREF to be relative to this object's self HREF.
+
+        Returns:
+            Item: self
+        """
+        self_href = self.get_self_href()
+        for asset in self.assets.values():
+            if is_absolute_href(asset.href, self_href):
+                if self_href is None:
+                    raise STACError(
+                        "Cannot make asset HREFs relative if no self_href is set."
+                    )
+                asset.href = make_relative_href(asset.href, self_href)
+        return self
+
+    def make_asset_hrefs_absolute(self) -> 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:
+            Assets: self
+        """
+        self_href = self.get_self_href()
+        for asset in self.assets.values():
+            if not is_absolute_href(asset.href, self_href):
+                if self_href is None:
+                    raise STACError(
+                        "Cannot make relative asset HREFs absolute "
+                        "if no self_href is set."
+                    )
+                asset.href = make_absolute_href(asset.href, self_href)
+        return self
+
+    def get_self_href(self) -> 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.
+        """
+        ...
+
+
+def _absolute_href(href: str, owner: Assets | None, action: str = "access") -> str:
+    item_self = owner.get_self_href() if owner else None
+    if utils.is_absolute_href(href, item_self):
+        return href
+    else:
+        if item_self is None:
+            raise ValueError(
+                f"Cannot {action} file if asset href ('{href}') is relative "
+                "and owner item is not set. Hint: try using "
+                ":func:`~pystac.Item.make_asset_hrefs_absolute`"
+            )
+        return utils.make_absolute_href(href, item_self)