Read and download STAC assets across platforms and providers
Project description
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.
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 | No additional setup required, works out of the box |
UsgsErosClient |
Uses a token-based authentication workflow to download data, e.g. landsat, from USGS EROS | Requires creation of a personal access token, see section below |
EarthdataClient |
Uses a token-based authentication to download data, from some Earthdata providers, e.g. DAACs | Requires creation of a personal access token, see section 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:
- Create a new personal access token
- 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
- 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.
- 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).
- Set an enviornment variable named
EARTHDATA_PAT
to your token. - Use
EarthdataClient.default()
to create a new client.
You can also provide your token directly to EarthdataClient.login()
.
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:stac-utils/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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file stac-asset-0.1.1.tar.gz
.
File metadata
- Download URL: stac-asset-0.1.1.tar.gz
- Upload date:
- Size: 23.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.4
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4ad6a3b466cded13063282b97928c68e70bc14dc8f1a1913f7841d7e48281b1d |
|
MD5 | 2448d4e1ae2948cf83867ab7ccfae30c |
|
BLAKE2b-256 | 8d254c1f25b43e33331078bb43d2ca3fa70478c38a4f37547f17fcf99d2c2ee5 |
File details
Details for the file stac_asset-0.1.1-py3-none-any.whl
.
File metadata
- Download URL: stac_asset-0.1.1-py3-none-any.whl
- Upload date:
- Size: 24.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.4
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9bffa82b1364cee0ecb4cd67a653aad135638d59d4a26a7b55ec0095a6f4efe7 |
|
MD5 | dc8bdc09d3b1b0cfb0518fda8eb10287 |
|
BLAKE2b-256 | 2dc3fc1d36deae841caa893a1fdc9e1a9f03641e8ce875083bdbf3b348a763bc |