Skip to content

honua-admin › Clients

The admin SDK ships sync and async clients with parity to the data-plane SDK: pick HonuaAdminClient for scripts and CLIs, and AsyncHonuaAdminClient for async services. Both clients share the data-plane configuration model (auth, retries, timeouts, with_options(...)); see the honua-sdk core client model for the conceptual overview that applies to both packages.

from honua_admin import HonuaAdminClient

with HonuaAdminClient("https://admin.your-honua-server.com", api_key="...") as admin:
    services = admin.list_services()

See also: honua-sdk Clients for the data-plane counterpart that shares the same configuration model, and Core client model for cross-package with_options(...) semantics.

honua_admin.HonuaAdminClient

Synchronous client for the Honua Admin (control-plane) API.

Methods map 1:1 to admin REST endpoints (services, metadata resources, manifests, connections, layers, styles, config) and return typed model objects.

Authentication is configured at construction with at most one of api_key, bearer_token, or auth_provider (mutually exclusive). bearer_token= is deprecated (removal in 0.2.x); prefer auth_provider=StaticAuthProvider({"Authorization": f"Bearer {token}"}). When client is supplied as a pre-built :class:httpx.Client, no auth kwargs may be passed — configure them on the client instead.

Retries: only idempotent methods (GET/HEAD/PUT/DELETE/OPTIONS) on transient statuses (429/502/503/504) are retried by default. Opt POST in by configuring retry_methods on the underlying retry transport; mutating helpers (apply_manifest, create_connection, publish_layer) then auto-generate Idempotency-Key headers.

Use as a context manager so the underlying transport closes deterministically::

with HonuaAdminClient("https://example.com", api_key="...") as admin:
    services = admin.list_services()

Per-call overrides (timeout, extra_headers, idempotency_key) are exposed on every method; use :meth:with_options for sticky per-clone overrides (shared transport unless base_url is supplied).

All HTTP failures surface as :class:HonuaHttpError (or one of its status-specific subclasses such as :class:HonuaAuthError / :class:HonuaRateLimitError); transport-level failures surface as :class:HonuaTransportError (and its subclass :class:HonuaTimeoutError).

See also: :class:honua_sdk.HonuaClient and docs/core-client.md.

__init__(base_url, *, timeout=30.0, api_key=None, bearer_token=None, auth_provider=None, follow_redirects=False, client=None, transport=None, max_retries=3)

Construct an admin client bound to a single Honua deployment.

Parameters:

Name Type Description Default
base_url str

Server base URL (scheme + host + optional path prefix). Trailing slashes are normalized.

 required
timeout float

Request timeout in seconds applied to every call.

 30.0
api_key str | None

Optional X-API-Key header value. Mutually exclusive with passing a pre-built client.

 None
bearer_token str | None

Optional Authorization: Bearer … value. Mutually exclusive with auth_provider and with a pre-built client.

 None
auth_provider AuthProvider | None

Pluggable provider that yields request-time auth headers. Mutually exclusive with bearer_token and with a pre-built client.

 None
follow_redirects bool

Whether the underlying :class:httpx.Client follows 3xx redirects. Sensitive auth headers are still stripped when redirected to a different authority.

 False
client Client | None

A caller-supplied :class:httpx.Client. When set, the SDK will not own or close the client and the auth kwargs above must not be passed (configure them on the client instead).

 None
transport BaseTransport | None

A caller-supplied :class:httpx.BaseTransport. Mutually exclusive with client. Use this to inject a :class:httpx.MockTransport in tests.

 None
max_retries int

Maximum number of retry attempts on transient HTTP statuses (429/502/503/504). 0 disables retries. Only safe methods (GET/HEAD/PUT/DELETE/OPTIONS) and transient statuses (429/502/503/504) are retried by default.

 3

Raises:

Type Description
ValueError

client and transport are both supplied, or auth kwargs are supplied alongside a pre-built client.

close()

Release underlying HTTP resources if this instance owns the client.

When constructed with an externally supplied :class:httpx.Client, ownership stays with the caller and this method is a no-op.

with_options(*, timeout=None, max_retries=None, base_url=None)

Return a clone with overridden options.

When only timeout and/or max_retries are supplied, the returned client reuses the original's :class:httpx.Client and its connection pool — only the per-request timeout and (optionally) the per-request retry budget are overridden. In this transport-sharing mode the clone does not own the underlying client; calling :meth:close on the clone is a no-op. Only the original is responsible for closing the transport.

Passing base_url creates an independent client; the transport is NOT shared. Because the underlying :class:httpx.Client binds its base_url (and authority-bound timeouts, event hooks, and connection-pool keys) at construction time, swapping the base URL on a shared client would silently target the wrong host for any code path that relies on those bindings. To avoid that footgun, supplying base_url builds a fresh :class:httpx.Client for the clone and the clone owns it — you must clone.close() (or use with) independently of the original.

The auth provider, if any, is reused (not duplicated) so token state is shared across the original and the clone.

Parameters:

Name Type Description Default
timeout float | None

When set, overrides the per-request timeout. Smaller timeout values automatically build an independent client (with the smaller transport timeout); larger values reuse the parent's transport with a per-request httpx.Timeout(...) override.

 None
max_retries int | None

When set, overrides the retry budget. 0 disables retries on the clone via a per-request extension read by the retry transport.

 None
base_url str | None

When set, the returned clone is fully independent (owns its own :class:httpx.Client and connection pool) and must be closed separately. The transport is NOT shared with the original.

 None

Returns:

Name Type Description
An HonuaAdminClient

