stac-asset

Download STAC Assets using a variety of authentication schemes.

Installation

pip install stac-asset

Usage

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, ".")

To download an item using the command line:

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

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

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