Cleanup deprecation docs

CHANGELOG.md

@@ -17,6 +17,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   as replacements for various deprecated methods [#237](https://github.com/stac-utils/pystac-client/issues/237)
 - Restored the previous behavior of ``Client.search()`` to return an unlimited number of items by default. [#273](https://github.com/stac-utils/pystac-client/pull/273)
 
+### Deprecated
+
+- `ItemSearch.item_collections` has been deprecated in favor of `ItemSearch.pages`. [#237](https://github.com/stac-utils/pystac-client/issues/237)
+
 ## [v0.4.0] - 2022-06-08
 
 ### Added

docs/api.rst

@@ -37,6 +37,7 @@ The `ItemSearch` class represents a search of a STAC API.
 .. autoclass:: pystac_client.ItemSearch
    :members:
    :undoc-members:
+   :member-order: bysource
 
 STAC API IO
 -----------

pystac_client/client.py

@@ -367,11 +367,11 @@ def search(
                 You may express a single datetime using a :class:`datetime.datetime`
                 instance, a `RFC 3339-compliant <https://tools.ietf.org/html/rfc3339>`__
                 timestamp, or a simple date string (see below). Instances of
-                 :class:`datetime.datetime` may be either
+                :class:`datetime.datetime` may be either
                 timezone aware or unaware. Timezone aware instances will be converted to
-                 a UTC timestamp before being passed
+                a UTC timestamp before being passed
                 to the endpoint. Timezone unaware instances are assumed to represent UTC
-                 timestamps. You may represent a
+                timestamps. You may represent a
                 datetime range using a ``"/"`` separated string as described in the
                 spec, or a list, tuple, or iterator
                 of 2 timestamps or datetime instances. For open-ended ranges, use either
@@ -380,10 +380,9 @@ def search(
                 (``['2020-01-01:00:00:00Z', None]``).
 
                 If using a simple date string, the datetime can be specified in
-                 ``YYYY-mm-dd`` format, optionally truncating
+                ``YYYY-mm-dd`` format, optionally truncating
                 to ``YYYY-mm`` or just ``YYYY``. Simple date strings will be expanded to
-                 include the entire time period, for
-                example:
+                include the entire time period, for example:
 
                 - ``2017`` expands to ``2017-01-01T00:00:00Z/2017-12-31T23:59:59Z``
                 - ``2017-06`` expands to ``2017-06-01T00:00:00Z/2017-06-30T23:59:59Z``

pystac_client/item_search.py

@@ -181,25 +181,24 @@ class ItemSearch:
             geojson. Results filtered to only those intersecting the geometry.
         datetime: Either a single datetime or datetime range used to filter results.
             You may express a single datetime using a :class:`datetime.datetime`
-             instance, a `RFC 3339-compliant <https://tools.ietf.org/html/rfc3339>`__
+            instance, a `RFC 3339-compliant <https://tools.ietf.org/html/rfc3339>`__
             timestamp, or a simple date string (see below). Instances of
-             :class:`datetime.datetime` may be either
+            :class:`datetime.datetime` may be either
             timezone aware or unaware. Timezone aware instances will be converted to
-             a UTC timestamp before being passed
+            a UTC timestamp before being passed
             to the endpoint. Timezone unaware instances are assumed to represent UTC
-             timestamps. You may represent a
+            timestamps. You may represent a
             datetime range using a ``"/"`` separated string as described in the spec,
-             or a list, tuple, or iterator
+            or a list, tuple, or iterator
             of 2 timestamps or datetime instances. For open-ended ranges, use either
             ``".."`` (``'2020-01-01:00:00:00Z/..'``,
             ``['2020-01-01:00:00:00Z', '..']``) or a value of ``None``
             (``['2020-01-01:00:00:00Z', None]``).
 
             If using a simple date string, the datetime can be specified in
-             ``YYYY-mm-dd`` format, optionally truncating
+            ``YYYY-mm-dd`` format, optionally truncating
             to ``YYYY-mm`` or just ``YYYY``. Simple date strings will be expanded to
-             include the entire time period, for
-            example:
+            include the entire time period, for example:
 
             - ``2017`` expands to ``2017-01-01T00:00:00Z/2017-12-31T23:59:59Z``
             - ``2017-06`` expands to ``2017-06-01T00:00:00Z/2017-06-30T23:59:59Z``
@@ -697,7 +696,7 @@ def pages_as_dicts(self) -> Iterator[Dict[str, Any]]:
     @lru_cache(1)
     def item_collection(self) -> ItemCollection:
         """
-        Get the matching items as a :ref:`pystac.ItemCollection`.
+        Get the matching items as a :py:class:`pystac.ItemCollection`.
 
         Return:
             ItemCollection: The item collection
@@ -745,11 +744,13 @@ def item_collection_as_dict(self) -> Dict[str, Any]:
     # not caching these, since they're cached in the implementation
 
     def get_item_collections(self) -> Iterator[ItemCollection]:
-        """DEPRECATED. Use :meth:`ItemSearch.item_collections` instead.
+        """DEPRECATED
+
+        .. deprecated:: 0.4.0
+            Use :meth:`ItemSearch.pages` instead.
 
         Yields:
-            ItemCollection : a group of Items matching the search criteria within an
-            ItemCollection
+            ItemCollection : a group of Items matching the search criteria.
         """
         warnings.warn(
             "get_item_collections() is deprecated, use pages() instead",
@@ -758,21 +759,26 @@ def get_item_collections(self) -> Iterator[ItemCollection]:
         return self.pages()
 
     def item_collections(self) -> Iterator[ItemCollection]:
-        """Iterator that yields ItemCollection objects.  Each ItemCollection is
-        a page of results from the search.
+        """DEPRECATED
+
+        .. deprecated:: 0.5.0
+            Use :meth:`ItemSearch.pages` instead.
 
         Yields:
             ItemCollection : a group of Items matching the search criteria within an
             ItemCollection
         """
         warnings.warn(
-            "'item_collections()' is deprecated, use 'pages()' instead",
+            "item_collections() is deprecated, use pages() instead",
             DeprecationWarning,
         )
         return self.pages()
 
     def get_items(self) -> Iterator[Item]:
-        """DEPRECATED. Use :meth:`ItemSearch.items` instead.
+        """DEPRECATED.
+
+        .. deprecated:: 0.4.0
+            Use :meth:`ItemSearch.items` instead.
 
         Yields:
             Item : each Item matching the search criteria
@@ -784,8 +790,7 @@ def get_items(self) -> Iterator[Item]:
         return self.items()
 
     def get_all_items(self) -> ItemCollection:
-        """
-        Get the matching items as a :ref:`pystac.ItemCollection`.
+        """DEPRECATED
 
         .. deprecated:: 0.4.0
            Use :meth:`ItemSearch.item_collection` instead.
@@ -794,23 +799,22 @@ def get_all_items(self) -> ItemCollection:
             item_collection : ItemCollection
         """
         warnings.warn(
-            "get_all_items is deprecated, use 'item_collection' instead.",
+            "get_all_items() is deprecated, use item_collection() instead.",
             DeprecationWarning,
         )
         return self.item_collection()
 
     def get_all_items_as_dict(self) -> Dict[str, Any]:
-        """Get items as a FeatureCollection dictionary.
+        """DEPRECATED
 
-        Convenience method that gets all items from all pages, up to
-        the number provided by the max_items parameter, and returns an array of
-        dictionaries.
+        .. deprecated:: 0.4.0
+           Use :meth:`ItemSearch.item_collection_as_dict` instead.
 
         Return:
             Dict : A GeoJSON FeatureCollection
         """
         warnings.warn(
-            "'get_all_items_as_dict' is deprecated, use 'item_collection_as_dict' "
+            "get_all_items_as_dict() is deprecated, use item_collection_as_dict() "
             "instead.",
             DeprecationWarning,
         )