stac-asset

Download STAC Assets using a variety of authentication schemes.

Installation

pip install git+https://github.com/gadomski/stac-async

Usage

Download a STAC Item and all of its assets to a local directory. Each Asset's href will be updated to point to the local file.

import stac_async

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

To download an item using the command line:

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

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.

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.login() to create a new client.

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

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

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