class:HonuaAdminClient — transport-sharing when
HonuaAdminClient

the override timeout is greater than or equal to the
HonuaAdminClient

parent's configured timeout, independently-owned when
HonuaAdminClient

base_url is supplied or when timeout is smaller than
HonuaAdminClient

the parent's configured timeout.

copy(*, timeout=None, max_retries=None, base_url=None)

Alias for :meth:with_options.

Provided for parity with the stripe-python convention. The semantics are identical to :meth:with_options; see that method for the full contract.

list_services(*, timeout=None, extra_headers=None)

List every service registered on the admin catalog.

Returns:

Name Type Description
Typed list[ServiceSummary]

class:ServiceSummary objects for each service the
list[ServiceSummary]

server reports. Empty when the server returns a non-list
list[ServiceSummary]

payload (e.g. an empty envelope).

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed before any HTTP response was received.

get_service_settings(name, *, timeout=None, extra_headers=None)

Fetch the resolved settings for a single service.

Parameters:

Name Type Description Default
name str

Service name as advertised by the catalog. URL-encoded.

 required

Returns:

Name Type Description
A ServiceSettingsResponse

class:ServiceSettingsResponse describing protocol
ServiceSettingsResponse

availability and per-protocol configuration.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_protocols(name, protocols, *, timeout=None, extra_headers=None, idempotency_key=None)

Replace the enabled-protocol list for a service.

Parameters:

Name Type Description Default
name str

Service name; URL-encoded.

 required
protocols list[str]

Desired ordered list of protocol identifiers.

 required

Returns:

Type Description
ServiceSettingsResponse

The refreshed :class:ServiceSettingsResponse.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update.
HonuaTransportError

The request failed at the transport layer.

update_mapserver_settings(name, *, max_image_width=None, max_image_height=None, default_image_width=None, default_image_height=None, default_dpi=None, default_format=None, default_transparent=None, max_features_per_layer=None, extra_settings=None, timeout=None, extra_headers=None, idempotency_key=None)

Patch the MapServer-specific settings for a service.

Parameters:

Name Type Description Default
name str

Service name; URL-encoded.

 required
max_image_width int | None

Maximum allowed image width in pixels.

 None
max_image_height int | None

Maximum allowed image height in pixels.

 None
default_image_width int | None

Default image width applied when callers omit one.

 None
default_image_height int | None

Default image height applied when callers omit one.

 None
default_dpi int | None

Default DPI used when callers omit one.

 None
default_format str | None

Default image format (e.g. "png", "jpg").

 None
default_transparent bool | None

Default transparency setting for rendered tiles.

 None
max_features_per_layer int | None

Server-side cap on features returned per layer.

 None
extra_settings Mapping[str, Any] | None

Escape hatch for additional snake-case settings that aren't represented as explicit kwargs. Keys are converted to camelCase before being sent. Only fields with non-None values are forwarded.

 None

Returns:

Type Description
ServiceSettingsResponse

The refreshed :class:ServiceSettingsResponse.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update.
HonuaTransportError

The request failed at the transport layer.

list_metadata_resources(kind=None, namespace=None, *, timeout=None, extra_headers=None)

List metadata resources, optionally filtered by kind/namespace.

Parameters:

Name Type Description Default
kind str | None

Optional resource-kind filter.

 None
namespace str | None

Optional namespace filter.

 None

Returns:

Name Type Description
Matching list[MetadataResource]

class:MetadataResource objects; empty when the
list[MetadataResource]

server returns a non-list payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_metadata_resource(kind, ns, name, *, timeout=None, extra_headers=None)

Fetch a single metadata resource together with its ETag.

Parameters:

Name Type Description Default
kind str

Resource kind; URL-encoded.

 required
ns str

Namespace; URL-encoded.

 required
name str

Resource name; URL-encoded.

 required

Returns:

Type Description
MetadataResource

A tuple (resource, etag); etag is None when the
str | None

server did not return an ETag response header.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status or the response body was not valid JSON.
HonuaTransportError

The request failed at the transport layer.

create_metadata_resource(resource, *, timeout=None, extra_headers=None, idempotency_key=None)

Create a new metadata resource on the server.

Parameters:

Name Type Description Default
resource MetadataResource

Desired initial state of the resource.

 required

Returns:

Type Description
MetadataResource

The server-canonical :class:MetadataResource after creation.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the create.
HonuaTransportError

The request failed at the transport layer.

update_metadata_resource(kind, ns, name, resource, *, if_match=None, timeout=None, extra_headers=None, idempotency_key=None)

Replace the contents of a metadata resource.

Parameters:

Name Type Description Default
kind str

Resource kind; URL-encoded.

 required
ns str

Namespace; URL-encoded.

 required
name str

Resource name; URL-encoded.

 required
resource MetadataResource

Desired full state of the resource.

 required
if_match str | None

Optional ETag for optimistic concurrency.

 None

Returns:

Type Description
MetadataResource

The server-canonical :class:MetadataResource after update.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update (including precondition failures when if_match is supplied).
HonuaTransportError

The request failed at the transport layer.

delete_metadata_resource(kind, ns, name, *, if_match=None, timeout=None, extra_headers=None, idempotency_key=None)

Delete a single metadata resource.

Parameters:

Name Type Description Default
kind str

Resource kind; URL-encoded.

 required
ns str

Namespace; URL-encoded.

 required
name str

Resource name; URL-encoded.

 required
if_match str | None

Optional ETag for optimistic concurrency.

 None

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the delete.
HonuaTransportError

The request failed at the transport layer.

get_version(*, timeout=None, extra_headers=None)

