Metadata-Version: 2.4
Name: geoarrow-c
Version: 0.4.0
Summary: Python bindings to the geoarrow C and C++ implementation
Author-email: Dewey Dunnington <dewey@dunnington.ca>
License-Expression: Apache-2.0
Project-URL: homepage, https://geoarrow.org
Project-URL: repository, https://github.com/geoarrow/geoarrow-c
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: geoarrow-types; extra == "test"
Requires-Dist: pyarrow; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: numpy; extra == "test"
Dynamic: license-file


# geoarrow-c for Python

The geoarrow-c Python package provides bindings to the geoarrow-c implementation of the [GeoArrow specification](https://github.com/geoarrow/geoarrow). Its primary purpose is to serve as a dependency to [geoarrow-python](https://github.com/geoarrow/geoarrow-python) where needed.

## Installation

Python bindings for geoarrow are available on PyPI and can be installed with:

```bash
pip install geoarrow-c
```

You can install a development version with:

```bash
python -m pip install "git+https://github.com/geoarrow/geoarrow-c.git#egg=geoarrow-c&subdirectory=python/geoarrow-c"
```

If you can import the namespace, you're good to go!

```python
import geoarrow.c
```

## Example

Most users should use the higher-level
[geoarrow-python](https://github.com/geoarrow/geoarrow-python) bindings.
The Python package also provides thin Arrow PyCapsule protocol wrappers around
the compute kernels exposed by `geoarrow-c`:

```python
import geoarrow.pyarrow as ga
from geoarrow.c import AggregateFunction, ScalarFunction

input_pyarrow = ga.array(["POINT (0 1)"])
format_wkt = ScalarFunction("format_wkt", precision=3)
formatted = format_wkt(input_pyarrow)

box_agg = AggregateFunction("box_agg")
result = box_agg(input_pyarrow)
```

Each call infers the input type from the array or stream and creates a fresh
kernel. Scalar functions preserve stream batch boundaries; aggregate functions
combine all batches into a single result array. Results implement the Arrow
PyCapsule protocol and can be imported into an Arrow implementation.

## Type specification integration

The `arrow_to_type_spec()` and `type_spec_to_arrow()` functions bridge
`geoarrow.types.TypeSpec` objects and the Arrow C Data Interface. This
integration requires the `geoarrow-types` package but does not require a
particular Arrow implementation.

`type_spec_to_arrow()` returns a `SchemaHolder` implementing
`__arrow_c_schema__`:

```python
import geoarrow.types as gt
from geoarrow.c import type_spec_to_arrow

type_spec = gt.linestring(
    dimensions=gt.Dimensions.XYZ,
    coord_type=gt.CoordType.INTERLEAVED,
    crs="EPSG:4326",
)
schema = type_spec_to_arrow(type_spec)
schema_capsule = schema.__arrow_c_schema__()
```

`arrow_to_type_spec()` accepts a `SchemaHolder` or any other
`__arrow_c_schema__` provider and reconstructs the corresponding `TypeSpec`:

```python
from geoarrow.c import arrow_to_type_spec

roundtripped = arrow_to_type_spec(schema)
assert roundtripped == type_spec.with_defaults().canonicalize()
```

## Building

Python bindings for nanoarrow are managed with [setuptools](https://setuptools.pypa.io/en/latest/index.html).
This means you can build the project using:

```shell
git clone https://github.com/geoarrow/geoarrow-c.git
cd python
pip install -e geoarrow-c/
```

Tests use [pytest](https://docs.pytest.org/):

```shell
# Install dependencies
cd python/geoarrow-c
pip install -e ".[test]"

# Run tests
pytest
```
