honua-sdk › Models¶

These dataclasses make up the canonical request/response shape. Query is the input type — it captures filter, projection, and pagination intent in a protocol-agnostic way. Result[QueryFeature] is the canonical output: each feature exposes GeoJSON-shaped .geometry and .properties plus the resolved protocol and source tags.

FeatureQuery and FeatureQueryResult are the legacy GeoServices-flavoured shape, where each feature has .attributes (raw GeoServices field bag) rather than .properties — they remain on the public API for the existing HonuaClient.query / iter_query dispatcher and to keep typed access to FeatureServer responses. New code should prefer Query / Result[QueryFeature] via the Source facade.

from honua_sdk import Query

q = Query(where="status = 'active'", out_fields=["id", "name"], limit=100)
for feature in client.source(descriptor).iter_query(q):
    print(feature.id, feature.properties)

See also: Source facade for the entry point that consumes these models, Errors for the exception hierarchy raised on failure, and Pagination for how Result.exceeded_transfer_limit / Result.total_count map to FeatureServer, OGC Features, STAC, and OData signals and how Query.page_size / Query.max_pages drive the pagination loop.

Geometry, schema, and GeoDataFrame ergonomics¶

For ArcGIS-style geoprocessing authoring, the typed feature models carry a first-class geometry bridge and the source facade exposes typed layer schema and arcpy.da-style cursors:

Feature / QueryFeature expose .to_shapely(), a cached .geometry_shape, and the __geo_interface__ protocol — Shapely geometry directly off the typed feature (the arcpy feature.SHAPE analogue), for both Esri-JSON and GeoJSON sources. Shapely stays an optional dependency.
LayerSchema (with typed Field / Extent) is the arcpy.Describe / ListFields analogue — Source.schema() / feature_server.schema() parse FeatureServer layer metadata into typed fields, normalized geometry type, resolved SRID, and a typed extent.
Result.to_geodataframe() / Source.to_geodataframe(...) are the Spatially-Enabled-DataFrame equivalent: one call from a query result to a GeoPandas GeoDataFrame (requires the geopandas extra).
Source.search_cursor / update_cursor / insert_cursor (see the Source facade) provide the arcpy.da cursor idioms over streaming query + batched apply_edits.

`honua_sdk.Query` `dataclass` ¶

Cross-SDK query model with Pythonic field names.

Filter routing¶

Pick exactly one of three forms, matched to the target protocol:

where — SQL-style WHERE clause for SQL protocols (GeoServices FeatureServer, OData). On CQL-based protocols (OGC Features, STAC) this raises :class:ValueError at routing time, because silently forwarding SQL syntax to a CQL endpoint is a footgun that masks bugs.
cql_filter — CQL2-text filter for CQL protocols (OGC Features, STAC). On SQL-style protocols this raises :class:ValueError — CQL2-text is not valid for FeatureServer / OData.
where_as_cql=True — escape hatch for protocol-agnostic callers that have already verified the where string is valid CQL2-text. With the flag set, where is forwarded to the CQL filter field on OGC/STAC without raising. The flag is a no-op on SQL-style protocols (where still routes to SQL where).

When both where and cql_filter are set on a CQL-based protocol, cql_filter wins.

Attributes:

Name	Type	Description
`where`	`str \| None`	SQL-style filter for FeatureServer/OData endpoints.
`cql_filter`	`str \| None`	CQL2-text filter for OGC Features / STAC.
`where_as_cql`	`bool`	When True, forwards `where` to CQL endpoints without raising.
`spatial_filter`	`Mapping[str, Any] \| None`	Free-form spatial-filter mapping (geometry, relation, SR).
`bbox`	`str \| Sequence[int \| float] \| None`	`(minx, miny, maxx, maxy)` spatial filter; comma-string also accepted.
`out_fields`	`str \| Sequence[str] \| None`	Field selector; `[""]` or `""` selects all.
`order_by`	`str \| Sequence[str] \| None`	Sort specification forwarded to the protocol.
`pagination`	`Pagination`	:class:`Pagination` options (`limit`, `page_size`, ...).
`aggregation`	`Mapping[str, Any] \| None`	Protocol-neutral aggregation request mapping.
`return_geometry`	`bool`	Whether to include geometry in the response.
`out_sr`	`int \| str \| None`	Output spatial reference (EPSG code or WKID).
`extra_params`	`Mapping[str, Any]`	Free-form per-protocol query parameter overrides.

