Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stac-utils/stac-asset

Read and download STAC Assets, using a variety of authentication schemes
https://github.com/stac-utils/stac-asset

geospatial stac

Last synced: 3 months ago
JSON representation

Read and download STAC Assets, using a variety of authentication schemes

Awesome Lists containing this project

README 

        
# stac-asset



[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/stac-utils/stac-asset/ci.yaml?style=for-the-badge)](https://github.com/stac-utils/stac-asset/actions/workflows/ci.yaml)

[![Read the Docs](https://img.shields.io/readthedocs/stac-asset?style=for-the-badge)](https://stac-asset.readthedocs.io/en/stable/)

[![PyPI](https://img.shields.io/pypi/v/stac-asset?style=for-the-badge)](https://pypi.org/project/stac-asset)

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](./CODE_OF_CONDUCT)



Download STAC Assets using a variety of authentication schemes.



## Installation



```shell

pip install stac-asset

```



To use the command-line interface (CLI):



```shell

pip install 'stac-asset[cli]'

```



## Usage



We have a Python API and a command-line interface (CLI).



### API



Here's how to download a STAC [Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) and all of its assets to the current working directory.

The correct [client](#clients) will be guessed from the assets' href.

Each asset's href will be updated to point to the local file.



```python

import pystac

import stac_asset

import asyncio



async def main():

    href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"

    item = pystac.read_file(href)

    item = await stac_asset.download_item(item, ".")

    return item



asyncio.run(main())

```



If you're working in a fully synchronous application, you can use our blocking interface:



```python

import stac_asset.blocking

href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"

item = pystac.read_file(href)

item = stac_asset.blocking.download_item(item, ".")

```



Note that the above will not work in some environments like Jupyter notebooks which already have their own `asyncio` loop running.

To get around this, you can use [`nest_asyncio`](https://pypi.org/project/nest-asyncio/).

Simply run the following before using any functions from `stac_asset.blocking`.



```python

import nest_asyncio

nest_asyncio.apply()

```



### CLI



To download an item using the command line:



```shell

stac-asset download \

    https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json

```



To download all assets from the results of a [pystac-client](https://github.com/stac-utils/pystac-client) search, and save the item collection to a file named `item-collection.json`:



```shell

stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \

        -c landsat-c2-l2 \

        --max-items 1 | \

    stac-asset download > item-collection.json

```



If you'd like to only download certain assets, e.g. a preview image, you can use the include `-i` flag:



```shell

stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \

        -c landsat-c2-l2 \

        --max-items 1 | \

    stac-asset download -i rendered_preview -q

```



By default, all assets are stored in a folder named after the item ID. To change this, you can use the `-p` flag and specify a path template using PySTAC layout template [variables](https://pystac.readthedocs.io/en/latest/api/layout.html#pystac.layout.LayoutTemplate):



```shell

stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \

        -c landsat-c2-l2 \

        --max-items 1 | \

    stac-asset download -i rendered_preview -p '${collection}'

```



See [the documentation](https://stac-asset.readthedocs.io/en/latest/index.html) for more examples and complete API and CLI documentation.



### Clients



This library comes with several clients, each tailored for a specific data provider model and authentication scheme.

Some clients require some setup before use; they are called out in this table, and the details are provided below.



| Name | Description | Notes |

| -- | -- | -- |

| `HttpClient` | Simple HTTP client without any authentication | |

| `S3Client` | Simple S3 client | Use `requester_pays=True` in the client initializer to enable access to requester pays buckets, e.g. USGS landsat's public AWS archive |

| `FilesystemClient` | Moves files from place to place on a local filesystem | Mostly used for testing |

| `PlanetaryComputerClient` | Signs urls with the [Planetary Computer Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/) | No additional setup required, works out of the box |

| `EarthdataClient` | Uses a token-based authentication to download data, from _some_ Earthdata providers, e.g. DAACs | Requires creation of a personal access token, see [docs](https://stac-asset.readthedocs.io/en/latest/api.html#stac_asset.EarthdataClient) |



For information about configuring each client, see the [API documentation](https://stac-asset.readthedocs.io/en/latest/api.html) for that client.



## Versioning



This project does its best to adhere to [semantic versioning](https://semver.org/).

Any module, class, constant, or function that does not begin with a `_` is considered part of our public API for versioning purposes.

Our command-line interface (CLI) is NOT considered part of our public API, and may change in breaking ways at any time.

If you need stability promises, use our API.



## Contributing



Use Github [issues](https://github.com/stac-utils/stac-asset/issues) to report bugs and request new features.

Use Github [pull requests](https://github.com/stac-utils/stac-asset/pulls) to fix bugs and propose new features.



## Developing



Clone, install with the dev dependencies, and install **pre-commit**:



```shell

git clone [email protected]:stac-utils/stac-asset.git

cd stac-asset

pip install '.[dev]'

pre-commit install

```



### Testing



Some network-touching tests are disabled by default.

To enable these tests:



```shell

pytest --network-access

```



Some tests are client-specific and need your environment to be configured correctly.

See [each client's documentation](#clients) for instructions on setting up your environment for each client.



### Docs



Install the documentation dependencies:



```shell

pip install -e '.[docs]'

```



Then, build the docs:



```shell

make -C docs html && open docs/_build/html/index.html

```



It can be handy to use [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/) if you're doing a lot of doc work:



```shell

pip install sphinx-autobuild

sphinx-autobuild --watch src docs docs/_build/html

```



## License



[Apache-2.0](https://github.com/stac-utils/stac-asset/blob/main/LICENSE)