Update docs

Author: jsignell

docs/api/item_assets.rst

@@ -0,0 +1,7 @@
+pystac.item_assets
+==================
+
+.. automodule:: pystac.item_assets
+    :members:
+    :undoc-members:
+    :noindex:

docs/api/pystac.rst

@@ -15,6 +15,7 @@ pystac
       Summaries
       Item
       Asset
+      ItemAssetDefinition
       CommonMetadata
       ItemCollection
       Link
@@ -116,6 +117,14 @@ Asset
    :members:
    :undoc-members:
 
+ItemAssetDefinition
+-------------------
+
+.. autoclass:: pystac.ItemAssetDefinition
+   :members:
+   :undoc-members:
+
+
 CommonMetadata
 --------------
 

pystac/collection.py

@@ -735,6 +735,41 @@ def get_item(self, id: str, recursive: bool = False) -> Item | None:
 
     @property
     def item_assets(self) -> dict[str, ItemAssetDefinition] | None:
+        """Accessor for `item_assets
+        <https://github.com/radiantearth/stac-spec/blob/v1.1.0/collection-spec/collection-spec.md#item_assets>`__
+        on this collection.
+
+        Example::
+
+        .. code-block:: python
+
+           >>> print(collection.item_assets)
+           {'thumbnail': <pystac.item_assets.ItemAssetDefinition at 0x72aea0420750>,
+            'metadata': <pystac.item_assets.ItemAssetDefinition at 0x72aea017dc90>,
+            'B5': <pystac.item_assets.ItemAssetDefinition at 0x72aea017efd0>,
+            'B6': <pystac.item_assets.ItemAssetDefinition at 0x72aea016d5d0>,
+            'B7': <pystac.item_assets.ItemAssetDefinition at 0x72aea016e050>,
+            'B8': <pystac.item_assets.ItemAssetDefinition at 0x72aea016da90>}
+           >>> collection.item_assets["thumbnail"].title
+           'Thumbnail'
+
+        Set attributes on :class:`~pystac.ItemAssetDefinition` objects
+
+        .. code-block:: python
+
+           >>> collection.item_assets["thumbnail"].title = "New Title"
+
+        Add to the ``item_assets`` dict:
+
+        .. code-block:: python
+
+            >>> collection.item_assets["B4"] = {
+                'type': 'image/tiff; application=geotiff; profile=cloud-optimized',
+                'eo:bands': [{'name': 'B4', 'common_name': 'red'}]
+            }
+            >>> collection.item_assets["B4"].owner == collection
+            True
+        """
         if self._item_assets is None and "item_assets" in self.extra_fields:
             self._item_assets = _ItemAssets(self)
         return self._item_assets

pystac/extensions/item_assets.py

@@ -28,14 +28,21 @@ def __init__(cls, *args: Any, **kwargs: Any) -> None:
 
 
 class ItemAssetsExtension(ExtensionManagementMixin[pystac.Collection]):
+    """
+    DEPRECATED
+
+    .. deprecated:: 1.12.0
+        Use :attr:`~pystac.Collection.item_assets` instead.
+    """
+
     name: Literal["item_assets"] = "item_assets"
     collection: pystac.Collection
 
     def __init__(self, collection: pystac.Collection) -> None:
         warnings.warn(
             (
                 "The ``item_assets`` extension is deprecated. "
-                "``item_assets`` are now top-level collection properties."
+                "``item_assets`` is now a top-level property of ``Collection``."
             ),
             DeprecatedWarning,
         )

pystac/item_assets.py

@@ -1,4 +1,8 @@
-"""Implements the ``Item Asset Definition <item-assets>``."""
+"""
+Implements the `Item Asset Definition Object
+<https://github.com/radiantearth/stac-spec/blob/v1.1.0/collection-spec/collection-spec.md#item-asset-definition-object>`__
+for use as values in the :attr:`~pystac.Collection.item_assets` dict.
+"""
 
 from __future__ import annotations
 
@@ -18,10 +22,9 @@
 
 
 class ItemAssetDefinition:
-    """Object that contains details about the datafiles that will be included in member
-    Items for this Collection.
-
-    See the `Item Asset Definition Object <item-assets#asset-object>` for details.
+    """Implementation of the `Item Asset Definition Object
+    <https://github.com/radiantearth/stac-spec/blob/v1.1.0/collection-spec/collection-spec.md#item-asset-definition-object>`__
+    for use as values in the :attr:`~pystac.Collection.item_assets` dict.
     """
 
     properties: dict[str, Any]
@@ -58,10 +61,10 @@ def create(
                 `CommonMark 0.29 <http://commonmark.org/>`__ syntax MAY be used
                 for rich text representation.
             media_type : `media type\
-                <https://github.com/radiantearth/stac-spec/tree/v1.0.0/catalog-spec/catalog-spec.md#media-types>`__
+                <https://github.com/radiantearth/stac-spec/tree/v1.1.0/catalog-spec/catalog-spec.md#media-types>`__
                  of the asset.
             roles : `semantic roles
-                <https://github.com/radiantearth/stac-spec/tree/v1.0.0/item-spec/item-spec.md#asset-role-types>`__
+                <https://github.com/radiantearth/stac-spec/tree/v1.1.0/item-spec/item-spec.md#asset-role-types>`__
                 of the asset, similar to the use of rel in links.
             extra_fields : Additional fields on the asset definition, e.g. from
                 extensions.

tests/test_item_assets.py

@@ -45,6 +45,28 @@ def test_example(self) -> None:
             ),
         )
 
+    def test_set_using_dict(self) -> None:
+        collection = self.collection.clone()
+
+        assert collection.item_assets
+        self.assertEqual(len(collection.item_assets), 13)
+
+        collection.item_assets["Bx"] = {
+            "type": "image/tiff; application=geotiff",
+            "eo:bands": [
+                {
+                    "name": "B1",
+                    "common_name": "coastal",
+                    "center_wavelength": 0.44,
+                    "full_width_half_max": 0.02,
+                }
+            ],
+            "title": "Coastal Band (B1)",
+            "description": "Coastal Band Top Of the Atmosphere",
+        }  # type:ignore
+
+        self.assertEqual(collection.item_assets["B1"], collection.item_assets["Bx"])
+
 
 class TestAssetDefinition(unittest.TestCase):
     def setUp(self) -> None:
@@ -130,14 +152,14 @@ def test_item_assets_extension_is_deprecated() -> None:
 
     assert ItemAssetsExtension.get_schema_uri() not in collection.stac_extensions
 
-    with pytest.warns(DeprecatedWarning, match="top-level collection properties"):
+    with pytest.warns(DeprecatedWarning, match="top-level property of"):
         item_asset = ItemAssetsExtension.ext(
             collection, add_if_missing=True
         ).item_assets["cloud-mask-raster"]
 
     assert item_asset.ext.has("eo")
 
-    with pytest.warns(DeprecatedWarning, match="top-level collection properties"):
+    with pytest.warns(DeprecatedWarning, match="top-level property of"):
         assert collection.ext.item_assets["cloud-mask-raster"].ext.has("eo")
 
     assert ItemAssetsExtension.get_schema_uri() in collection.stac_extensions