Return the server's reported admin API version.

Returns:

Name Type Description
An AdminVersionResponse

class:AdminVersionResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_capabilities(*, timeout=None, extra_headers=None)

Return the server's advertised admin capabilities and compat block.

Returns:

Name Type Description
An AdminCapabilitiesResponse

class:AdminCapabilitiesResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_capability_flags(*, timeout=None, extra_headers=None)

Return coarse feature flags from the admin compatibility contract.

When the server does not expose a compatibility block (older deployments), the returned flags are all False.

Returns:

Name Type Description
An AdminCompatibilityFeatureFlags

class:AdminCompatibilityFeatureFlags describing which
AdminCompatibilityFeatureFlags

optional admin surfaces the server supports.

Raises:

Type Description
HonuaHttpError

The underlying capabilities fetch failed with a non-success status.
HonuaTransportError

The capabilities fetch failed at the transport layer.

Per-request options (timeout / extra_headers) are forwarded to :meth:get_capabilities.

check_compatibility(*, timeout=None, extra_headers=None)

Evaluate whether the connected server satisfies the admin SDK baseline.

Returns:

Name Type Description
An AdminCompatibilityCheckResult

class:AdminCompatibilityCheckResult summarising whether
AdminCompatibilityCheckResult

the server's compatibility block meets
AdminCompatibilityCheckResult

attr:MINIMUM_SUPPORTED_SERVER_BASELINE, along with any
AdminCompatibilityCheckResult

specific gaps.

Raises:

Type Description
HonuaHttpError

The underlying capabilities fetch failed with a non-success status.
HonuaTransportError

The capabilities fetch failed at the transport layer.

Per-request options (timeout / extra_headers) are forwarded to :meth:get_capabilities.

get_manifest(namespace=None, *, timeout=None, extra_headers=None)

Export the server's metadata as a single declarative manifest.

Parameters:

Name Type Description Default
namespace str | None

Optional namespace filter.

 None

Returns:

Name Type Description
A MetadataManifest

class:MetadataManifest.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

apply_manifest(request, *, idempotency_key=None, timeout=None, extra_headers=None)

Apply a declarative metadata manifest to the server.

Parameters:

Name Type Description Default
request ManifestApplyRequest

Manifest payload plus any dry-run / prune flags.

 required
idempotency_key str | None

Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side.

 None

Returns:

Name Type Description
A ManifestApplyResult

class:ManifestApplyResult summarising the effect.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the manifest.
HonuaTransportError

The request failed at the transport layer.

scan_migration_source(request, *, export_json=False, timeout=None, extra_headers=None, idempotency_key=None)

POST /api/v1/admin/import/scan

list_connections(*, timeout=None, extra_headers=None)

List every secure datasource connection registered on the server.

Returns:

Name Type Description
Typed list[SecureConnectionSummary]

class:SecureConnectionSummary objects; empty when
list[SecureConnectionSummary]

the server returns a non-list payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_connection(id, *, timeout=None, extra_headers=None)

Fetch detailed information for a single secure connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required

Returns:

Name Type Description
A SecureConnectionDetail

class:SecureConnectionDetail.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

create_connection(request, *, idempotency_key=None, timeout=None, extra_headers=None)

Create a new secure datasource connection.

Parameters:

Name Type Description Default
request CreateSecureConnectionRequest

Connection definition (DSN, credentials, options).

 required
idempotency_key str | None

Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side.

 None

Returns:

Name Type Description
A SecureConnectionSummary

class:SecureConnectionSummary (secrets elided).

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the create.
HonuaTransportError

The request failed at the transport layer.

test_draft_connection(request, *, timeout=None, extra_headers=None, idempotency_key=None)

Verify a draft connection definition without persisting it.

Parameters:

Name Type Description Default
request CreateSecureConnectionRequest

The same payload that would be sent to :meth:create_connection.

 required

Returns:

Name Type Description
A ConnectionTestResult

class:ConnectionTestResult. A failed probe is reported
ConnectionTestResult

in the result payload, not as an exception.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server returned a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_connection(id, request, *, timeout=None, extra_headers=None, idempotency_key=None)

Replace mutable fields on an existing secure connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required
request UpdateSecureConnectionRequest

Patch payload describing the new state.

 required

Returns:

Type Description
SecureConnectionSummary

A refreshed :class:SecureConnectionSummary.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update.
HonuaTransportError

The request failed at the transport layer.

test_connection(id, *, timeout=None, extra_headers=None, idempotency_key=None)

Re-run the server-side connection probe for a stored connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required

Returns:

Name Type Description
A ConnectionTestResult

class:ConnectionTestResult.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server itself rejected the request.
HonuaTransportError

The request failed at the transport layer.

delete_connection(id, *, timeout=None, extra_headers=None, idempotency_key=None)

Delete a stored secure connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the delete.
HonuaTransportError

The request failed at the transport layer.

validate_encryption(*, timeout=None, extra_headers=None, idempotency_key=None)

Verify that the server can decrypt every stored credential.

Returns:

Name Type Description
An EncryptionValidationResult

class:EncryptionValidationResult.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

rotate_encryption_key(*, timeout=None, extra_headers=None, idempotency_key=None)

Rotate the server's connection-encryption key.

Returns:

Name Type Description
A KeyRotationResult

class:KeyRotationResult.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the rotation request.
HonuaTransportError

The request failed at the transport layer.

list_layers(conn_id, service_name=None, *, timeout=None, extra_headers=None)

List published layers belonging to a connection.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
service_name str | None

When provided, restrict to one service's layers.

 None

