deprecate get_all_items_as_dict and get_all_items, add get_items_as_dicts

CHANGELOG.md

@@ -6,6 +6,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased] - TBD
 
+### Deprecated
+
+- Item Search methods `get_items()` and `get_item_collections()` have been renamed to
+  `items()` and `item_collections()`. The original methods are now deprecated 
+  and may be removed as early as v0.5.0. [#206](https://github.com/stac-utils/pystac-client/pull/206)
+- Item Search methods `get_all_items()` and `get_all_items_as_dict()` are now deprecated,
+  and may be removed as early as v0.5.0.
+  These have been deprecated because they have the potential to perform a large number
+  of requests to the server and instantiate a large number of objects in memory.
+  To a user, this is only visible as a large delay in the method call and/or the
+  exhaustion of all available memory. The iterator methods `items()` or
+  `item_collections()` should be used instead. [#206](https://github.com/stac-utils/pystac-client/pull/206)
+
 ### Added
 
 - lru_cache to several methods [#167](https://github.com/stac-utils/pystac-client/pull/167)
@@ -15,9 +28,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Changed
 
 - Better error message when trying to search a non-item-search-conforming catalog [#164](https://github.com/stac-utils/pystac-client/pull/164)
-- Search `filter-lang` defaults to `cql2-json` instead of `cql-json`
-- Search `filter-lang` will be set to `cql2-json` if the `filter` is a dict, or `cql2-text` if it is a string
-- Search parameter `intersects` is now typed to only accept a str, dict, or object that implements `__geo_interface__`
+- Search `filter-lang` defaults to `cql2-json` instead of `cql-json` [#169](https://github.com/stac-utils/pystac-client/pull/169)
+- Search `filter-lang` will be set to `cql2-json` if the `filter` is a dict, or `cql2-text` if it is a string [#169](https://github.com/stac-utils/pystac-client/pull/169)
+- Search parameter `intersects` is now typed to only accept a str, dict, or object that implements `__geo_interface__` [#169](https://github.com/stac-utils/pystac-client/pull/169)
 
 ### Fixed
 
@@ -27,7 +40,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Removed
 
-- Client parameter `require_geojson_link` has been removed.
+- Client parameter `require_geojson_link` has been removed. [#169](https://github.com/stac-utils/pystac-client/pull/169)
 
 ## [v0.3.5] - 2022-05-26
 
@@ -122,7 +135,7 @@ are in a single HTTP session, handle pagination and respects conformance
 - Update to use PySTAC 1.1.0
 - IO changed to use PySTAC's new StacIO base class. 
 - `Search.item_collections()` renamed to `Search.get_item_collections()`
-- `Search.item_collections()` renamed to `Search.get_items()`
+- `Search.item()` renamed to `Search.get_items()`
 - Conformance is checked by each individual function that requires a particular conformance
 - STAC API testing URLs changed to updated APIs
 - `ItemSearch.get_pages()` function moved to StacApiIO class for general use

docs/quickstart.rst

@@ -13,15 +13,15 @@ The ``--matched`` switch performs a search with limit=1 so does not get
 any Items, but gets the total number of matches which will be output to
 the screen (if supported by the STAC API).
 
-::
+.. code-block:: console
 
     $ stac-client search https://earth-search.aws.element84.com/v0 -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --matched
     2179 items matched
 
 If the same URL is to be used over and over, define an environment
 variable to be used in the CLI call:
 
-::
+.. code-block:: console
 
     $ export STAC_API_URL=https://earth-search.aws.element84.com/v0
     $ stac-client search ${STAC_API_URL} -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 --matched
@@ -36,7 +36,7 @@ another process such as
 `geojsonio-cli <https://github.com/mapbox/geojsonio-cli>`__, or
 `jq <https://stedolan.github.io/jq/>`__.
 
-::
+.. code-block:: console
 
     $ stac-client search ${STAC_API_URL} -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 | stacterm cal --label platform
 
@@ -46,7 +46,7 @@ another process such as
 If the ``--save`` switch is provided instead, the results will not be
 output to stdout, but instead will be saved to the specified file.
 
-::
+.. code-block:: console
 
     $ stac-client search ${STAC_API_URL} -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 --save items.json
 
@@ -77,12 +77,12 @@ The query filter will also accept complete JSON as per the specification.
 Any number of properties can be included, and each can be included more
 than once to use additional operators.
 
-::
+.. code-block:: console
 
     $ stac-client search ${STAC_API_URL} -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 -q "eo:cloud_cover<10" --matched
     10 items matched
 
-::
+.. code-block:: console
 
     $ stac-client search ${STAC_API_URL} -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 -q "eo:cloud_cover<10" "eo:cloud_cover>5" --matched
     4 items matched
@@ -91,37 +91,39 @@ Python
 ~~~~~~
 
 To use the Python library, first a Client instance is created for a
-specific STAC API (use the root URL)
+specific STAC API (use the root URL):
 
-::
+.. code-block:: python
 
     from pystac_client import Client
 
-    catalog = Client.open("https://earth-search.aws.element84.com/v0")
+    catalog_client = Client.open("https://earth-search.aws.element84.com/v0")
 
-Create a search
+Create a search:
 
-::
+.. code-block:: python
 
-    mysearch = catalog.search(collections=['sentinel-s2-l2a-cogs'], bbox=[-72.5,40.5,-72,41], max_items=10)
+    my_search = catalog_client.search(collections=['sentinel-s2-l2a-cogs'], bbox=[-72.5,40.5,-72,41], max_items=10)
     print(f"{mysearch.matched()} items found")
 
-The ``get_items`` function returns an iterator for looping through he
-returned items.
+The ``items()`` generator method can be used to iterate through all resulting items.
 
-::
+.. code-block:: python
 
-    for item in mysearch.get_items():
+    for item in my_search.items():
         print(item.id)
 
-To get all of Items from a search as a single `PySTAC
-ItemCollection <https://pystac.readthedocs.io/en/latest/api.html#itemcollection>`__
-use the ``get_all_items`` function. The ``ItemCollection`` can then be
-saved as a GeoJSON FeatureCollection.
+To convert all of Items from a search as a single `PySTAC
+ItemCollection <https://pystac.readthedocs.io/en/latest/api/pystac.html#pystac.ItemCollection>`__,
+you must first do a limited iteration on the iterator to get a list of Items, and then
+create an ItemCollection with that. The ``ItemCollection`` can then be saved as a
+GeoJSON FeatureCollection.
 
-Save all found items as a single FeatureCollection
+Save all found items as a single FeatureCollection:
 
-::
+.. code-block:: python
+
+    from pystac import ItemCollection
 
-    items = mysearch.get_all_items()
-    items.save_object('items.json')
+    my_itemcollection = ItemCollection(items = list(my_search.items()))
+    my_itemcollection.save_object('my_itemcollection.json')