| Name | stacrs JSON |
| Version |
0.5.6
JSON |
| download |
| home_page | None |
| Summary | A no-dependency Python package for STAC, using Rust under the hood. |
| upload_time | 2025-02-26 14:44:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
stac
geospatial
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# stacrs
[](https://github.com/stac-utils/stacrs/actions/workflows/ci.yaml)
[](https://stac-utils.github.io/stacrs/latest/)
[](https://pypi.org/project/stacrs)
[](https://anaconda.org/conda-forge/stacrs)
[](./CODE_OF_CONDUCT)
A Python package for [STAC](https://stacspec.org/) using Rust under the hood.
## Why?
Q: We already have [PySTAC](https://github.com/stac-utils/pystac), so why **stacrs**?
A: **stacrs** can
- Read, write, and search [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet)
- Go to and from [arrow](https://arrow.apache.org/) tables, allowing easy interoperability with (e.g.) [GeoPandas](https://geopandas.org/en/stable/)
- `async`
If you don't need those things, **stacrs** probably isn't for you — use **pystac** and its friend, [pystac-client](https://github.com/stac-utils/pystac-client).
## Usage
Install via **pip**:
```shell
# basic
python -m pip install stacrs
# support arrow tables
python -m pip install 'stacrs[arrow]'
```
Or via **conda**:
```shell
conda install conda-forge::stacrs
```
Then:
```python
import stacrs
# Search a STAC API
items = await stacrs.search(
"https://landsatlook.usgs.gov/stac-server",
collections="landsat-c2l2-sr",
intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
sortby="-properties.datetime",
max_items=100,
)
# If you installed with `pystac[arrow]`:
from geopandas import GeoDataFrame
table = await stacrs.search_to_arrow(...)
data_frame = GeoDataFrame.from_arrow(table)
items = stacrs.from_arrow(data_frame.to_arrow())
# Write items to a stac-geoparquet file
await stacrs.write("items.parquet", items)
# Read items from a stac-geoparquet file as an item collection
item_collection = await stacrs.read("items.parquet")
# You can search geoparquet files using DuckDB
# If you want to search a file on s3, make sure to configure your AWS environment first
item_collection = await stacrs.search("s3://bucket/items.parquet", ...)
# Use `search_to` for better performance if you know you'll be writing the items
# to a file
await stacrs.search_to(
"items.parquet",
"https://landsatlook.usgs.gov/stac-server",
collections="landsat-c2l2-sr",
intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
sortby="-properties.datetime",
max_items=100,
)
```
See [the documentation](https://stac-utils.github.io/stacrs) for details.
In particular, our [example notebook](https://stac-utils.github.io/stacrs/latest/example/) demonstrates some of the more interesting features.
## CLI
**stacrs** comes with a CLI:
```shell
$ stacrs -h
stacrs: A command-line interface for the SpatioTemporal Asset Catalog (STAC)
Usage: stacrs [OPTIONS] <COMMAND>
Commands:
translate Translates STAC from one format to another
search Searches a STAC API or stac-geoparquet file
serve Serves a STAC API
validate Validates a STAC value
help Print this message or the help of the given subcommand(s)
Options:
-i, --input-format <INPUT_FORMAT>
The input format.
--opt <OPTIONS>
Options for getting and putting files from object storage.
-o, --output-format <OUTPUT_FORMAT>
The output format.
-c, --compact-json <COMPACT_JSON>
Whether to print compact JSON output [possible values: true, false]
--parquet-compression <PARQUET_COMPRESSION>
The parquet compression to use when writing stac-geoparquet.
-h, --help
Print help (see more with '--help')
```
> [!NOTE]
> Before **stacrs** v0.5.4, the CLI was its own PyPI package named **stacrs-cli**, which is no longer needed.
## stac-geoparquet
**stacrs** replicates much of the behavior in the [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet) library, and even uses some of the same Rust dependencies.
We believe there are a couple of issues with **stac-geoparquet** that make **stacrs** a worthy replacement:
- The **stac-geoparquet** repo includes Python dependencies
- It doesn't have a nice one-shot API for reading and writing
- It includes some leftover code and logic from its genesis as a tool for the [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/)
We test to ensure [compatibility](https://github.com/stac-utils/stac-rs/blob/main/scripts/validate-stac-geoparquet) between the two libraries, and we intend to consolidate to a single "stac-geoparquet" library at some point in the future.
## Development
Get [Rust](https://rustup.rs/), [uv](https://docs.astral.sh/uv/getting-started/installation/), and [libduckdb](https://duckdb.org/docs/installation/index) (for more on setting up **libduckdb**, [see this](#duckdb)).
Then:
```shell
git clone git@github.com:stac-utils/stacrs.git
cd stacrs
scripts/test
```
See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information about contributing to this project.
> [!TIP]
> We ship our wheels with **libduckdb** so users don't have to worry about having it installed.
> You only need it if you're doing development.
### DuckDB
By default, this package expects **libduckdb** to be present on your system.
If you get this sort of error when building:
```shell
= note: ld: library 'duckdb' not found
```
Set your `DUCKDB_LIB_DIR` to point to your **libduckdb**.
If you're using [homebrew](https://brew.sh/), that might look like this:
```shell
export DUCKDB_LIB_DIR=/opt/homebrew/lib
```
> [!NOTE]
> We used to use the [bundled](https://github.com/duckdb/duckdb-rs?tab=readme-ov-file#notes-on-building-duckdb-and-libduckdb-sys) feature of DuckDB, but it was making our build times intolerably slow.
## License
**stacrs** is dual-licensed under both the MIT license and the Apache license (Version 2.0).
See [LICENSE-APACHE](./LICENSE-APACHE) and [LICENSE-MIT](./LICENSE-MIT) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "stacrs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "stac, geospatial",
"author": null,
"author_email": "Pete Gadomski <pete.gadomski@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/38/e1/5853c3f90d0364a055fcde1b70ca666e33e47c02f87dcd3e96e46a882d30/stacrs-0.5.6.tar.gz",
"platform": null,
"description": "# stacrs\n\n[](https://github.com/stac-utils/stacrs/actions/workflows/ci.yaml)\n[](https://stac-utils.github.io/stacrs/latest/)\n[](https://pypi.org/project/stacrs)\n[](https://anaconda.org/conda-forge/stacrs)\n\n[](./CODE_OF_CONDUCT)\n\nA Python package for [STAC](https://stacspec.org/) using Rust under the hood.\n\n## Why?\n\nQ: We already have [PySTAC](https://github.com/stac-utils/pystac), so why **stacrs**?\n\nA: **stacrs** can\n\n- Read, write, and search [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet)\n- Go to and from [arrow](https://arrow.apache.org/) tables, allowing easy interoperability with (e.g.) [GeoPandas](https://geopandas.org/en/stable/)\n- `async`\n\nIf you don't need those things, **stacrs** probably isn't for you \u2014 use **pystac** and its friend, [pystac-client](https://github.com/stac-utils/pystac-client).\n\n## Usage\n\nInstall via **pip**:\n\n```shell\n# basic\npython -m pip install stacrs\n\n# support arrow tables\npython -m pip install 'stacrs[arrow]'\n```\n\nOr via **conda**:\n\n```shell\nconda install conda-forge::stacrs\n```\n\nThen:\n\n```python\nimport stacrs\n\n# Search a STAC API\nitems = await stacrs.search(\n \"https://landsatlook.usgs.gov/stac-server\",\n collections=\"landsat-c2l2-sr\",\n intersects={\"type\": \"Point\", \"coordinates\": [-105.119, 40.173]},\n sortby=\"-properties.datetime\",\n max_items=100,\n)\n\n# If you installed with `pystac[arrow]`:\nfrom geopandas import GeoDataFrame\ntable = await stacrs.search_to_arrow(...)\ndata_frame = GeoDataFrame.from_arrow(table)\nitems = stacrs.from_arrow(data_frame.to_arrow())\n\n# Write items to a stac-geoparquet file\nawait stacrs.write(\"items.parquet\", items)\n\n# Read items from a stac-geoparquet file as an item collection\nitem_collection = await stacrs.read(\"items.parquet\")\n\n# You can search geoparquet files using DuckDB\n# If you want to search a file on s3, make sure to configure your AWS environment first\nitem_collection = await stacrs.search(\"s3://bucket/items.parquet\", ...)\n\n# Use `search_to` for better performance if you know you'll be writing the items\n# to a file\nawait stacrs.search_to(\n \"items.parquet\",\n \"https://landsatlook.usgs.gov/stac-server\",\n collections=\"landsat-c2l2-sr\",\n intersects={\"type\": \"Point\", \"coordinates\": [-105.119, 40.173]},\n sortby=\"-properties.datetime\",\n max_items=100,\n)\n```\n\nSee [the documentation](https://stac-utils.github.io/stacrs) for details.\nIn particular, our [example notebook](https://stac-utils.github.io/stacrs/latest/example/) demonstrates some of the more interesting features.\n\n## CLI\n\n**stacrs** comes with a CLI:\n\n```shell\n$ stacrs -h\nstacrs: A command-line interface for the SpatioTemporal Asset Catalog (STAC)\n\nUsage: stacrs [OPTIONS] <COMMAND>\n\nCommands:\n translate Translates STAC from one format to another\n search Searches a STAC API or stac-geoparquet file\n serve Serves a STAC API\n validate Validates a STAC value\n help Print this message or the help of the given subcommand(s)\n\nOptions:\n -i, --input-format <INPUT_FORMAT>\n The input format.\n --opt <OPTIONS>\n Options for getting and putting files from object storage.\n -o, --output-format <OUTPUT_FORMAT>\n The output format.\n -c, --compact-json <COMPACT_JSON>\n Whether to print compact JSON output [possible values: true, false]\n --parquet-compression <PARQUET_COMPRESSION>\n The parquet compression to use when writing stac-geoparquet.\n -h, --help\n Print help (see more with '--help')\n```\n\n> [!NOTE]\n> Before **stacrs** v0.5.4, the CLI was its own PyPI package named **stacrs-cli**, which is no longer needed.\n\n## stac-geoparquet\n\n**stacrs** replicates much of the behavior in the [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet) library, and even uses some of the same Rust dependencies.\nWe believe there are a couple of issues with **stac-geoparquet** that make **stacrs** a worthy replacement:\n\n- The **stac-geoparquet** repo includes Python dependencies\n- It doesn't have a nice one-shot API for reading and writing\n- It includes some leftover code and logic from its genesis as a tool for the [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/)\n\nWe test to ensure [compatibility](https://github.com/stac-utils/stac-rs/blob/main/scripts/validate-stac-geoparquet) between the two libraries, and we intend to consolidate to a single \"stac-geoparquet\" library at some point in the future.\n\n## Development\n\nGet [Rust](https://rustup.rs/), [uv](https://docs.astral.sh/uv/getting-started/installation/), and [libduckdb](https://duckdb.org/docs/installation/index) (for more on setting up **libduckdb**, [see this](#duckdb)).\nThen:\n\n```shell\ngit clone git@github.com:stac-utils/stacrs.git\ncd stacrs\nscripts/test\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for more information about contributing to this project.\n\n> [!TIP]\n> We ship our wheels with **libduckdb** so users don't have to worry about having it installed.\n> You only need it if you're doing development.\n\n### DuckDB\n\nBy default, this package expects **libduckdb** to be present on your system.\nIf you get this sort of error when building:\n\n```shell\n = note: ld: library 'duckdb' not found\n```\n\nSet your `DUCKDB_LIB_DIR` to point to your **libduckdb**.\nIf you're using [homebrew](https://brew.sh/), that might look like this:\n\n```shell\nexport DUCKDB_LIB_DIR=/opt/homebrew/lib\n```\n\n> [!NOTE]\n> We used to use the [bundled](https://github.com/duckdb/duckdb-rs?tab=readme-ov-file#notes-on-building-duckdb-and-libduckdb-sys) feature of DuckDB, but it was making our build times intolerably slow.\n\n## License\n\n**stacrs** is dual-licensed under both the MIT license and the Apache license (Version 2.0).\nSee [LICENSE-APACHE](./LICENSE-APACHE) and [LICENSE-MIT](./LICENSE-MIT) for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A no-dependency Python package for STAC, using Rust under the hood.",
"version": "0.5.6",
"project_urls": {
"Documentation": "https://stac-utils.github.io/stacrs",
"Issues": "https://github.com/stac-utils/issues",
"Repository": "https://github.com/stac-utils/stacrs"
},
"split_keywords": [
"stac",
" geospatial"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2403f40e223b5cd1cb604c1124b74076e04718c0a75ab3361597388b99f252be",
"md5": "69a59e4e8a1a0016cb4e10ded828443f",
"sha256": "d54ea3c105cbfc52e9ea2bb35f90ae224d36fe790a68b2dd84dbcd67bcb6e316"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp310-cp310-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "69a59e4e8a1a0016cb4e10ded828443f",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 42628862,
"upload_time": "2025-02-26T14:44:09",
"upload_time_iso_8601": "2025-02-26T14:44:09.374215Z",
"url": "https://files.pythonhosted.org/packages/24/03/f40e223b5cd1cb604c1124b74076e04718c0a75ab3361597388b99f252be/stacrs-0.5.6-cp310-cp310-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70786f1bbea96a6732ec9579c044d131106ad27644f6e9d24e8583967d6def8f",
"md5": "df7f4febb4c95670d92918e64c6a12f8",
"sha256": "ef1ab54206efababbf209374a1be8b0a6cd41b17f021328ed07f38434ae4f8ca"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp310-cp310-macosx_11_0_x86_64.whl",
"has_sig": false,
"md5_digest": "df7f4febb4c95670d92918e64c6a12f8",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 43428160,
"upload_time": "2025-02-26T14:44:23",
"upload_time_iso_8601": "2025-02-26T14:44:23.795567Z",
"url": "https://files.pythonhosted.org/packages/70/78/6f1bbea96a6732ec9579c044d131106ad27644f6e9d24e8583967d6def8f/stacrs-0.5.6-cp310-cp310-macosx_11_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2aefef7bab3019c4d64ebd0d1ecf66e670e7a9a73b6db8af525f7d36ece19d0c",
"md5": "a94dfb4e2d24932620642f1374f9a1b2",
"sha256": "1dce3926aaa5b72dccf257f3e5f7eedc2d015a0ff7bcca0dea6be148076d9ad6"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "a94dfb4e2d24932620642f1374f9a1b2",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 32686444,
"upload_time": "2025-02-26T14:43:58",
"upload_time_iso_8601": "2025-02-26T14:43:58.556997Z",
"url": "https://files.pythonhosted.org/packages/2a/ef/ef7bab3019c4d64ebd0d1ecf66e670e7a9a73b6db8af525f7d36ece19d0c/stacrs-0.5.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e593475f7fbaceb4a0c907974f41ebbcc31447bc0b6115418f1f7ce399acf168",
"md5": "3e4c3323f9f2b334272f9d5857b0505e",
"sha256": "3096b9fc2ad0e2c997a2970d889f946e43ceaf000684de227e393a526bd1c868"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp310-cp310-manylinux_2_28_aarch64.whl",
"has_sig": false,
"md5_digest": "3e4c3323f9f2b334272f9d5857b0505e",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 31135389,
"upload_time": "2025-02-26T14:43:46",
"upload_time_iso_8601": "2025-02-26T14:43:46.815134Z",
"url": "https://files.pythonhosted.org/packages/e5/93/475f7fbaceb4a0c907974f41ebbcc31447bc0b6115418f1f7ce399acf168/stacrs-0.5.6-cp310-cp310-manylinux_2_28_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2f034facd07c9d3a1f2312a20843bb278208971165a1480ef48b3e0fe1d11fbf",
"md5": "c45e8878db3a182f0d045bde7ae4e500",
"sha256": "1a6958ccca957ea8b3ca20de0dd08cdd32f2d4a16c3164f1fb48e65020527195"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp311-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "c45e8878db3a182f0d045bde7ae4e500",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 42629983,
"upload_time": "2025-02-26T14:44:16",
"upload_time_iso_8601": "2025-02-26T14:44:16.283741Z",
"url": "https://files.pythonhosted.org/packages/2f/03/4facd07c9d3a1f2312a20843bb278208971165a1480ef48b3e0fe1d11fbf/stacrs-0.5.6-cp311-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d2a062e05b995de05e165cf283f10c32b7db4a402470e914fe8eb59323759cac",
"md5": "f4907e2db73d3e360127cd85998556d0",
"sha256": "b25307f8a605aeb0f09b27ba73e25231c400dfad8e6b339b028f8569cce3174f"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp311-abi3-macosx_11_0_x86_64.whl",
"has_sig": false,
"md5_digest": "f4907e2db73d3e360127cd85998556d0",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 43442144,
"upload_time": "2025-02-26T14:44:30",
"upload_time_iso_8601": "2025-02-26T14:44:30.942513Z",
"url": "https://files.pythonhosted.org/packages/d2/a0/62e05b995de05e165cf283f10c32b7db4a402470e914fe8eb59323759cac/stacrs-0.5.6-cp311-abi3-macosx_11_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "169adfb38c0df69fb38d4c58cf252fa1eb2427931b94dd2f9a43020384e85c65",
"md5": "a86b82748b26de8e6e420c1af41c6f3c",
"sha256": "6f56f7a5a18bffaa7f934ad066d7742be15a29f7eb64006426f0686e6c5d6a30"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "a86b82748b26de8e6e420c1af41c6f3c",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 32682848,
"upload_time": "2025-02-26T14:44:03",
"upload_time_iso_8601": "2025-02-26T14:44:03.847257Z",
"url": "https://files.pythonhosted.org/packages/16/9a/dfb38c0df69fb38d4c58cf252fa1eb2427931b94dd2f9a43020384e85c65/stacrs-0.5.6-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3378b85840e05184ab349d02a56651a32afcd9ee70616c77756b8cc24603d5c1",
"md5": "7afe65279a8c910cbbc02973caacc5e0",
"sha256": "0cbc2c1ca80136fcc0082631b6a203c8b8434cafbea81e7af7b524c595d6dcf6"
},
"downloads": -1,
"filename": "stacrs-0.5.6-cp311-abi3-manylinux_2_28_aarch64.whl",
"has_sig": false,
"md5_digest": "7afe65279a8c910cbbc02973caacc5e0",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 31133078,
"upload_time": "2025-02-26T14:43:52",
"upload_time_iso_8601": "2025-02-26T14:43:52.629082Z",
"url": "https://files.pythonhosted.org/packages/33/78/b85840e05184ab349d02a56651a32afcd9ee70616c77756b8cc24603d5c1/stacrs-0.5.6-cp311-abi3-manylinux_2_28_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "38e15853c3f90d0364a055fcde1b70ca666e33e47c02f87dcd3e96e46a882d30",
"md5": "dcd27917055b76a074e5498913720f06",
"sha256": "f154340e3f754d30b29fad06f3ce2fa6112c7b2535592cc5ed7334bd6f12c155"
},
"downloads": -1,
"filename": "stacrs-0.5.6.tar.gz",
"has_sig": false,
"md5_digest": "dcd27917055b76a074e5498913720f06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 941594,
"upload_time": "2025-02-26T14:44:35",
"upload_time_iso_8601": "2025-02-26T14:44:35.238366Z",
"url": "https://files.pythonhosted.org/packages/38/e1/5853c3f90d0364a055fcde1b70ca666e33e47c02f87dcd3e96e46a882d30/stacrs-0.5.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-26 14:44:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stac-utils",
"github_project": "issues",
"github_not_found": true,
"lcname": "stacrs"
}