Returns:

Name Type Description
Matching list[PublishedLayerSummary]

class:PublishedLayerSummary objects; empty when
list[PublishedLayerSummary]

the server returns a non-list payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

publish_layer(conn_id, request, *, idempotency_key=None, timeout=None, extra_headers=None)

Publish a new layer derived from a stored connection.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
request PublishLayerRequest

Layer-publication payload.

 required
idempotency_key str | None

Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side.

 None

Returns:

Name Type Description
A PublishedLayerSummary

class:PublishedLayerSummary describing the new layer.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the publish request.
HonuaTransportError

The request failed at the transport layer.

set_layer_enabled(conn_id, layer_id, enabled, service_name=None, *, timeout=None, extra_headers=None, idempotency_key=None)

Toggle whether a single published layer is enabled.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
layer_id int

Numeric layer identifier.

 required
enabled bool

Desired enabled state.

 required
service_name str | None

Optional service-scoped toggle.

 None

Returns:

Type Description
PublishedLayerSummary

The refreshed :class:PublishedLayerSummary.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the toggle.
HonuaTransportError

The request failed at the transport layer.

set_service_layers_enabled(conn_id, enabled, service_name=None, *, timeout=None, extra_headers=None, idempotency_key=None)

Toggle every layer on a connection (optionally per service) in bulk.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
enabled bool

Desired enabled state for every layer in scope.

 required
service_name str | None

Optional per-service restriction.

 None

Returns:

Name Type Description
Refreshed list[PublishedLayerSummary]

class:PublishedLayerSummary objects for every
list[PublishedLayerSummary]

affected layer; empty when the server returns a non-list
list[PublishedLayerSummary]

payload.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the bulk toggle.
HonuaTransportError

The request failed at the transport layer.

discover_tables(conn_id, *, timeout=None, extra_headers=None)

Ask the server which tables are visible through a connection.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required

Returns:

Name Type Description
A TableDiscoveryResponse

class:TableDiscoveryResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

list_styles(*, timeout=None, extra_headers=None)

List the styles published over OGC API - Styles (GET /ogc/styles).

Returns:

Name Type Description
An OgcStylesList

class:OgcStylesList of styleId-keyed entries plus the
OgcStylesList

optional default style and landing links.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_stylesheet(style_id, *, encoding=_DEFAULT_STYLE_ENCODING, timeout=None, extra_headers=None)

Fetch a stylesheet by style_id (GET /ogc/styles/{styleId}).

The encoding is selected by Accept content negotiation: mapbox-style (MapLibre/Mapbox JSON, the default), sld-1.0, or sld-1.1 (derived on demand by the server).

Parameters:

Name Type Description Default
style_id str

Stable style identifier.

 required
encoding StyleEncoding

Desired stylesheet encoding (see :data:StyleEncoding).

 DEFAULT_STYLE_ENCODING

Returns:

Name Type Description
An OgcStylesheet

class:OgcStylesheet carrying the raw content and the
OgcStylesheet

media_type the server returned.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status (e.g. 404 unknown style, 406 unsupported encoding).
HonuaTransportError

The request failed at the transport layer.

get_style_metadata(style_id, *, timeout=None, extra_headers=None)

Fetch style metadata (GET /ogc/styles/{styleId}/metadata).

Parameters:

Name Type Description Default
style_id str

Stable style identifier.

 required

Returns:

Name Type Description
An OgcStyleMetadata

class:OgcStyleMetadata describing the style.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_style(style_id, style, *, strict=False, timeout=None, extra_headers=None, idempotency_key=None)

Replace an existing style's MapLibre stylesheet (PUT /ogc/styles/{styleId}).

Phase 1 manage-styles accepts only a MapLibre/Mapbox style document; the server validates and stores it against the existing style. Standalone style creation/deletion is not yet supported.

Parameters:

Name Type Description Default
style_id str

Stable style identifier (must already exist).

 required
style Mapping[str, Any]

The MapLibre/Mapbox stylesheet document.

 required
strict bool

When True, request strict validation via Prefer: handling=strict.

 False

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update (e.g. 400 invalid style, 404 unknown style, 415 unsupported media type).
HonuaTransportError

The request failed at the transport layer.

get_layer_style(layer_id, *, timeout=None, extra_headers=None)

Fetch the stored renderer / style document for a layer.

.. deprecated:: This layerId-keyed path is a back-compat alias (ADR-0048). Prefer the styleId-keyed :meth:get_stylesheet / :meth:get_style_metadata over OGC API - Styles.

Parameters:

Name Type Description Default
layer_id int

Numeric layer identifier.

 required

Returns:

Name Type Description
A LayerStyleResponse

class:LayerStyleResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_layer_style(layer_id, request, *, timeout=None, extra_headers=None, idempotency_key=None)

Replace the stored renderer / style document for a layer.

.. deprecated:: This layerId-keyed path is a back-compat alias (ADR-0048). Prefer the styleId-keyed :meth:update_style over OGC API - Styles.

Parameters:

Name Type Description Default
layer_id int

Numeric layer identifier.

 required
request LayerStyleUpdateRequest

The new renderer payload.

 required

Returns:

Type Description
LayerStyleResponse

A refreshed :class:LayerStyleResponse.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the style update.
HonuaTransportError

The request failed at the transport layer.

get_config(*, timeout=None, extra_headers=None)

Return the server's effective admin configuration block.

Returns:

Type Description
dict[str, Any]

The server-side admin config as a plain dict; an empty
dict[str, Any]

dict when the server returns a non-mapping payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

honua_admin.AsyncHonuaAdminClient

