Refactors architecture to better enable STAC 1.0 extension changes

.flake8

@@ -1,14 +1,3 @@
 [flake8]
-max-line-length = 100
-
-## IGNORES
-
-# E126: yapf conflicts with "continuation line over-indented for hanging indent"
-
-# E127: flake8 reporting incorrect continuation line indent errors
-# on multi-line and multi-level indents
-
-# W503: flake8 reports this as incorrect, and scripts/format_code
-# changes code to it, so let format_code win.
-
-ignore = E126,E127,W503
+max-line-length = 88
+extend-ignore = E203, W503, E731, E722

mypy.ini

@@ -0,0 +1,3 @@
+[mypy]
+ignore_missing_imports = True
+disallow_untyped_defs = True

pystac/__init__.py

@@ -3,59 +3,72 @@
 """
 
 # flake8: noqa
-
-
-class STACError(Exception):
-    """A STACError is raised for errors relating to STAC, e.g. for
-    invalid formats or trying to operate on a STAC that does not have
-    the required information available.
-    """
-    pass
-
-
-from pystac.version import (__version__, get_stac_version, set_stac_version)
-from pystac.stac_io import STAC_IO
-from pystac.extensions import Extensions
-from pystac.stac_object import (STACObject, STACObjectType)
-from pystac.media_type import MediaType
-from pystac.link import (Link, HIERARCHICAL_LINKS)
-from pystac.catalog import (Catalog, CatalogType)
-from pystac.collection import (Collection, Extent, SpatialExtent, TemporalExtent, Provider)
-from pystac.item import (Item, Asset, CommonMetadata)
-
-from pystac.serialization import stac_object_from_dict
+from pystac.errors import (
+    STACError,  # type:ignore
+    STACTypeError,  # type:ignore
+    RequiredPropertyMissing,  # type:ignore
+)
+
+from typing import Any, Dict, Optional
+from pystac.version import (
+    __version__,
+    get_stac_version,  # type:ignore
+    set_stac_version,  # type:ignore
+)
+from pystac.stac_io import StacIO  # type:ignore
+from pystac.stac_object import STACObject, STACObjectType  # type:ignore
+from pystac.media_type import MediaType  # type:ignore
+from pystac.link import Link, HIERARCHICAL_LINKS  # type:ignore
+from pystac.catalog import Catalog, CatalogType  # type:ignore
+from pystac.collection import (
+    Collection,  # type:ignore
+    Extent,  # type:ignore
+    SpatialExtent,  # type:ignore
+    TemporalExtent,  # type:ignore
+    Provider,  # type:ignore
+    Summaries,  # type:ignore
+    RangeSummary,  # type:ignore
+)
+from pystac.item import Item, Asset, CommonMetadata  # type:ignore
 
 import pystac.validation
+from pystac.validation import STACValidationError  # type:ignore
 
-STAC_IO.stac_object_from_dict = stac_object_from_dict
-
-from pystac import extensions
+import pystac.extensions.hooks
+import pystac.extensions.datacube
 import pystac.extensions.eo
+import pystac.extensions.file
+import pystac.extensions.item_assets
 import pystac.extensions.label
 import pystac.extensions.pointcloud
 import pystac.extensions.projection
 import pystac.extensions.sar
 import pystac.extensions.sat
 import pystac.extensions.scientific
-import pystac.extensions.single_file_stac
 import pystac.extensions.timestamps
 import pystac.extensions.version
 import pystac.extensions.view
-import pystac.extensions.file
-
-STAC_EXTENSIONS = extensions.base.RegisteredSTACExtensions([
-    extensions.eo.EO_EXTENSION_DEFINITION, extensions.label.LABEL_EXTENSION_DEFINITION,
-    extensions.pointcloud.POINTCLOUD_EXTENSION_DEFINITION,
-    extensions.projection.PROJECTION_EXTENSION_DEFINITION, extensions.sar.SAR_EXTENSION_DEFINITION,
-    extensions.sat.SAT_EXTENSION_DEFINITION, extensions.scientific.SCIENTIFIC_EXTENSION_DEFINITION,
-    extensions.single_file_stac.SFS_EXTENSION_DEFINITION,
-    extensions.timestamps.TIMESTAMPS_EXTENSION_DEFINITION,
-    extensions.version.VERSION_EXTENSION_DEFINITION, extensions.view.VIEW_EXTENSION_DEFINITION,
-    extensions.file.FILE_EXTENSION_DEFINITION
-])
-
 
-def read_file(href):
+EXTENSION_HOOKS = pystac.extensions.hooks.RegisteredExtensionHooks(
+    [
+        pystac.extensions.datacube.DATACUBE_EXTENSION_HOOKS,
+        pystac.extensions.eo.EO_EXTENSION_HOOKS,
+        pystac.extensions.file.FILE_EXTENSION_HOOKS,
+        pystac.extensions.item_assets.ITEM_ASSETS_EXTENSION_HOOKS,
+        pystac.extensions.label.LABEL_EXTENSION_HOOKS,
+        pystac.extensions.pointcloud.POINTCLOUD_EXTENSION_HOOKS,
+        pystac.extensions.projection.PROJECTION_EXTENSION_HOOKS,
+        pystac.extensions.sar.SAR_EXTENSION_HOOKS,
+        pystac.extensions.sat.SAT_EXTENSION_HOOKS,
+        pystac.extensions.scientific.SCIENTIFIC_EXTENSION_HOOKS,
+        pystac.extensions.timestamps.TIMESTAMPS_EXTENSION_HOOKS,
+        pystac.extensions.version.VERSION_EXTENSION_HOOKS,
+        pystac.extensions.view.VIEW_EXTENSION_HOOKS,
+    ]
+)
+
+
+def read_file(href: str) -> STACObject:
     """Reads a STAC object from a file.
 
     This method will return either a Catalog, a Collection, or an Item based on what the