`honua_sdk.Result` `dataclass` ¶

Bases: Generic[T]

Collected result returned by the canonical Source/Query API.

Generic over the feature element type T (defaults to :class:QueryFeature at call sites). raw_legacy exposes the underlying :class:FeatureQueryResult (the protocol-neutral query result the canonical facade is built on) for callers that need the unprocessed protocol response — e.g. inspecting pages_seen or the original query envelope. raw remains a free-form mapping reserved for protocol-specific extension fields.

Attributes:

Name	Type	Description
`features`	`tuple[T, ...]`	Tuple of result features (type parameter `T`).
`exceeded_transfer_limit`	`bool`	True when the server signalled more pages remain.
`total_count`	`int \| None`	Server-reported total count when available.
`aggregate_rows`	`tuple[Mapping[str, Any], ...]`	Aggregate result rows when an aggregation was requested.
`extent`	`Mapping[str, Any] \| None`	Result extent mapping (`xmin`/`ymin`/`xmax`/`ymax`).
`fields`	`tuple[Mapping[str, Any], ...]`	Field schema entries returned by the protocol.
`degraded`	`tuple[DegradedReason, ...]`	Reasons this result fell back to a lower-fidelity path.
`protocol`	`str`	Canonical protocol literal the result was served from.
`source_id`	`str`	Identifier of the source that produced the result.
`query`	`Query \| None`	The :class:`Query` instance that produced this result.
`raw`	`Mapping[str, Any]`	Free-form mapping for protocol-specific extension fields.
`raw_legacy`	`'FeatureQueryResult \| None'`	Underlying :class:`FeatureQueryResult` envelope, when available.

`to_geodataframe()` ¶

Convert this result's features to a GeoPandas GeoDataFrame.

The first-class, one-call equivalent of the Esri Spatially-Enabled DataFrame: feature attributes become columns and each feature's geometry (via its __geo_interface__ bridge) becomes the geometry column. The CRS is resolved from the result's query.out_sr / extent spatial reference, defaulting to EPSG:4326 for GeoJSON sources.

Requires the optional geopandas extra (pip install honua-sdk[geopandas]); raises :class:ImportError with an install hint when it is absent.

`honua_sdk.QueryFeature` `dataclass` ¶

Protocol-neutral feature returned by the shared query API.

Returned by :meth:Source.query, :meth:Source.stream, and the underlying :meth:HonuaClient.query / :meth:AsyncHonuaClient.query facade across every protocol (FeatureServer, OGC Features, STAC, OData). Uses GeoJSON-shaped properties + geometry. For the raw GeoServices attributes/geometry shape, see :class:Feature.

Attributes:

Name	Type	Description
`id`	`str \| int \| None`	Stable feature identifier from the underlying protocol.
`properties`	`Mapping[str, Any]`	GeoJSON-shaped attribute mapping.
`geometry`	`Mapping[str, Any] \| None`	Optional GeoJSON-shaped geometry mapping.
`protocol`	`str`	Canonical protocol literal the feature was served from.
`source`	`str`	Identifier of the source that produced the feature.
`raw`	`Mapping[str, Any]`	Free-form mapping preserving the underlying protocol payload.

`__geo_interface__` `property` ¶

GeoJSON-mapping view of this feature's geometry (None if absent).

Implements the de-facto __geo_interface__ protocol so the feature plugs directly into Shapely and the wider Python geospatial ecosystem. Handles both Esri-JSON (FeatureServer) and GeoJSON (OGC/STAC) sources.

`geometry_shape` `property` ¶

Cached Shapely geometry for this feature (see :meth:to_shapely).

`to_shapely()` ¶

Return this feature's geometry as a Shapely geometry.

The typed analogue of arcpy feature.SHAPE / the ArcGIS-API geometry object. Returns None when the feature carries no geometry. Raises :class:ImportError with an install hint when the optional shapely dependency is absent.

`honua_sdk.Feature` `dataclass` ¶

FeatureServer feature with attributes and optional geometry.

Returned by GeoServices FeatureServer endpoints (FeatureServerClient and its async sibling) via :meth:FeatureSet.features. Uses the GeoServices attributes/geometry shape verbatim. For the protocol-neutral feature shape used by :meth:Source.query, see :class:QueryFeature instead.

`__geo_interface__` `property` ¶

GeoJSON-mapping view of this feature's geometry (None if absent).

