From 37281b9b4eed4aea53ce9c8a5b872bfdeae0c51c Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Sat, 19 Apr 2025 06:35:53 -0400 Subject: [PATCH 1/6] Updates and fixes to README, index, quickstart, and usage --- README.md | 22 +++++++++++++++++++--- docs/index.rst | 34 +++++++++++++++++++++------------- docs/quickstart.rst | 44 ++++++++++++++++++++++++++++---------------- docs/usage.rst | 9 +++++---- 4 files changed, 73 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index f5c49c5f..cb36023b 100644 --- a/README.md +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index a27ac16c..dc15c6ea 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 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,28 @@ STAC Versions Installation ------------ +``pystac-client`` requires `Python >=3.10 `__. + +pip: + .. code-block:: console $ pip install pystac-client -``pystac_client`` requires `Python >=3.8 `__. +uv: + +.. code-block:: console + + $ uv add pystac-client + +poetry: + +.. code-block:: console + + $ poetry add 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..fa79ee1c 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,41 +129,53 @@ 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. .. 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")) diff --git a/docs/usage.rst b/docs/usage.rst index 714d0bce..5800f32c 100644 --- a/docs/usage.rst +++ b/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") :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. From 8fe4b7c0caf04578a851bc1596e8faa4029e7fcc Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Sat, 19 Apr 2025 06:37:22 -0400 Subject: [PATCH 2/6] remove incorrect link in pr template --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 4600fde26811a9344e8661ec1dbefb81fe7906cc Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 21 Apr 2025 14:54:45 -0400 Subject: [PATCH 3/6] Update docs/index.rst Co-authored-by: Julia Signell --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index dc15c6ea..bcffbad9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ PySTAC Client Documentation =========================== -PySTAC Client is a is a Python package for working with `STAC `__ +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 access STAC API search endpoints. From debbb0afad5f58168b2f4dca6e270ab6d5fa4b52 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 21 Apr 2025 20:35:37 -0400 Subject: [PATCH 4/6] revert install instructions --- README.md | 16 ++-------------- docs/index.rst | 17 ++--------------- 2 files changed, 4 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index cb36023b..c0923363 100644 --- a/README.md +++ b/README.md @@ -15,22 +15,10 @@ PySTAC Client is published to PyPi as [pystac-client](https://pypi.org/project/p 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: +To install with pip, run: ```shell -pip install pystac-client -``` - -uv: - -```shell -uv add pystac-client -``` - -poetry: - -```shell -poetry add pystac-client +python -m pip install pystac-client ``` ## Documentation diff --git a/docs/index.rst b/docs/index.rst index bcffbad9..3743f5fd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,24 +32,11 @@ Installation ``pystac-client`` requires `Python >=3.10 `__. -pip: +To install with pip, run: .. code-block:: console - $ pip install pystac-client - -uv: - -.. code-block:: console - - $ uv add pystac-client - -poetry: - -.. code-block:: console - - $ poetry add pystac-client - + $ python -m pip install pystac-client This will install the dependencies :doc:`pystac `, :doc:`python-dateutil `, and :doc:`requests `. From bb53ea5de96cd1da24ef71a11b9a04f4c5699ffe Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 21 Apr 2025 20:51:35 -0400 Subject: [PATCH 5/6] User ORNL CLOUD for collections search --- docs/quickstart.rst | 13 ++++++------- pystac_client/collection_search.py | 1 - 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index fa79ee1c..36b60d57 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -166,16 +166,15 @@ of the results from the search, so it may take some time to retrieve all the pag item_collection = search.item_collection() item_collection.save_object("my_itemcollection.json") -Some STAC APIs also implement the Collection Search Extension. +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://emc.spacebel.be") - + client = Client.open("https://cmr.earthdata.nasa.gov/stac/ORNL_CLOUD") collection_search = client.collection_search( - q='Sentinel-6', + q="rain", ) - print(f"{collection_search.matched()} collections found") @@ -184,6 +183,6 @@ resulting collections. .. code-block:: python - for collection in collection_search.collections_as_dicts(): - print(collection.get("id")) + for collection in collection_search.collections(): + print(collection.id) 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 From b782bcb4fc9b07f19c720ae38a0385475bf02adf Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 21 Apr 2025 20:55:22 -0400 Subject: [PATCH 6/6] revert usage --- docs/usage.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 5800f32c..714d0bce 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -95,12 +95,11 @@ 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 a :class:`ConformanceClasses` enum value. +pass the `conforms_to` function the name of a :class:`ConformanceClasses`. .. code-block:: python - >>> from pystac_client import ConformanceClasses - >>> catalog.conforms_to(ConformanceClasses.ITEM_SEARCH) + >>> catalog.conforms_to("ITEM_SEARCH") True If the API does not advertise conformance with a particular spec, but it does support @@ -111,9 +110,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") :1: NoConformsTo: Server does not advertise any conformance classes. - >>> catalog.conforms_to(ConformanceClasses.ITEM_SEARCH) + >>> catalog.conforms_to("ITEM_SEARCH") False - >>> catalog.add_conforms_to(ConformanceClasses.ITEM_SEARCH) + >>> catalog.add_conforms_to("ITEM_SEARCH") Note, updating ``"conformsTo"`` does not change what the server supports, it just changes PySTAC client's understanding of what the server supports.