Asynchronous client for the Honua Admin (control-plane) API.

Async counterpart to :class:HonuaAdminClient: methods map 1:1 to admin REST endpoints (services, metadata resources, manifests, connections, layers, styles, config) and return typed model objects.

Authentication is configured at construction with at most one of api_key, bearer_token, or auth_provider (mutually exclusive). bearer_token= is deprecated (removal in 0.2.x); prefer auth_provider=StaticAuthProvider({"Authorization": f"Bearer {token}"}). When client is supplied as a pre-built :class:httpx.AsyncClient, no auth kwargs may be passed — configure them on the client instead.

Retries: only idempotent methods (GET/HEAD/PUT/DELETE/OPTIONS) on transient statuses (429/502/503/504) are retried by default. Opt POST in by configuring retry_methods on the underlying retry transport; mutating helpers (apply_manifest, create_connection, publish_layer) then auto-generate Idempotency-Key headers.

Use as an async context manager so the underlying transport closes deterministically::

async with AsyncHonuaAdminClient("https://example.com", api_key="...") as admin:
    services = await admin.list_services()

Per-call overrides (timeout, extra_headers, idempotency_key) are exposed on every method; use :meth:with_options for sticky per-clone overrides (shared transport unless base_url is supplied).

All HTTP failures surface as :class:HonuaHttpError (or one of its status-specific subclasses such as :class:HonuaAuthError / :class:HonuaRateLimitError); transport-level failures surface as :class:HonuaTransportError (and its subclass :class:HonuaTimeoutError).

See also: :class:honua_sdk.AsyncHonuaClient and docs/core-client.md.

__init__(base_url, *, timeout=30.0, api_key=None, bearer_token=None, auth_provider=None, follow_redirects=False, client=None, transport=None, max_retries=3)

Construct an async admin client bound to a single Honua deployment.

Parameters:

Name Type Description Default
base_url str

Server base URL (scheme + host + optional path prefix). Trailing slashes are normalized.

 required
timeout float

Request timeout in seconds applied to every call.

 30.0
api_key str | None

Optional X-API-Key header value. Mutually exclusive with passing a pre-built client.

 None
bearer_token str | None

Optional Authorization: Bearer … value. Mutually exclusive with auth_provider and with a pre-built client.

 None
auth_provider AuthProvider | None

Pluggable provider that yields request-time auth headers. Mutually exclusive with bearer_token and with a pre-built client.

 None
follow_redirects bool

Whether the underlying :class:httpx.AsyncClient follows 3xx redirects. Sensitive auth headers are still stripped when redirected to a different authority.

 False
client AsyncClient | None

A caller-supplied :class:httpx.AsyncClient. When set, the SDK will not own or close the client and the auth kwargs above must not be passed (configure them on the client instead).

 None
transport AsyncBaseTransport | None

A caller-supplied :class:httpx.AsyncBaseTransport. Mutually exclusive with client. Use this to inject a :class:httpx.MockTransport in tests.

 None
max_retries int

Maximum number of retry attempts on transient HTTP statuses (429/502/503/504). 0 disables retries. Only safe methods (GET/HEAD/PUT/DELETE/OPTIONS) and transient statuses (429/502/503/504) are retried by default.

 3

Raises:

Type Description
ValueError

client and transport are both supplied, or auth kwargs are supplied alongside a pre-built client.

close() async

Release underlying HTTP resources if this instance owns the client.

When constructed with an externally supplied :class:httpx.AsyncClient, ownership stays with the caller and this coroutine is a no-op.

with_options(*, timeout=None, max_retries=None, base_url=None)

Return a clone with overridden options.

When only timeout and/or max_retries are supplied, the returned client reuses the original's :class:httpx.AsyncClient and its connection pool — only the per-request timeout and (optionally) the per-request retry budget are overridden. In this transport-sharing mode the clone does not own the underlying client; awaiting :meth:close on the clone is a no-op. Only the original is responsible for closing the transport.

Passing base_url creates an independent client; the transport is NOT shared. Because the underlying :class:httpx.AsyncClient binds its base_url (and authority-bound timeouts, event hooks, and connection-pool keys) at construction time, swapping the base URL on a shared client would silently target the wrong host for any code path that relies on those bindings. To avoid that footgun, supplying base_url builds a fresh :class:httpx.AsyncClient for the clone and the clone owns it — you must await clone.close() (or use async with) independently of the original.

The auth provider, if any, is reused (not duplicated) so token state is shared across the original and the clone.

Parameters:

Name Type Description Default
timeout float | None

When set, overrides the per-request timeout. Smaller timeout values automatically build an independent client (with the smaller transport timeout); larger values reuse the parent's transport with a per-request httpx.Timeout(...) override.

 None
max_retries int | None

When set, overrides the retry budget. 0 disables retries on the clone via a per-request extension read by the retry transport.

 None
base_url str | None

When set, the returned clone is fully independent (owns its own :class:httpx.AsyncClient and connection pool) and must be closed separately. The transport is NOT shared with the original.

 None

Returns:

Name Type Description
An AsyncHonuaAdminClient

class:AsyncHonuaAdminClient — transport-sharing when
AsyncHonuaAdminClient

the override timeout is greater than or equal to the
AsyncHonuaAdminClient

parent's configured timeout, independently-owned when
AsyncHonuaAdminClient

base_url is supplied or when timeout is smaller than
AsyncHonuaAdminClient

the parent's configured timeout.

copy(*, timeout=None, max_retries=None, base_url=None)

Alias for :meth:with_options.