Implements the de-facto __geo_interface__ protocol so the feature plugs directly into Shapely (shapely.geometry.shape(feature)) and the wider Python geospatial ecosystem. Handles both the Esri-JSON (FeatureServer) and GeoJSON (OGC/STAC) geometry encodings.

`geometry_shape` `property` ¶

Cached Shapely geometry for this feature (see :meth:to_shapely).

`to_shapely()` ¶

Return this feature's geometry as a Shapely geometry.

The typed analogue of arcpy feature.SHAPE / the ArcGIS-API geometry object: a GP tool gets Shapely geometry directly from the feature without dropping to result.raw. Returns None when the feature has no geometry. Raises :class:ImportError with an install hint when the optional shapely dependency is absent.

`honua_sdk.LayerSchema` `dataclass` ¶

Typed description of a single layer's fields, geometry, CRS, and extent.

Built from a FeatureServer/MapServer layer_metadata JSON response (or the OGC-style properties/queryables shape) via :meth:from_metadata. The :class:arcpy.Describe analogue for Honua GP authoring: fields, geometry_type, srid, and extent are all typed so a tool never hand-parses the raw JSON.

Attributes:

Name	Type	Description
`layer_id`	`int \| None`	Numeric layer id when the source exposes one.
`name`	`str`	Layer display name.
`geometry_type`	`str \| None`	Normalized geometry type (e.g. `"Polygon"`), or `None` for non-spatial tables.
`fields`	`tuple[Field, ...]`	Typed :class:`Field` entries in server order.
`srid`	`int \| None`	Resolved EPSG/WKID of the layer's spatial reference.
`extent`	`Extent \| None`	Typed :class:`Extent`, when advertised.
`object_id_field`	`str \| None`	Name of the OID field, when advertised.
`spatial_reference`	`Mapping[str, Any] \| None`	Raw spatial-reference mapping, preserved verbatim.
`raw`	`Mapping[str, Any]`	The unparsed metadata mapping the schema was built from.

`field_names` `property` ¶

Field names in server order (the arcpy.ListFields name list).

`field(name)` ¶

Return the field whose name matches name case-insensitively.

`from_metadata(payload)` `classmethod` ¶

Parse a FeatureServer/MapServer (or OGC) layer-metadata mapping.

`honua_sdk.Field` `dataclass` ¶

A single typed attribute field on a layer.

Mirrors the fields surfaced by arcpy.ListFields / the ArcGIS-API layer fields property. type retains the server's native type token (the Esri esriFieldType* family or an OGC/JSON-schema type) verbatim.

`honua_sdk.Extent` `dataclass` ¶

Axis-aligned bounding box for a layer.

Carries the four bounds plus the spatial reference WKID when the source advertised one, so a GP tool can build an output extent without re-parsing.

`bbox` `property` ¶

(minx, miny, maxx, maxy) tuple — the GeoJSON/Shapely bbox order.

`honua_sdk.SourceDescriptor` `dataclass` ¶

Cross-SDK source description used by the source facade.

protocol accepts any string (including alias forms) at construction time; __post_init__ normalizes it through :func:normalize_protocol so the stored value is always a canonical :data:Protocol literal.

Attributes:

Name	Type	Description
`id`	`str`	Stable source identifier used by the canonical facade.
`protocol`	`Protocol \| str`	Canonical protocol literal after normalization.
`locator`	`SourceLocator`	Protocol-specific addressing fields.
`capabilities`	`frozenset[str]`	Frozen set of canonical capability names advertised.
`raw`	`Mapping[str, Any]`	Free-form mapping preserving the source's underlying payload.

`supports(capability)` ¶

Return whether the source descriptor advertises a capability.

`honua_sdk.SourceLocator` `dataclass` ¶

Protocol-specific source address using Pythonic field names.

Attributes:

Name	Type	Description
`service_id`	`str \| None`	GeoServices service identifier (FeatureServer/MapServer/ImageServer).
`layer_id`	`int \| None`	Numeric layer index within a GeoServices service.
`collection_id`	`str \| None`	OGC API / STAC collection identifier.
`entity_set`	`str \| None`	OData entity-set name (e.g. `"Features"`).
`type_name`	`str \| None`	WFS `typeName` value.

`honua_sdk.FeatureQuery` `dataclass` ¶

Protocol-neutral feature query request.

Attributes:

