| Name | stac-asset JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Read and download STAC assets across platforms and providers |
| upload_time | 2024-04-24 13:06:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | Apache-2.0 |
| keywords |
stac
async
|
| 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
pip install stac-asset
```
To use the command-line interface (CLI):
```shell
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
```
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
Clone, install with the dev dependencies, and install **pre-commit**:
```shell
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://pytest-vcr.readthedocs.io/en/latest/) (<https://github.com/kevin1024/vcrpy/issues/597>), and repeatedly hitting the network during testing and CI is bad behavior.
To enable network-touching tests:
```shell
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
Install the documentation dependencies:
```shell
pip install -e '.[docs]'
```
Then, build the docs:
```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
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.9",
"maintainer_email": null,
"keywords": "stac, async",
"author": null,
"author_email": "Pete Gadomski <pete.gadomski@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/19/c6/01421d4ee31fa78eb8ab28117a3e2c479350f74bf810b86419fb8d6723f1/stac_asset-0.3.0.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\npip install stac-asset\n```\n\nTo use the command-line interface (CLI):\n\n```shell\npip 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\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\nClone, install with the dev dependencies, and install **pre-commit**:\n\n```shell\ngit clone git@github.com:stac-utils/stac-asset.git\ncd stac-asset\npip install '.[dev]'\npre-commit install\n```\n\n### Testing\n\nAll network-touching tests are disabled by default, because we can't use [pytest-vcr](https://pytest-vcr.readthedocs.io/en/latest/) (<https://github.com/kevin1024/vcrpy/issues/597>), and repeatedly hitting the network during testing and CI is bad behavior.\nTo enable network-touching tests:\n\n```shell\npytest --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\nInstall the documentation dependencies:\n\n```shell\npip install -e '.[docs]'\n```\n\nThen, build the docs:\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\npip 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.3.0",
"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": [
"stac",
" async"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35211fc155e6754f407b3f2a2feda13bccd19a51c1ab6a763b4e39e697c29a33",
"md5": "57b4c1ef5cd4170ebc57d33ed2dc525f",
"sha256": "4a96de1a23149f7f01b8353816672b4eaedad1cb93a6e0b070afc1c412f46a15"
},
"downloads": -1,
"filename": "stac_asset-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "57b4c1ef5cd4170ebc57d33ed2dc525f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 33687,
"upload_time": "2024-04-24T13:06:52",
"upload_time_iso_8601": "2024-04-24T13:06:52.368226Z",
"url": "https://files.pythonhosted.org/packages/35/21/1fc155e6754f407b3f2a2feda13bccd19a51c1ab6a763b4e39e697c29a33/stac_asset-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "19c601421d4ee31fa78eb8ab28117a3e2c479350f74bf810b86419fb8d6723f1",
"md5": "e049132787f8e2173b5031a231dd0820",
"sha256": "73f77eb4d19915c550c49736a3f8c7276d7e4a642fcf0091aa480111b15e8845"
},
"downloads": -1,
"filename": "stac_asset-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e049132787f8e2173b5031a231dd0820",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 31672,
"upload_time": "2024-04-24T13:06:53",
"upload_time_iso_8601": "2024-04-24T13:06:53.701560Z",
"url": "https://files.pythonhosted.org/packages/19/c6/01421d4ee31fa78eb8ab28117a3e2c479350f74bf810b86419fb8d6723f1/stac_asset-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-24 13:06:53",
"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"
}
