stac-asset

Download STAC Assets using a variety of authentication schemes.

Installation

pip install stac-asset

To use the command-line interface (CLI):

pip install 'stac-asset[cli]'

Usage

API

Here's how to download a STAC Item and all of its assets to a local directory using the top-level function. The correct client will be guessed from the assets' href. Each asset's href will be updated to point to the local file.

import stac_asset

href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"
await stac_asset.download_item_from_href(href, ".")

CLI

To download an item using the command line:

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 search, and save the item collection to a file named item-collection.json:

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:

stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 -c landsat-c2-l2 --max-items 1 | \
    stac-asset download -i rendered_preview -q

If you do a lot of downloads, you may want an alias:

alias stac-download="stac-asset download"

See the documentation for more examples and complete API 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.

S3Client

To use the requester_pays option, you need to configure your AWS credentials. See the AWS documentation for instructions.

USGS EROS

The USGS EROS system, which hosts landsat data, requires a personal access token to download assets. Here's how to create and use your personal access token with stac-asset:

1. Create a new personal access token
2. Set two environment variables:
   • USGS_EROS_USERNAME to your username (found in the top right of the web UI)
   • USGS_EROS_PAT to your personal access token
3. Use UsgsErosClient.default() to create a new client.

You can also provide your username and password to the UsgsErosClient.login method.

Earthdata

You'll need a personal access token.

1. Create a new personal access token by going to https://urs.earthdata.nasa.gov/profile and then clicking "Generate Token" (you'll need to log in).
2. Set an enviornment variable named EARTHDATA_PAT to your token.
3. Use EarthdataClient.default() to create a new client.

You can also provide your token directly to EarthdataClient.login().

Design goals

As determined during a meeting at the Element 84 offices (formerly Azavea offices) on 2023-05-24.

• async-first
• Allow range requests
• Download functionality
• Update STAC items to point to new hrefs on download
• Allow byte-stream access
• Protocols:
  • http
  • s3
    • requestor pays
    • custom endpoint
  • custom authentication
    • Planetary Computer
    • USGS EROS
    • NASA
• Copy directly from source to destination ("skip local")
• Add new assets to an item
• Update an existing asset
• Delete assets
• Templated paths on download
• (possible) Support the file extension's local path
• Checksum validation and creation
• CLI

Versioning

This project does its best to adhere to semantic versioning. 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 to report bugs and request new features. Use Github pull requests to fix bugs and propose new features.

Developing

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

git clone git@github.com:gadomski/stac-asset.git
cd stac-asset
pip install '.[dev]'
pre-commit install

Testing

All network-touching tests are disabled by default, because we can't use pytest-vcr (https://github.com/kevin1024/vcrpy/issues/597), and repeatedly hitting the network during testing and CI is bad behavior. To enable network-touching tests:

pytest --network-access

Some tests are client-specific and need your environment to be configured correctly. See each client's documentation for instructions on setting up your environment for each client. If your environment is not configured for a certain client, that client's tests are skipped.

Docs

Install the documentation dependencies:

pip install -e '.[docs]'

Then, build the docs:

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

It can be handy to use sphinx-autobuild if you're doing a lot of doc work:

pip install sphinx-autobuild
sphinx-autobuild docs docs/_build/html

License

Apache-2.0