Name	Type	Description
`source`	`str`	Source identifier (service id / collection id / entity set).
`protocol`	`QueryProtocol \| str`	Canonical query protocol literal.
`layer_id`	`int \| None`	FeatureServer / OData layer index when required.
`where`	`str \| None`	SQL-style `WHERE` clause (FeatureServer / OData).
`filter`	`str \| None`	CQL2-text filter (OGC Features / STAC).
`bbox`	`str \| Sequence[int \| float] \| None`	`(minx, miny, maxx, maxy)` envelope spatial filter.
`spatial_filter`	`Mapping[str, Any] \| None`	Free-form spatial-filter mapping (arbitrary geometry + relationship + SR + optional distance) translated to GeoServices `geometry`/`geometryType`/`spatialRel`/`inSR` params on the FeatureServer path. See :mod:`honua_sdk._geoservices_query`.
`fields`	`str \| Sequence[str] \| None`	Attribute selection.
`return_geometry`	`bool`	Whether to include geometry in the response.
`out_statistics`	`Sequence[Mapping[str, Any]] \| None`	Server-side statistic definitions (FeatureServer `outStatistics`).
`group_by`	`str \| Sequence[str] \| None`	Group-by fields for statistics (FeatureServer `groupByFieldsForStatistics`).
`return_distinct_values`	`bool`	Request distinct rows (`returnDistinctValues`).
`return_count_only`	`bool`	Request only the matching count (`returnCountOnly`).
`page_size`	`int \| None`	Per-request page size for paginated protocols.
`limit`	`int \| None`	Maximum features collected across all pages.
`max_pages`	`int \| None`	Cap on the number of pages walked. `None` is unbounded.
`extra_params`	`Mapping[str, Any]`	Free-form per-protocol query parameter overrides.

`honua_sdk.FeatureQueryResult` `dataclass` ¶

Collected result returned by the shared query API.

Pagination signals (exceeded_transfer_limit, total_count, pages_seen) are populated from the underlying protocol response when available:

GeoServices FeatureServer surfaces exceededTransferLimit on each page; total_count defaults to len(features).
OGC Features / STAC surface numberMatched (total) and numberReturned; exceeded_transfer_limit is derived from a next link being present on the last page walked.
OData surfaces @odata.count (total) and @odata.nextLink (drives exceeded_transfer_limit).

When the protocol does not expose a signal the field defaults to a safe value (False / None) — never silently fabricated.

honua-sdk › Models¶

Geometry, schema, and GeoDataFrame ergonomics¶

honua_sdk.Query dataclass ¶

Filter routing¶

honua_sdk.Result dataclass ¶

to_geodataframe() ¶

honua_sdk.QueryFeature dataclass ¶

__geo_interface__ property ¶

geometry_shape property ¶

to_shapely() ¶

honua_sdk.Feature dataclass ¶

__geo_interface__ property ¶

geometry_shape property ¶

to_shapely() ¶

honua_sdk.LayerSchema dataclass ¶

field_names property ¶

field(name) ¶

from_metadata(payload) classmethod ¶

honua_sdk.Field dataclass ¶

honua_sdk.Extent dataclass ¶

bbox property ¶

honua_sdk.SourceDescriptor dataclass ¶

supports(capability) ¶

honua_sdk.SourceLocator dataclass ¶

honua_sdk.FeatureQuery dataclass ¶

honua_sdk.FeatureQueryResult dataclass ¶

`honua_sdk.Query` `dataclass` ¶

`honua_sdk.Result` `dataclass` ¶

`to_geodataframe()` ¶

`honua_sdk.QueryFeature` `dataclass` ¶

`__geo_interface__` `property` ¶

`geometry_shape` `property` ¶

`to_shapely()` ¶

`honua_sdk.Feature` `dataclass` ¶

`__geo_interface__` `property` ¶

`geometry_shape` `property` ¶

`to_shapely()` ¶

`honua_sdk.LayerSchema` `dataclass` ¶

`field_names` `property` ¶

`field(name)` ¶

`from_metadata(payload)` `classmethod` ¶

`honua_sdk.Field` `dataclass` ¶

`honua_sdk.Extent` `dataclass` ¶

`bbox` `property` ¶

`honua_sdk.SourceDescriptor` `dataclass` ¶

`supports(capability)` ¶

`honua_sdk.SourceLocator` `dataclass` ¶

`honua_sdk.FeatureQuery` `dataclass` ¶

`honua_sdk.FeatureQueryResult` `dataclass` ¶