Installing the Honua Python SDK

September 3, 2026 · View on GitHub

Packages

Package	Description
`honua-sdk`	Data-plane client for Honua Server -- REST queries, geocoding, gRPC features
`honua-admin`	Control-plane / admin client for Honua Server (depends on `honua-sdk`)

Prerequisites

Python 3.11 or later
A running Honua Server instance

Install

The canonical install path is PyPI:

# Core data client (REST/HTTP, sync + async)
pip install honua-sdk

# With extras: gRPC, GeoPandas vector interop, raster interop
pip install "honua-sdk[grpc,geopandas,raster]"

# Admin / control-plane client (installs honua-sdk alongside it)
pip install honua-admin

For unreleased development work, install from a clone instead:

git clone https://github.com/honua-io/honua-sdk-python.git
cd honua-sdk-python

# Core data client (REST/HTTP, sync + async)
pip install ./packages/honua-sdk

# With gRPC support
pip install "./packages/honua-sdk[grpc]"

# With GeoPandas integration (vector result interop)
pip install "./packages/honua-sdk[geopandas]"

# With raster result interop (rasterio / rioxarray / xarray)
pip install "./packages/honua-sdk[raster]"

# Admin / control-plane client (installs honua-sdk alongside it)
pip install ./packages/honua-sdk ./packages/honua-admin

# Everything
pip install "./packages/honua-sdk[grpc,geopandas,raster]" ./packages/honua-admin

Or straight from GitHub without cloning, pinned to a release tag (replace with the newest python-sdk-v* tag):

pip install "honua-sdk[geopandas] @ git+https://github.com/honua-io/honua-sdk-python.git@python-sdk-v0.1.11#subdirectory=packages/honua-sdk"

The repo-root pyproject.toml is intentionally not installable (it holds shared tool config only) -- install the per-package directories, not ..

Quick Start

from honua_sdk import HonuaClient, Query, SourceDescriptor, SourceLocator

with HonuaClient(base_url="https://your-honua-server.com") as client:
    # Query features through the shared Source/Query/Result API
    source = client.source(
        SourceDescriptor(
            id="parcels",
            protocol="geoservices-feature-service",
            locator=SourceLocator(service_id="parcels", layer_id=0),
        )
    )
    result = source.query(
        Query(where="status = 'active'", out_fields=["*"])
    )

    print(f"Found {len(result.features)} features")

The context-manager form (with HonuaClient(...) as client:) is the recommended default -- it guarantees underlying httpx connections are returned to the pool when the block exits, even if a request raises.

With gRPC

import grpc

from honua_sdk.grpc import HonuaGrpcClient, QueryFeaturesRequest

request = QueryFeaturesRequest(service_id="parcels", layer_id=0)

# Production: TLS via channel credentials
with HonuaGrpcClient(
    "grpc.your-honua-server.com:443",
    credentials=grpc.ssl_channel_credentials(),
) as client:
    # Stream features
    for page in client.query_features_stream(request):
        print(page)

# Local dev: plaintext channel (must opt in explicitly)
with HonuaGrpcClient("localhost:50051", insecure=True) as client:
    for page in client.query_features_stream(request):
        print(page)

The constructor takes target positionally; pass exactly one of credentials=, channel=, or insecure=True. The same shape is used in docs/quickstart.md.

Admin

from honua_admin import HonuaAdminClient

with HonuaAdminClient("https://your-honua-server.com", api_key="honua-api-key") as admin:
    compatibility = admin.check_compatibility()
    if not compatibility.supported:
        raise RuntimeError("; ".join(compatibility.reasons))

    features = admin.get_capability_flags()
    if features.metadata_resources:
        print("Metadata resources are supported on this server.")

Version Policy

Pre-release (0.x.xaN, 0.x.xbN): Published to PyPI with alpha/beta classifiers
Stable (1.0.0+): Published to PyPI as a stable release

All packages follow Semantic Versioning. Major versions are coordinated across all Honua SDKs.

Admin Compatibility Checks

The admin SDK uses GET /api/v1/admin/capabilities as the runtime compatibility source of truth. It currently expects:

server version >= 1.0.0 for GA SemVer identities, or >= 2026.3.0 for pre-GA CalVer identities
control-plane API major v1
release channel preview or newer

The coarse feature flags exposed today are:

metadata_resources
manifest_export
manifest_apply
manifest_dry_run
manifest_prune

Canonical vs legacy API

New code should prefer the canonical Source / Query / Result surface:

from honua_sdk import HonuaClient, Query, SourceDescriptor, SourceLocator

with HonuaClient(base_url="https://your-honua-server.com") as client:
    source = client.source(
        SourceDescriptor(
            id="parcels",
            protocol="geoservices-feature-service",
            locator=SourceLocator(service_id="parcels", layer_id=0),
        )
    )
    result = source.query(Query(where="status = 'active'", out_fields=["*"]))
    for feature in result.features:
        # Typed ``QueryFeature`` -- attributes live under ``.properties``.
        print(feature.id, feature.properties)

client.query_features(service_id, layer_id, where=...) and the rest of the raw-dict FeatureServer helpers remain available as the legacy / compact form. They return raw JSON dicts (FeatureServer attributes-shaped payloads) and are useful for one-liners, scripting, and protocol-debugging. New library code should reach for the canonical form so it gets:

typed Result[QueryFeature] with .properties / .geometry / .protocol
protocol-aware filter routing (CQL2-text vs SQL WHERE) -- including the where_as_cql=True opt-in for callers who want a SQL-style string forwarded as CQL on OGC Features or STAC
consistent pagination signals across FeatureServer, OGC Features, STAC, and OData

Troubleshooting

See docs/troubleshooting.md for the full guide. The most common install-time failures:

gRPC wheel build fails on macOS Apple Silicon -- upgrade pip (python -m pip install --upgrade pip) so it picks the prebuilt grpcio arm64 wheel instead of falling back to source.
GeoPandas / Shapely fails on Windows -- install the honua-sdk[geopandas] extra inside a conda env (or under WSL); the pip path on Windows requires a working GEOS / GDAL toolchain.
Python 3.10 install fails with a version-pin error -- the SDK requires Python 3.11+. Upgrade your interpreter or pin a 3.11+ venv.
"Microsoft Visual C++ 14.0 is required" / "command 'gcc' failed" -- a transitive dep is building from source because no wheel matched your platform. Install your platform's C compiler (Build Tools for Visual Studio on Windows, xcode-select --install on macOS, build-essential on Debian/Ubuntu) and re-run pip.