| Name | stac-asset JSON |
| Version |
0.4.6
JSON |
| download |
| home_page | None |
| Summary | Read and download STAC assets across platforms and providers |
| upload_time | 2024-11-05 21:06:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | Apache-2.0 |
| keywords |
async
stac
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# stac-asset
[](https://github.com/stac-utils/stac-asset/actions/workflows/ci.yaml)
[](https://stac-asset.readthedocs.io/en/stable/)
[](https://pypi.org/project/stac-asset)
[](./CODE_OF_CONDUCT)
Download STAC Assets using a variety of authentication schemes.
## Installation
```shell
python -m pip install stac-asset
```
To use the command-line interface (CLI):
```shell
python -m 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
Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
Then clone, sync, and install **pre-commit**:
```shell
git clone git@github.com:stac-utils/stac-asset.git
cd stac-asset
uv sync
pre-commit install
```
### Testing
Some network-touching tests are disabled by default.
To enable these tests:
```shell
uv run 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
To build:
```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
uv 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)
Raw data
{
"_id": null,
"home_page": null,
"name": "stac-asset",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "async, stac",
"author": null,
"author_email": "Pete Gadomski <pete.gadomski@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/70/ed/e23ab4c849cd164ad44b1498787c16ab414543414fac46c457abfaee68b1/stac_asset-0.4.6.tar.gz",
"platform": null,
"description": "# stac-asset\n\n[](https://github.com/stac-utils/stac-asset/actions/workflows/ci.yaml)\n[](https://stac-asset.readthedocs.io/en/stable/)\n[](https://pypi.org/project/stac-asset)\n[](./CODE_OF_CONDUCT)\n\nDownload STAC Assets using a variety of authentication schemes.\n\n## Installation\n\n```shell\npython -m pip install stac-asset\n```\n\nTo use the command-line interface (CLI):\n\n```shell\npython -m pip install 'stac-asset[cli]'\n```\n\n## Usage\n\nWe have a Python API and a command-line interface (CLI).\n\n### API\n\nHere'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.\nThe correct [client](#clients) will be guessed from the assets' href.\nEach asset's href will be updated to point to the local file.\n\n```python\nimport pystac\nimport stac_asset\nimport asyncio\n\nasync def main():\n href = \"https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json\"\n item = pystac.read_file(href)\n item = await stac_asset.download_item(item, \".\")\n return item\n\nasyncio.run(main())\n```\n\nIf you're working in a fully synchronous application, you can use our blocking interface:\n\n```python\nimport stac_asset.blocking\nhref = \"https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json\"\nitem = pystac.read_file(href)\nitem = stac_asset.blocking.download_item(item, \".\")\n```\n\nNote that the above will not work in some environments like Jupyter notebooks which already have their own `asyncio` loop running.\nTo get around this, you can use [`nest_asyncio`](https://pypi.org/project/nest-asyncio/).\nSimply run the following before using any functions from `stac_asset.blocking`.\n\n```python\nimport nest_asyncio\nnest_asyncio.apply()\n```\n\n### CLI\n\nTo download an item using the command line:\n\n```shell\nstac-asset download \\\n https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json\n```\n\nTo 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`:\n\n```shell\nstac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \\\n -c landsat-c2-l2 \\\n --max-items 1 | \\\n stac-asset download > item-collection.json\n```\n\nIf you'd like to only download certain assets, e.g. a preview image, you can use the include `-i` flag:\n\n```shell\nstac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \\\n -c landsat-c2-l2 \\\n --max-items 1 | \\\n stac-asset download -i rendered_preview -q\n```\n\nBy 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):\n\n```shell\nstac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \\\n -c landsat-c2-l2 \\\n --max-items 1 | \\\n stac-asset download -i rendered_preview -p '${collection}'\n```\n\nSee [the documentation](https://stac-asset.readthedocs.io/en/latest/index.html) for more examples and complete API and CLI documentation.\n\n### Clients\n\nThis library comes with several clients, each tailored for a specific data provider model and authentication scheme.\nSome clients require some setup before use; they are called out in this table, and the details are provided below.\n\n| Name | Description | Notes |\n| -- | -- | -- |\n| `HttpClient` | Simple HTTP client without any authentication | |\n| `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 |\n| `FilesystemClient` | Moves files from place to place on a local filesystem | Mostly used for testing |\n| `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 |\n| `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) |\n\nFor information about configuring each client, see the [API documentation](https://stac-asset.readthedocs.io/en/latest/api.html) for that client.\n\n## Versioning\n\nThis project does its best to adhere to [semantic versioning](https://semver.org/).\nAny module, class, constant, or function that does not begin with a `_` is considered part of our public API for versioning purposes.\nOur command-line interface (CLI) is NOT considered part of our public API, and may change in breaking ways at any time.\nIf you need stability promises, use our API.\n\n## Contributing\n\nUse Github [issues](https://github.com/stac-utils/stac-asset/issues) to report bugs and request new features.\nUse Github [pull requests](https://github.com/stac-utils/stac-asset/pulls) to fix bugs and propose new features.\n\n## Developing\n\nInstall [uv](https://docs.astral.sh/uv/getting-started/installation/).\nThen clone, sync, and install **pre-commit**:\n\n```shell\ngit clone git@github.com:stac-utils/stac-asset.git\ncd stac-asset\nuv sync\npre-commit install\n```\n\n### Testing\n\nSome network-touching tests are disabled by default.\nTo enable these tests:\n\n```shell\nuv run pytest --network-access\n```\n\nSome tests are client-specific and need your environment to be configured correctly.\nSee [each client's documentation](#clients) for instructions on setting up your environment for each client.\n\n### Docs\n\nTo build:\n\n```shell\nmake -C docs html && open docs/_build/html/index.html\n```\n\nIt can be handy to use [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/) if you're doing a lot of doc work:\n\n```shell\nuv pip install sphinx-autobuild\nsphinx-autobuild --watch src docs docs/_build/html\n```\n\n## License\n\n[Apache-2.0](https://github.com/stac-utils/stac-asset/blob/main/LICENSE)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Read and download STAC assets across platforms and providers",
"version": "0.4.6",
"project_urls": {
"CHANGELOG": "https://github.com/stac-utils/stac-asset/blob/main/CHANGELOG.md",
"Github": "https://github.com/stac-utils/stac-asset",
"Issues": "https://github.com/stac-utils/stac-asset/issues"
},
"split_keywords": [
"async",
" stac"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "acad173f9fc405b787b819c5285192d8d44e683b648d29cee5252567c05fe470",
"md5": "b809fd304818891d483de26331aef92e",
"sha256": "901f721589f58dcc6c1dd0dbf6baa8dc3b216f948602b770f1d7d2eb75781acd"
},
"downloads": -1,
"filename": "stac_asset-0.4.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b809fd304818891d483de26331aef92e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 37163,
"upload_time": "2024-11-05T21:06:29",
"upload_time_iso_8601": "2024-11-05T21:06:29.213811Z",
"url": "https://files.pythonhosted.org/packages/ac/ad/173f9fc405b787b819c5285192d8d44e683b648d29cee5252567c05fe470/stac_asset-0.4.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "70ede23ab4c849cd164ad44b1498787c16ab414543414fac46c457abfaee68b1",
"md5": "49aab0a1df4cf7688900d4fecb167766",
"sha256": "4ae94a6055a8084542563bc010df238d810863cfd44e26b822a14a9a21650f18"
},
"downloads": -1,
"filename": "stac_asset-0.4.6.tar.gz",
"has_sig": false,
"md5_digest": "49aab0a1df4cf7688900d4fecb167766",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 165681,
"upload_time": "2024-11-05T21:06:30",
"upload_time_iso_8601": "2024-11-05T21:06:30.861078Z",
"url": "https://files.pythonhosted.org/packages/70/ed/e23ab4c849cd164ad44b1498787c16ab414543414fac46c457abfaee68b1/stac_asset-0.4.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-05 21:06:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stac-utils",
"github_project": "stac-asset",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stac-asset"
}
