{"id":13735195,"url":"https://github.com/stac-utils/stac-asset","last_synced_at":"2025-06-23T17:12:05.449Z","repository":{"id":169099568,"uuid":"644565166","full_name":"stac-utils/stac-asset","owner":"stac-utils","description":"Read and download STAC Assets, using a variety of authentication schemes","archived":false,"fork":false,"pushed_at":"2024-11-11T12:10:11.000Z","size":399,"stargazers_count":41,"open_issues_count":15,"forks_count":8,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-11-11T13:19:40.748Z","etag":null,"topics":["geospatial","stac"],"latest_commit_sha":null,"homepage":"https://stac-asset.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stac-utils.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-23T19:38:23.000Z","updated_at":"2024-11-11T12:10:13.000Z","dependencies_parsed_at":"2023-09-29T03:40:49.450Z","dependency_job_id":"b7012b03-b544-4399-b9da-771eb3bb64de","html_url":"https://github.com/stac-utils/stac-asset","commit_stats":{"total_commits":157,"total_committers":6,"mean_commits":"26.166666666666668","dds":"0.21019108280254772","last_synced_commit":"41a8274e643c7cbf7720b08b980ee4c1e24205ef"},"previous_names":["gadomski/stac-asset"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-asset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-asset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-asset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fstac-asset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stac-utils","download_url":"https://codeload.github.com/stac-utils/stac-asset/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224727173,"owners_count":17359532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geospatial","stac"],"created_at":"2024-08-03T03:01:04.047Z","updated_at":"2024-11-15T03:31:31.427Z","avatar_url":"https://github.com/stac-utils.png","language":"Python","funding_links":[],"categories":["`Python` processing of optical imagery (non deep learning)"],"sub_categories":["Cloud Native Geospatial"],"readme":"# stac-asset\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/stac-utils/stac-asset/ci.yaml?style=for-the-badge)](https://github.com/stac-utils/stac-asset/actions/workflows/ci.yaml)\n[![Read the Docs](https://img.shields.io/readthedocs/stac-asset?style=for-the-badge)](https://stac-asset.readthedocs.io/en/stable/)\n[![PyPI](https://img.shields.io/pypi/v/stac-asset?style=for-the-badge)](https://pypi.org/project/stac-asset)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=for-the-badge)](./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 \u003e 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 \u0026\u0026 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-asset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstac-utils%2Fstac-asset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fstac-asset/lists"}