Update Item Assets Extension docstrings

Author: duckontheweb

pystac/extensions/item_assets.py

@@ -3,6 +3,7 @@
 https://github.com/stac-extensions/item-assets
 """
 
+from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 import pystac
@@ -22,11 +23,23 @@
 
 
 class AssetDefinition:
+    """Object that contains details about the datafiles that will be included in member
+    Items for this Collection.
+
+    See the :stac-ext:`Asset Object <item-assets#asset-object>` for details.
+    """
+
     def __init__(self, properties: Dict[str, Any]) -> None:
         self.properties = properties
 
+    def __eq__(self, o: object) -> bool:
+        if not isinstance(o, AssetDefinition):
+            return NotImplemented
+        return self.to_dict() == o.to_dict()
+
     @property
     def title(self) -> Optional[str]:
+        """Gets or sets the displayed title for clients and users."""
         return self.properties.get(ASSET_TITLE_PROP)
 
     @title.setter
@@ -38,6 +51,9 @@ def title(self, v: Optional[str]) -> None:
 
     @property
     def description(self) -> Optional[str]:
+        """Gets or sets a description of the Asset providing additional details, such as
+        how it was processed or created. `CommonMark 0.29 <http://commonmark.org/`__
+        syntax MAY be used for rich text representation."""
         return self.properties.get(ASSET_DESC_PROP)
 
     @description.setter
@@ -49,6 +65,9 @@ def description(self, v: Optional[str]) -> None:
 
     @property
     def media_type(self) -> Optional[str]:
+        """Gets or sets the `media type
+        <https://github.com/radiantearth/stac-spec/tree/v1.0.0-rc.1/catalog-spec/catalog-spec.md#media-types>`__
+        of the asset."""
         return self.properties.get(ASSET_TYPE_PROP)
 
     @media_type.setter
@@ -60,6 +79,9 @@ def media_type(self, v: Optional[str]) -> None:
 
     @property
     def roles(self) -> Optional[List[str]]:
+        """Gets or sets the `semantic roles
+        <https://github.com/radiantearth/stac-spec/tree/v1.0.0-rc.1/item-spec/item-spec.md#asset-role-types>`__
+        of the asset, similar to the use of rel in links."""
         return self.properties.get(ASSET_ROLES_PROP)
 
     @roles.setter
@@ -69,7 +91,13 @@ def roles(self, v: Optional[List[str]]) -> None:
         else:
             self.properties[ASSET_ROLES_PROP] = v
 
+    def to_dict(self) -> Dict[str, Any]:
+        """Returns a JSON-like dictionary representing this ``AssetDefinition``."""
+        return deepcopy(self.properties)
+
     def create_asset(self, href: str) -> pystac.Asset:
+        """Creates a new :class:`~pystac.Asset` instance using the fields from this
+        ``AssetDefinition`` and the given ``href``."""
         return pystac.Asset(
             href=href,
             title=self.title,
@@ -96,6 +124,8 @@ def __init__(self, collection: pystac.Collection) -> None:
 
     @property
     def item_assets(self) -> Dict[str, AssetDefinition]:
+        """Gets or sets a dictionary of assets that can be found in member Items. Maps
+        the asset key to an :class:`AssetDefinition` instance."""
         result: Dict[str, Any] = get_required(
             self.collection.extra_fields.get(ITEM_ASSETS_PROP), self, ITEM_ASSETS_PROP
         )
@@ -118,6 +148,13 @@ def get_schema_uri(cls) -> str:
     def ext(
         cls, obj: pystac.Collection, add_if_missing: bool = False
     ) -> "ItemAssetsExtension":
+        """Extends the given :class:`~pystac.Collection` with properties from the
+        :stac-ext:`Item Assets Extension <item-assets>`.
+
+        Raises:
+
+            pystac.ExtensionTypeError : If an invalid object type is passed.
+        """
         if isinstance(obj, pystac.Collection):
             cls.validate_has_extension(obj, add_if_missing)
             return cls(obj)