Provided for parity with the stripe-python convention. The semantics are identical to :meth:with_options; see that method for the full contract.

list_services(*, timeout=None, extra_headers=None) async

List every service registered on the admin catalog.

Returns:

Name Type Description
Typed list[ServiceSummary]

class:ServiceSummary objects for each service the
list[ServiceSummary]

server reports. Empty when the server returns a non-list
list[ServiceSummary]

payload (e.g. an empty envelope).

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed before any HTTP response was received.

get_service_settings(name, *, timeout=None, extra_headers=None) async

Fetch the resolved settings for a single service.

Parameters:

Name Type Description Default
name str

Service name as advertised by the catalog. URL-encoded.

 required

Returns:

Name Type Description
A ServiceSettingsResponse

class:ServiceSettingsResponse describing protocol
ServiceSettingsResponse

availability and per-protocol configuration.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_protocols(name, protocols, *, timeout=None, extra_headers=None, idempotency_key=None) async

Replace the enabled-protocol list for a service.

Parameters:

Name Type Description Default
name str

Service name; URL-encoded.

 required
protocols list[str]

Desired ordered list of protocol identifiers.

 required

Returns:

Type Description
ServiceSettingsResponse

The refreshed :class:ServiceSettingsResponse.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update.
HonuaTransportError

The request failed at the transport layer.

update_mapserver_settings(name, *, max_image_width=None, max_image_height=None, default_image_width=None, default_image_height=None, default_dpi=None, default_format=None, default_transparent=None, max_features_per_layer=None, extra_settings=None, timeout=None, extra_headers=None, idempotency_key=None) async

Patch the MapServer-specific settings for a service.

Parameters:

Name Type Description Default
name str

Service name; URL-encoded.

 required
max_image_width int | None

Maximum allowed image width in pixels.

 None
max_image_height int | None

Maximum allowed image height in pixels.

 None
default_image_width int | None

Default image width applied when callers omit one.

 None
default_image_height int | None

Default image height applied when callers omit one.

 None
default_dpi int | None

Default DPI used when callers omit one.

 None
default_format str | None

Default image format (e.g. "png", "jpg").

 None
default_transparent bool | None

Default transparency setting for rendered tiles.

 None
max_features_per_layer int | None

Server-side cap on features returned per layer.

 None
extra_settings Mapping[str, Any] | None

Escape hatch for additional snake-case settings that aren't represented as explicit kwargs. Keys are converted to camelCase before being sent. Only fields with non-None values are forwarded.

 None

Returns:

Type Description
ServiceSettingsResponse

The refreshed :class:ServiceSettingsResponse.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update.
HonuaTransportError

The request failed at the transport layer.

list_metadata_resources(kind=None, namespace=None, *, timeout=None, extra_headers=None) async

List metadata resources, optionally filtered by kind/namespace.

Parameters:

Name Type Description Default
kind str | None

Optional resource-kind filter.

 None
namespace str | None

Optional namespace filter.

 None

Returns:

Name Type Description
Matching list[MetadataResource]

class:MetadataResource objects; empty when the
list[MetadataResource]

server returns a non-list payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_metadata_resource(kind, ns, name, *, timeout=None, extra_headers=None) async

Fetch a single metadata resource together with its ETag.

Parameters:

Name Type Description Default
kind str

Resource kind; URL-encoded.

 required
ns str

Namespace; URL-encoded.

 required
name str

Resource name; URL-encoded.

 required

Returns:

Type Description
MetadataResource

A tuple (resource, etag); etag is None when the
str | None

server did not return an ETag response header.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status or the response body was not valid JSON.
HonuaTransportError

The request failed at the transport layer.

create_metadata_resource(resource, *, timeout=None, extra_headers=None, idempotency_key=None) async

Create a new metadata resource on the server.

Parameters:

Name Type Description Default
resource MetadataResource

Desired initial state of the resource.

 required

Returns:

Type Description
MetadataResource

The server-canonical :class:MetadataResource after creation.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the create.
HonuaTransportError

The request failed at the transport layer.

update_metadata_resource(kind, ns, name, resource, *, if_match=None, timeout=None, extra_headers=None, idempotency_key=None) async

Replace the contents of a metadata resource.

Parameters:

Name Type Description Default
kind str

Resource kind; URL-encoded.

 required
ns str

Namespace; URL-encoded.

 required
name str

Resource name; URL-encoded.

 required
resource MetadataResource

Desired full state of the resource.

 required
if_match str | None

Optional ETag for optimistic concurrency.

 None

Returns:

Type Description
MetadataResource

The server-canonical :class:MetadataResource after update.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update (including precondition failures when if_match is supplied).
HonuaTransportError

The request failed at the transport layer.

delete_metadata_resource(kind, ns, name, *, if_match=None, timeout=None, extra_headers=None, idempotency_key=None) async

Delete a single metadata resource.

Parameters:

Name Type Description Default
kind str

Resource kind; URL-encoded.

 required
ns str

Namespace; URL-encoded.

 required
name str

Resource name; URL-encoded.

 required
if_match str | None

Optional ETag for optimistic concurrency.

 None

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the delete.
HonuaTransportError

The request failed at the transport layer.

get_version(*, timeout=None, extra_headers=None) async

Return the server's reported admin API version.

Returns:

Name Type Description
An AdminVersionResponse

class:AdminVersionResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_capabilities(*, timeout=None, extra_headers=None) async

Return the server's advertised admin capabilities and compat block.

Returns:

Name Type Description
An AdminCapabilitiesResponse

class:AdminCapabilitiesResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_capability_flags(*, timeout=None, extra_headers=None) async

