feat: search to an arrow table (#54)

Author: gadomski

.github/workflows/ci.yaml

@@ -48,10 +48,12 @@ jobs:
           mkdir -p ${{ github.workspace }}/opt/duckdb
           unzip libduckdb-${{ matrix.os.duckdb-slug }}.zip -d ${{ github.workspace }}/opt/duckdb
       - name: Sync
-        run: uv sync --no-install-project
-      - name: Build directly with maturin
-        run: uv run maturin dev --uv
+        run: uv sync --all-extras
       - name: Lint
         run: scripts/lint
       - name: Test
         run: scripts/test
+      - name: Sync w/o extras
+        run: uv sync
+      - name: Test w/o extras
+        run: uv run pytest

.github/workflows/pypi.yaml

@@ -19,6 +19,11 @@ jobs:
     runs-on: ubuntu-22.04
     strategy:
       matrix:
+        maturin:
+          - args: "-i 3.10"
+            name: python-310
+          - args: "-i 3.11 -F pyo3/abi3-py311"
+            name: python-311+
         platform:
           - target: x86_64
             manylinux: auto
@@ -29,13 +34,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5
-      - name: Install Pythons
+      - name: Install Python
         run: uv python install 3.10
       - name: Build wheels
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist -i 3.10 --auditwheel repair
+          args: --release --out dist ${{ matrix.maturin.args }} --auditwheel repair
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
           manylinux: ${{ matrix.platform.manylinux }}
           before-script-linux: |
@@ -53,13 +58,18 @@ jobs:
       - name: Upload wheels
         uses: actions/upload-artifact@v4
         with:
-          name: wheels-linux-${{ matrix.platform.target }}
+          name: wheels-linux-${{ matrix.platform.target }}-${{ matrix.maturin.name }}
           path: dist
 
   macos:
     runs-on: ${{ matrix.platform.runner }}
     strategy:
       matrix:
+        maturin:
+          - args: "-i 3.10"
+            name: python-310
+          - args: "-i 3.11 -F pyo3/abi3-py311"
+            name: python-311+
         platform:
           - runner: macos-13
             target: x86_64
@@ -87,7 +97,7 @@ jobs:
           DUCKDB_LIB_DIR: ${{ github.workspace }}/opt/duckdb
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist -i 3.10
+          args: --release --out dist ${{ matrix.maturin.args }}
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
       - name: Repair wheel
         run: .venv/bin/delocate-wheel -v dist/*.whl
@@ -96,7 +106,7 @@ jobs:
       - name: Upload wheels
         uses: actions/upload-artifact@v4
         with:
-          name: wheels-macos-${{ matrix.platform.target }}
+          name: wheels-macos-${{ matrix.platform.target }}-${{ matrix.maturin.name }}
           path: dist
 
   sdist:

Cargo.lock

@@ -11,11 +11,12 @@ crate-type = ["cdylib"]
 [dependencies]
 clap = "4.5.30"
 geojson = "0.24.1"
-pyo3 = { version = "0.23.4", features = ["abi3-py310", "extension-module"] }
+pyo3 = { version = "0.23.4", features = ["extension-module"] }
 pyo3-async-runtimes = { version = "0.23.0", features = [
     "tokio",
     "tokio-runtime",
 ] }
+pyo3-arrow = "0.7.2"
 pythonize = "0.23.0"
 serde = "1.0.217"
 serde_json = "1.0.138"
@@ -27,8 +28,9 @@ stac-api = { features = [
     "client",
     "python",
 ], git = "https://github.com/stac-utils/stac-rs" }
-stac-cli = { git = "https://github.com/stac-utils/stac-rs", default-features = false, features = [
+stac-cli = { git = "https://github.com/stac-utils/stac-rs", features = [
     "pgstac",
+    "duckdb",
 ] }
 stac-duckdb = { git = "https://github.com/stac-utils/stac-rs" }
 thiserror = "2.0.11"

Cargo.toml

@@ -11,8 +11,9 @@ A small no-dependency Python package for [STAC](https://stacspec.org/), using Ru
 
 ## Why?
 
-Why make a new STAC Python library, when we already have [PySTAC](https://github.com/stac-utils/pystac)?
-Well, we've built some things in [stac-rs](https://github.com/stac-utils/stac-rs) (a collection of STAC Rust libraries) that we want to provide to the Python ecosystem, such as:
+Q: We already have [PySTAC](https://github.com/stac-utils/pystac), so why did we make a new STAC Python library?
+
+A: We want to provide a couple of things in [stac-rs](https://github.com/stac-utils/stac-rs) (a collection of STAC Rust libraries) to the Python ecosystem:
 
 - Read, write, and search [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet)
 - `async` functions
@@ -24,7 +25,11 @@ If you don't need those things, **stacrs** probably isn't for you — use **pyst
 Install via **pip**:
 
 ```shell
+# basic
 python -m pip install stacrs
+
+# add methods to return arrow tables
+python -m pip install 'stacrs[arrow]'
 ```
 
 Or via **conda**:
@@ -47,6 +52,11 @@ items = await stacrs.search(
     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)
+
 # Write items to a stac-geoparquet file
 await stacrs.write("items.parquet", items)
 

README.md

@@ -21,6 +21,10 @@ classifiers = [
 ]
 keywords = ["stac", "geospatial"]
 dynamic = ["version"]
+dependencies = []
+
+[project.optional-dependencies]
+arrow = ["arro3-core>=0.4.5"]
 
 [project.scripts]
 stacrs = "stacrs:main"
@@ -34,7 +38,7 @@ Issues = "https://github.com/stac-utils/issues"
 files = "**/*.py"
 
 [[tool.mypy.overrides]]
-module = "pyarrow.*"
+module = ["pyarrow.*", "geopandas.*"]
 ignore_missing_imports = true
 
 [tool.pytest.ini_options]
@@ -43,6 +47,7 @@ asyncio_default_fixture_loop_scope = "function"
 
 [dependency-groups]
 dev = [
+    "geopandas>=1.0.1",
     "maturin>=1.7.4",
     "mypy>=1.11.2",
     "pyarrow>=19.0.1",