Updates and fixes to README, index, quickstart, and usage

.github/pull_request_template.md

@@ -10,4 +10,4 @@
 
 - [ ] Code is formatted
 - [ ] Tests pass
-- [ ] Changes are added to the [CHANGELOG](https://github.com/stac-utils/pystac-api-client/blob/main/CHANGELOG.md)
+- [ ] Changes are added to CHANGELOG.md

README.md

@@ -10,11 +10,27 @@ A Python client for working with [STAC](https://stacspec.org/) APIs.
 
 ## Installation
 
-Install from PyPi.
-Other than [PySTAC](https://pystac.readthedocs.io) itself, the only dependencies for **pystac-client** are the Python [requests](https://docs.python-requests.org) and [dateutil](https://dateutil.readthedocs.io) libraries.
+PySTAC Client is published to PyPi as [pystac-client](https://pypi.org/project/pystac-client/).
+
+The only direct Python dependencies of **pystac-client** are [PySTAC](https://pystac.readthedocs.io),
+[requests](https://docs.python-requests.org), and [dateutil](https://dateutil.readthedocs.io).
+
+pip:
+
+```shell
+pip install pystac-client
+```
+
+uv:
+
+```shell
+uv add pystac-client
+```
+
+poetry:
 
 ```shell
-python -m pip install pystac-client
+poetry add pystac-client
 ```
 
 ## Documentation

docs/index.rst

@@ -1,17 +1,10 @@
-.. pystac-client documentation master file, created by
-   sphinx-quickstart on Sat Feb 27 14:27:12 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 PySTAC Client Documentation
 ===========================
 
-The STAC Python Client (``pystac_client``) is a Python package for working with STAC
-Catalogs and APIs that conform to the
-`STAC <https://github.com/radiantearth/stac-spec>`__ and
-`STAC API <https://github.com/radiantearth/stac-api-spec>`__ specs in a seamless way.
+PySTAC Client is a is a Python package for working with `STAC <https://github.com/radiantearth/stac-spec>`__
+Catalogs and `STAC APIs <https://github.com/radiantearth/stac-api-spec>`__.
 PySTAC Client builds upon PySTAC through higher-level functionality and ability to
-leverage STAC API search endpoints.
+access STAC API search endpoints.
 
 STAC Versions
 =============
@@ -20,7 +13,7 @@ STAC Versions
 | pystac-client | STAC spec | STAC API Spec               |
 +===============+===========+=============================+
 | 0.8.x         | 1.0.x     | 1.0.0-beta.1 - 1.0.0        |
-+ --------------+-----------+-----------------------------+
++---------------+-----------+-----------------------------+
 | 0.7.x         | 1.0.x     | 1.0.0-beta.1 - 1.0.0        |
 +---------------+-----------+-----------------------------+
 | 0.6.x         | 1.0.x     | 1.0.0-beta.1 - 1.0.0-rc.2   |
@@ -37,13 +30,28 @@ STAC Versions
 Installation
 ------------
 
+``pystac-client`` requires `Python >=3.10 <https://www.python.org/>`__.
+
+pip:
+
 .. code-block:: console
 
    $ pip install pystac-client
 
-``pystac_client`` requires `Python >=3.8 <https://www.python.org/>`__.
+uv:
+
+.. code-block:: console
+
+   $ uv add pystac-client
+
+poetry:
+
+.. code-block:: console
+
+   $ poetry add pystac-client
+
 
-This will install the dependencies :doc:`PySTAC <pystac:index>`,
+This will install the dependencies :doc:`pystac <pystac:index>`,
 :doc:`python-dateutil <dateutil:index>`, and :doc:`requests <requests:index>`.
 
 Acknowledgements

docs/quickstart.rst

@@ -1,13 +1,13 @@
 Quickstart
 ----------
 
-pystac-client can be used as either a Command Line Interface (CLI) or a
+PySTAC Client can be used as either a Command Line Interface (CLI) or a
 Python library.
 
 CLI
 ~~~
 
-Use the CLI to quickly make item- or collection-level searches and
+Use the CLI to quickly perform Item or Collection searches and
 output or save the results.
 
 The ``--matched`` switch performs a search with limit=1 so does not get
@@ -108,7 +108,7 @@ a spatial extent that intersects Scandinavia.
     43 items matched
 
 Since most STAC APIs have not yet implemented the `collection search 
-extension <https://github.com/stac-api-extensions/collection-search>`_, 
+extension <https://github.com/stac-api-extensions/collection-search>`__, 
 ``pystac-client`` will perform a limited client-side 
 filter on the full list of collections using only the ``bbox``, 
 ``datetime``, and ``q`` (free-text search) parameters.
@@ -120,50 +120,62 @@ applied client-side.
 Python
 ~~~~~~
 
-To use the Python library, first a Client instance is created for a
-specific STAC API (use the root URL):
+First, create a Client instance configured to use a specific STAC API by the root URL of that API. For this example, we
+will use `Earth Search <https://earth-search.aws.element84.com/v1>`__.
 
 .. code-block:: python
 
     from pystac_client import Client
 
     client = Client.open("https://earth-search.aws.element84.com/v1")
 
-Create an item-level search:
+Create an Item Search instance that represents a search to run. This does not actually run a search yet --
+that does not happen until a method is called that requires data from the STAC API.
 
 .. code-block:: python
 
     search = client.search(
         max_items=10,
-        collections=['sentinel-2-l2a'],
+        collections=["sentinel-2-c1-l2a"],
         bbox=[-72.5,40.5,-72,41]
     )
+
+Calling ``matched()`` will send a request to the STAC API and retrieve a single item and metadata about how many Items
+match the search criteria.
+
+.. code-block:: python
+
     print(f"{search.matched()} items found")
 
-The ``items()`` iterator method can be used to iterate through all resulting items.
+The ``items()`` iterator method can be used to iterate through all resulting items. This iterator
+hides the pagination behavior that the may occur if there are sufficient results. Be careful with this
+method -- you could end up iterating over the entire catalog if ``max_items`` is not set!
 
 .. code-block:: python
 
     for item in search.items():
         print(item.id)
 
-Use `item_collection()` to convert all Items from a search into a single `PySTAC
+Use ``item_collection()`` to convert all Items from a search into a single `PySTAC
 ItemCollection <https://pystac.readthedocs.io/en/latest/api/pystac.html#pystac.ItemCollection>`__.
-The ``ItemCollection`` can then be saved as a GeoJSON FeatureCollection.
+The ``ItemCollection`` can then be saved as a GeoJSON FeatureCollection. This requires retrieving all
+of the results from the search, so it may take some time to retrieve all the paginated responses.
 
 .. code-block:: python
 
     item_collection = search.item_collection()
-    item_collection.save_object('my_itemcollection.json')
-
+    item_collection.save_object("my_itemcollection.json")
 
-Create a collection-level search:
+Some STAC APIs also implement the Collection Search Extension.
 
 .. code-block:: python
 
+    client = Client.open("https://emc.spacebel.be")
+
     collection_search = client.collection_search(
-        q='"sentinel-2" OR "sentinel-1"',
+        q='Sentinel-6',
     )
+
     print(f"{collection_search.matched()} collections found")
 
 
@@ -172,6 +184,6 @@ resulting collections.
 
 .. code-block:: python
 
-    for collection in collection_search.collections():
-        print(collection.id)
+    for collection in collection_search.collections_as_dicts():
+        print(collection.get("id"))
 

docs/usage.rst

@@ -95,11 +95,12 @@ optional specifications:
 
 The :meth:`pystac_client.Client.conforms_to` method is used to check conformance
 against conformance classes (specs). To check an API for support for a given spec,
-pass the `conforms_to` function the name of a :class:`ConformanceClasses`.
+pass the `conforms_to` function a :class:`ConformanceClasses` enum value.
 
 .. code-block:: python
 
-    >>> catalog.conforms_to("ITEM_SEARCH")
+    >>> from pystac_client import ConformanceClasses
+    >>> catalog.conforms_to(ConformanceClasses.ITEM_SEARCH)
     True
 
 If the API does not advertise conformance with a particular spec, but it does support
@@ -110,9 +111,9 @@ there are no ``"conformsTo"`` uris set at all. But they can be explicitly set:
 
     >>> catalog = Client.open("https://earth-search.aws.element84.com/v0")
     <stdin>:1: NoConformsTo: Server does not advertise any conformance classes.
-    >>> catalog.conforms_to("ITEM_SEARCH")
+    >>> catalog.conforms_to(ConformanceClasses.ITEM_SEARCH)
     False
-    >>> catalog.add_conforms_to("ITEM_SEARCH")
+    >>> catalog.add_conforms_to(ConformanceClasses.ITEM_SEARCH)
 
 Note, updating ``"conformsTo"`` does not change what the server supports, it just
 changes PySTAC client's understanding of what the server supports.