Return coarse feature flags from the admin compatibility contract.

When the server does not expose a compatibility block (older deployments), the returned flags are all False.

Returns:

Name Type Description
An AdminCompatibilityFeatureFlags

class:AdminCompatibilityFeatureFlags describing which
AdminCompatibilityFeatureFlags

optional admin surfaces the server supports.

Raises:

Type Description
HonuaHttpError

The underlying capabilities fetch failed with a non-success status.
HonuaTransportError

The capabilities fetch failed at the transport layer.

Per-request options (timeout / extra_headers) are forwarded to :meth:get_capabilities.

check_compatibility(*, timeout=None, extra_headers=None) async

Evaluate whether the connected server satisfies the admin SDK baseline.

Returns:

Name Type Description
An AdminCompatibilityCheckResult

class:AdminCompatibilityCheckResult summarising whether
AdminCompatibilityCheckResult

the server's compatibility block meets
AdminCompatibilityCheckResult

attr:MINIMUM_SUPPORTED_SERVER_BASELINE, along with any
AdminCompatibilityCheckResult

specific gaps.

Raises:

Type Description
HonuaHttpError

The underlying capabilities fetch failed with a non-success status.
HonuaTransportError

The capabilities fetch failed at the transport layer.

Per-request options (timeout / extra_headers) are forwarded to :meth:get_capabilities.

get_manifest(namespace=None, *, timeout=None, extra_headers=None) async

Export the server's metadata as a single declarative manifest.

Parameters:

Name Type Description Default
namespace str | None

Optional namespace filter.

 None

Returns:

Name Type Description
A MetadataManifest

class:MetadataManifest.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

apply_manifest(request, *, idempotency_key=None, timeout=None, extra_headers=None) async

Apply a declarative metadata manifest to the server.

Parameters:

Name Type Description Default
request ManifestApplyRequest

Manifest payload plus any dry-run / prune flags.

 required
idempotency_key str | None

Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side.

 None

Returns:

Name Type Description
A ManifestApplyResult

class:ManifestApplyResult summarising the effect.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the manifest.
HonuaTransportError

The request failed at the transport layer.

scan_migration_source(request, *, export_json=False, timeout=None, extra_headers=None, idempotency_key=None) async

POST /api/v1/admin/import/scan

list_connections(*, timeout=None, extra_headers=None) async

List every secure datasource connection registered on the server.

Returns:

Name Type Description
Typed list[SecureConnectionSummary]

class:SecureConnectionSummary objects; empty when
list[SecureConnectionSummary]

the server returns a non-list payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_connection(id, *, timeout=None, extra_headers=None) async

Fetch detailed information for a single secure connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required

Returns:

Name Type Description
A SecureConnectionDetail

class:SecureConnectionDetail.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

create_connection(request, *, idempotency_key=None, timeout=None, extra_headers=None) async

Create a new secure datasource connection.

Parameters:

Name Type Description Default
request CreateSecureConnectionRequest

Connection definition (DSN, credentials, options).

 required
idempotency_key str | None

Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side.

 None

Returns:

Name Type Description
A SecureConnectionSummary

class:SecureConnectionSummary (secrets elided).

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the create.
HonuaTransportError

The request failed at the transport layer.

test_draft_connection(request, *, timeout=None, extra_headers=None, idempotency_key=None) async

Verify a draft connection definition without persisting it.

Parameters:

Name Type Description Default
request CreateSecureConnectionRequest

The same payload that would be sent to :meth:create_connection.

 required

Returns:

Name Type Description
A ConnectionTestResult

class:ConnectionTestResult. A failed probe is reported
ConnectionTestResult

in the result payload, not as an exception.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server returned a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_connection(id, request, *, timeout=None, extra_headers=None, idempotency_key=None) async

Replace mutable fields on an existing secure connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required
request UpdateSecureConnectionRequest

Patch payload describing the new state.

 required

Returns:

Type Description
SecureConnectionSummary

A refreshed :class:SecureConnectionSummary.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update.
HonuaTransportError

The request failed at the transport layer.

test_connection(id, *, timeout=None, extra_headers=None, idempotency_key=None) async

Re-run the server-side connection probe for a stored connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required

Returns:

Name Type Description
A ConnectionTestResult

class:ConnectionTestResult.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server itself rejected the request.
HonuaTransportError

The request failed at the transport layer.

delete_connection(id, *, timeout=None, extra_headers=None, idempotency_key=None) async

Delete a stored secure connection.

Parameters:

Name Type Description Default
id str

Connection identifier; URL-encoded.

 required

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the delete.
HonuaTransportError

The request failed at the transport layer.

validate_encryption(*, timeout=None, extra_headers=None, idempotency_key=None) async

Verify that the server can decrypt every stored credential.

Returns:

Name Type Description
An EncryptionValidationResult

class:EncryptionValidationResult.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

rotate_encryption_key(*, timeout=None, extra_headers=None, idempotency_key=None) async

Rotate the server's connection-encryption key.

Returns:

Name Type Description
A KeyRotationResult

class:KeyRotationResult.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the rotation request.
HonuaTransportError

The request failed at the transport layer.

list_layers(conn_id, service_name=None, *, timeout=None, extra_headers=None) async

List published layers belonging to a connection.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
service_name str | None

When provided, restrict to one service's layers.

 None

Returns:

Name Type Description
Matching list[PublishedLayerSummary]

class:PublishedLayerSummary objects; empty when
list[PublishedLayerSummary]

the server returns a non-list payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

