Expand get_items - deprecate get_all_items and Catalog.get_item

CHANGELOG.md

@@ -5,6 +5,8 @@
 ### Added
 
 - `sort_links_by_id` to Catalog `get_child()` and `modify_links` to `get_stac_objects()` ([#1064](https://github.com/stac-utils/pystac/pull/1064))
+- `*ids` to Catalog and Collection `get_items()` for only including the provided ids in the iterator ([#1075](https://github.com/stac-utils/pystac/pull/1075))
+-  `recursive` to Catalog and Collection `get_items()` to walk the sub-catalogs and sub-collections ([#1075](https://github.com/stac-utils/pystac/pull/1075))
 
 ### Changed
 
@@ -13,6 +15,8 @@
 ### Deprecated
 
 - `pystac.summaries.FIELDS_JSON_URL` ([#1045](https://github.com/stac-utils/pystac/pull/1045))
+- Catalog `get_item()`. Use `get_items(id)` instead ([#1075](https://github.com/stac-utils/pystac/pull/1075))
+- Catalog and Collection `get_all_items`. Use `get_items(recursive=True)` instead ([#1075](https://github.com/stac-utils/pystac/pull/1075))
 
 ## [v1.7.1]
 

docs/quickstart.ipynb

@@ -149,14 +149,15 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Crawling Items\n",
     "\n",
     "[STAC Items](https://github.com/radiantearth/stac-spec/tree/master/item-spec) are the fundamental building blocks of a STAC Catalog. Each Item represents a single spatiotemporal resource (e.g. a satellite scene).\n",
     "\n",
-    "Both Catalogs and Collections may have Items associated with them. Let's crawl our catalog, starting at the root, to see what Items we have. The [Catalog.get_all_items method](https://pystac.readthedocs.io/en/latest/api.html#pystac.Catalog.get_all_items) provides a convenient way of recursively listing all Items associated with a Catalog and all of its sub-Catalogs."
+    "Both Catalogs and Collections may have Items associated with them. Let's crawl our catalog, starting at the root, to see what Items we have. The [Catalog.get_items method](https://pystac.readthedocs.io/en/latest/api.html#pystac.Catalog.get_items) provides a convenient way of recursively listing all Items associated with a Catalog and all of its sub-Catalogs by including the `recursive=True` option."
    ]
   },
   {
@@ -177,7 +178,7 @@
     }
    ],
    "source": [
-    "items = list(root_catalog.get_all_items())\n",
+    "items = list(root_catalog.get_items(recursive=True))\n",
     "\n",
     "print(f\"Number of items: {len(items)}\")\n",
     "for item in items:\n",
@@ -192,6 +193,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -205,7 +207,7 @@
     "\n",
     "We will walk through each of these metadata categories in the following sections. \n",
     "\n",
-    "First, let's grab one of the Items using the [Catalog.get_item method](https://pystac.readthedocs.io/en/latest/api.html#pystac.Catalog.get_item). We will use `recursive=True` to recursively crawl all child Catalogs and/or Collections to find the Item."
+    "First, let's grab one of the Items using the [Catalog.get_items method](https://pystac.readthedocs.io/en/latest/api.html#pystac.Catalog.get_items). We will use `recursive=True` to recursively crawl all child Catalogs and/or Collections to find the Item."
    ]
   },
   {
@@ -214,7 +216,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "item = root_catalog.get_item(\"LC80140332018166LGN00\", recursive=True)"
+    "item = next(root_catalog.get_items(\"LC80140332018166LGN00\", recursive=True))"
    ]
   },
   {
@@ -1794,7 +1796,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "item_to_update = root_catalog.get_item(\"LC80140332018166LGN00\", recursive=True)\n",
+    "item_to_update = next(\n",
+    "    root_catalog.get_items(\"LC80140332018166LGN00\", recursive=True)\n",
+    ")\n",
     "item_to_update_eo_ext = EOExtension.ext(item_to_update)\n",
     "\n",
     "# Update the cloud cover\n",
@@ -1856,7 +1860,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Catalog saved to: /tmp/tmpgdncnim0/catalog.json\n"
+      "Catalog saved to: /tmp/tmpo2y1572p/catalog.json\n"
      ]
     }
    ],