diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5cd7316c..84829cd7 100644 --- a/.github/pull_request_template.md +++ b/.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) \ No newline at end of file +- [ ] Changes are added to CHANGELOG.md diff --git a/README.md b/README.md index f5c49c5f..c0923363 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,12 @@ 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). + +To install with pip, run: ```shell python -m pip install pystac-client diff --git a/docs/index.rst b/docs/index.rst index a27ac16c..3743f5fd 100644 --- a/docs/index.rst +++ b/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 `__ and -`STAC API `__ specs in a seamless way. +PySTAC Client is a Python package for working with `STAC `__ +Catalogs and `STAC APIs `__. 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,15 @@ STAC Versions Installation ------------ -.. code-block:: console +``pystac-client`` requires `Python >=3.10 `__. - $ pip install pystac-client +To install with pip, run: + +.. code-block:: console -``pystac_client`` requires `Python >=3.8 `__. + $ python -m pip install pystac-client -This will install the dependencies :doc:`PySTAC `, +This will install the dependencies :doc:`pystac `, :doc:`python-dateutil `, and :doc:`requests `. Acknowledgements diff --git a/docs/quickstart.rst b/docs/quickstart.rst index dac1c4d5..36b60d57 100644 --- a/docs/quickstart.rst +++ b/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 `_, +extension `__, ``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,8 +120,8 @@ 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 `__. .. code-block:: python @@ -129,40 +129,51 @@ specific STAC API (use the root URL): 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 `__. -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. Earth Search does not, so we use the +ORNL_CLOUD CMR-STAC Catalog instead: .. code-block:: python + client = Client.open("https://cmr.earthdata.nasa.gov/stac/ORNL_CLOUD") collection_search = client.collection_search( - q='"sentinel-2" OR "sentinel-1"', + q="rain", ) print(f"{collection_search.matched()} collections found") diff --git a/pystac_client/collection_search.py b/pystac_client/collection_search.py index de04c2d3..b800f3ac 100644 --- a/pystac_client/collection_search.py +++ b/pystac_client/collection_search.py @@ -372,7 +372,6 @@ def matched(self) -> int | None: count = len(page["collections"]) for page in iter: - print(f"found {len(page['collections'])} on the next page") count += len(page["collections"]) found = count