publish_layer(conn_id, request, *, idempotency_key=None, timeout=None, extra_headers=None) async

Publish a new layer derived from a stored connection.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
request PublishLayerRequest

Layer-publication payload.

 required
idempotency_key str | None

Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side.

 None

Returns:

Name Type Description
A PublishedLayerSummary

class:PublishedLayerSummary describing the new layer.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the publish request.
HonuaTransportError

The request failed at the transport layer.

set_layer_enabled(conn_id, layer_id, enabled, service_name=None, *, timeout=None, extra_headers=None, idempotency_key=None) async

Toggle whether a single published layer is enabled.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
layer_id int

Numeric layer identifier.

 required
enabled bool

Desired enabled state.

 required
service_name str | None

Optional service-scoped toggle.

 None

Returns:

Type Description
PublishedLayerSummary

The refreshed :class:PublishedLayerSummary.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the toggle.
HonuaTransportError

The request failed at the transport layer.

set_service_layers_enabled(conn_id, enabled, service_name=None, *, timeout=None, extra_headers=None, idempotency_key=None) async

Toggle every layer on a connection (optionally per service) in bulk.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required
enabled bool

Desired enabled state for every layer in scope.

 required
service_name str | None

Optional per-service restriction.

 None

Returns:

Name Type Description
Refreshed list[PublishedLayerSummary]

class:PublishedLayerSummary objects for every
list[PublishedLayerSummary]

affected layer; empty when the server returns a non-list
list[PublishedLayerSummary]

payload.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the bulk toggle.
HonuaTransportError

The request failed at the transport layer.

discover_tables(conn_id, *, timeout=None, extra_headers=None) async

Ask the server which tables are visible through a connection.

Parameters:

Name Type Description Default
conn_id str

Connection identifier; URL-encoded.

 required

Returns:

Name Type Description
A TableDiscoveryResponse

class:TableDiscoveryResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

list_styles(*, timeout=None, extra_headers=None) async

List the styles published over OGC API - Styles (GET /ogc/styles).

Returns:

Name Type Description
An OgcStylesList

class:OgcStylesList of styleId-keyed entries plus the
OgcStylesList

optional default style and landing links.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

get_stylesheet(style_id, *, encoding=_DEFAULT_STYLE_ENCODING, timeout=None, extra_headers=None) async

Fetch a stylesheet by style_id (GET /ogc/styles/{styleId}).

The encoding is selected by Accept content negotiation: mapbox-style (MapLibre/Mapbox JSON, the default), sld-1.0, or sld-1.1 (derived on demand by the server).

Parameters:

Name Type Description Default
style_id str

Stable style identifier.

 required
encoding StyleEncoding

Desired stylesheet encoding (see :data:StyleEncoding).

 DEFAULT_STYLE_ENCODING

Returns:

Name Type Description
An OgcStylesheet

class:OgcStylesheet carrying the raw content and the
OgcStylesheet

media_type the server returned.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status (e.g. 404 unknown style, 406 unsupported encoding).
HonuaTransportError

The request failed at the transport layer.

get_style_metadata(style_id, *, timeout=None, extra_headers=None) async

Fetch style metadata (GET /ogc/styles/{styleId}/metadata).

Parameters:

Name Type Description Default
style_id str

Stable style identifier.

 required

Returns:

Name Type Description
An OgcStyleMetadata

class:OgcStyleMetadata describing the style.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_style(style_id, style, *, strict=False, timeout=None, extra_headers=None, idempotency_key=None) async

Replace an existing style's MapLibre stylesheet (PUT /ogc/styles/{styleId}).

Phase 1 manage-styles accepts only a MapLibre/Mapbox style document; the server validates and stores it against the existing style. Standalone style creation/deletion is not yet supported.

Parameters:

Name Type Description Default
style_id str

Stable style identifier (must already exist).

 required
style Mapping[str, Any]

The MapLibre/Mapbox stylesheet document.

 required
strict bool

When True, request strict validation via Prefer: handling=strict.

 False

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the update (e.g. 400 invalid style, 404 unknown style, 415 unsupported media type).
HonuaTransportError

The request failed at the transport layer.

get_layer_style(layer_id, *, timeout=None, extra_headers=None) async

Fetch the stored renderer / style document for a layer.

.. deprecated:: This layerId-keyed path is a back-compat alias (ADR-0048). Prefer the styleId-keyed :meth:get_stylesheet / :meth:get_style_metadata over OGC API - Styles.

Parameters:

Name Type Description Default
layer_id int

Numeric layer identifier.

 required

Returns:

Name Type Description
A LayerStyleResponse

class:LayerStyleResponse.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.

update_layer_style(layer_id, request, *, timeout=None, extra_headers=None, idempotency_key=None) async

Replace the stored renderer / style document for a layer.

.. deprecated:: This layerId-keyed path is a back-compat alias (ADR-0048). Prefer the styleId-keyed :meth:update_style over OGC API - Styles.

Parameters:

Name Type Description Default
layer_id int

Numeric layer identifier.

 required
request LayerStyleUpdateRequest

The new renderer payload.

 required

Returns:

Type Description
LayerStyleResponse

A refreshed :class:LayerStyleResponse.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server rejected the style update.
HonuaTransportError

The request failed at the transport layer.

get_config(*, timeout=None, extra_headers=None) async

Return the server's effective admin configuration block.

Returns:

Type Description
dict[str, Any]

The server-side admin config as a plain dict; an empty
dict[str, Any]

dict when the server returns a non-mapping payload.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type Description
HonuaHttpError

The server responded with a non-success status.
HonuaTransportError

The request failed at the transport layer.