@@ -73,7 +86,9 @@ def read_file(href):
     return STACObject.from_file(href)
 
 
-def write_file(obj, include_self_link=True, dest_href=None):
+def write_file(
+    obj: STACObject, include_self_link: bool = True, dest_href: Optional[str] = None
+) -> None:
     """Writes a STACObject to a file.
 
     This will write only the Catalog, Collection or Item ``obj``. It will not attempt
@@ -96,7 +111,12 @@ def write_file(obj, include_self_link=True, dest_href=None):
     obj.save_object(include_self_link=include_self_link, dest_href=dest_href)
 
 
-def read_dict(d, href=None, root=None):
+def read_dict(
+    d: Dict[str, Any],
+    href: Optional[str] = None,
+    root: Optional[Catalog] = None,
+    stac_io: Optional[StacIO] = None,
+) -> STACObject:
     """Reads a STAC object from a dict representing the serialized JSON version of the
     STAC object.
 
@@ -112,5 +132,9 @@ def read_dict(d, href=None, root=None):
         root (Catalog or Collection): 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 StacIO instance to use for reading. If None, the
+            default instance will be used.
     """
-    return stac_object_from_dict(d, href, root)
+    if stac_io is None:
+        stac_io = StacIO.default()
+    return stac_io.stac_object_from_dict(d, href, root)

pystac/asset.py

@@ -0,0 +1,165 @@
+from copy import copy
+from typing import Any, Dict, List, Optional, TYPE_CHECKING, Union
+
+import pystac as ps
+from pystac.utils import is_absolute_href, make_absolute_href
+
+if TYPE_CHECKING:
+    from pystac.collection import Collection as Collection_Type
+    from pystac.item import Item as Item_Type
+
+
+class Asset:
+    """An object that contains a link to data associated with an Item or Collection that
+    can be downloaded or streamed.
+
+    Args:
+        href (str): Link to the asset object. Relative and absolute links are both
+            allowed.
+        title (str): Optional displayed title for clients and users.
+        description (str): 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): Optional description of the media type. Registered Media Types
+            are preferred. See :class:`~pystac.MediaType` for common media types.
+        roles ([str]): Optional, Semantic roles (i.e. thumbnail, overview,
+            data, metadata) of the asset.
+        properties (dict): Optional, additional properties for this asset. This is used
+            by extensions as a way to serialize and deserialize properties on asset
+            object JSON.
+
+    Attributes:
+        href (str): Link to the asset object. Relative and absolute links are both
+            allowed.
+        title (str): Optional displayed title for clients and users.
+        description (str): 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): Optional description of the media type. Registered Media Types
+            are preferred. See :class:`~pystac.MediaType` for common media types.
+        properties (dict): Optional, additional properties for this asset. This is used
+            by extensions as a way to serialize and deserialize properties on asset
+            object JSON.
+        owner: The Item or Collection this asset belongs to, or None if it has no owner.
+    """
+
+    def __init__(
+        self,
+        href: str,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        media_type: Optional[str] = None,
+        roles: Optional[List[str]] = None,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.href = href
+        self.title = title
+        self.description = description
+        self.media_type = media_type
+        self.roles = roles
+
+        if properties is not None:
+            self.properties = properties
+        else:
+            self.properties = {}
+
+        # The Item which owns this Asset.
+        self.owner: Optional[Union[ps.Item, ps.Collection]] = None
+
+    def set_owner(self, obj: Union["Collection_Type", "Item_Type"]) -> 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) -> Optional[str]:
+        """Gets the absolute href for this asset, if possible.
+
+        If this Asset has no associated Item, this will return whatever the
+        href is (as it cannot determine the absolute path, if the asset
+        href is relative).
+
+        Returns:
+            str: The absolute HREF of this asset, or a relative HREF is an absolute HREF
+            cannot be determined.
+        """
+        if not is_absolute_href(self.href):
+            if self.owner is not None:
+                return make_absolute_href(self.href, self.owner.get_self_href())
+
+        return self.href
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Generate a dictionary representing the JSON of this Asset.
+
+        Returns:
+            dict: A serialization of the Asset that can be written out as JSON.
+        """
+
+        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.properties is not None and len(self.properties) > 0:
+            for k, v in self.properties.items():
+                d[k] = v
+
+        if self.roles is not None:
+            d["roles"] = self.roles
+
+        return d
+
+    def clone(self) -> "Asset":
+        """Clones this asset.
+
+        Returns:
+            Asset: The clone of this asset.
+        """
+        return Asset(
+            href=self.href,
+            title=self.title,
+            description=self.description,
+            media_type=self.media_type,
+            roles=self.roles,
+            properties=self.properties,
+        )
+
+    def __repr__(self) -> str:
+        return "<Asset href={}>".format(self.href)
+
+    @staticmethod
+    def from_dict(d: Dict[str, Any]) -> "Asset":
+        """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 Asset(
+            href=href,
+            media_type=media_type,
+            title=title,
+            description=description,
+            roles=roles,
+            properties=properties,
+        )