README.md

rustac

A Python package for STAC using Rust under the hood.

Tip

While you can pronounce "rustac" however you'd like, we like "ruh-stac".

Why?

Q: We already have PySTAC, so why rustac?

A: rustac can

• Read, write, and search stac-geoparquet
• Go to and from arrow tables, allowing easy interoperability with (e.g.) GeoPandas
• async

If you don't need those things, rustac probably isn't for you — use pystac and its friend, pystac-client.

Installation

Install via pip:

# basic
python -m pip install rustac

# support arrow tables
python -m pip install 'rustac[arrow]'

Or via conda:

conda install conda-forge::rustac

From source

By default, rustac wants to find DuckDB on your system:

brew install duckdb  # if you're using Homebrew ... if not, get DuckDB another way
python -m pip install -U git+https://github.com/stac-utils/rustac-py

If you don't want to (or can't) install DuckDB, can build DuckDB as a "bundled" build (warning: it takes a while):

MATURIN_PEP517_ARGS="--features=duckdb-bundled" python -m pip install -U git+https://github.com/stac-utils/rustac-py

Usage

import asyncio
import rustac

async def main() -> None:
    # Search a STAC API
    items = await rustac.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 = rustac.to_arrow(items)
    data_frame = GeoDataFrame.from_arrow(table)
    items = rustac.from_arrow(data_frame.to_arrow())

    # Write items to a stac-geoparquet file
    await rustac.write("/tmp/items.parquet", items)

    # Read items from a stac-geoparquet file as an item collection
    item_collection = await rustac.read("/tmp/items.parquet")

    # Use `search_to` for better performance if you know you'll be writing the items
    # to a file
    await rustac.search_to(
        "/tmp/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,
    )

asyncio.run(main())

See the documentation for details. In particular, our examples demonstrate some of the more interesting features.

Command line interface (CLI)

rustac comes with a CLI:

rustac -h

stac-geoparquet

rustac replicates much of the behavior in the 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 rustac 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

We test to ensure compatibility between the two libraries, and we intend to consolidate to a single "stac-geoparquet" library at some point in the future.

Development

Get Rust, uv, and (optionally) libduckdb. Then:

git clone git@github.com:stac-utils/rustac-py.git
cd rustac-py
scripts/test

See CONTRIBUTING.md for more information about contributing to this project.

DuckDB

By default, this package expects libduckdb to be present on your system. If you get this sort of error when building:

  = note: ld: library 'duckdb' not found

Set your DUCKDB_LIB_DIR to point to your libduckdb. If you're using homebrew, that might look like this:

export DUCKDB_LIB_DIR=/opt/homebrew/lib

Alternatively, you can use the duckdb-bundled feature to build DuckDB bindings into the Rust library:

maturin dev --uv -F duckdb-bundled && pytest

Warning

Building DuckDB bundled takes a long while.

Docs

If you want to run an off-cycle docs update (e.g. if you fixed something and want to post it without having to make a new release):

mike deploy [version] latest --push

License

rustac-py is dual-licensed under both the MIT license and the Apache license (Version 2.0). See LICENSE-APACHE and LICENSE-MIT for details.