StellMap Python SDK

StellMap Python SDK is a Python client for stellmap-service, the Stell service registry and discovery runtime. It provides service registration, deregistration, heartbeat renewal, instance discovery, metadata access, and SSE-based watch primitives for Python microservices, gateways, control-plane tools, and automation workloads.

The SDK follows the same public contract used by stellmap-java-sdk and stellmap-go-sdk: regular registry operations use HTTP JSON APIs, while service-instance changes are consumed through Server-Sent Events.

Capabilities

• Register service instances with endpoints, labels, metadata, and lease TTL.
• Deregister instances during graceful shutdown.
• Send heartbeat renewals for active registrations.
• Query service instances by namespace, service, structured service identity, zone, endpoint, labels, and selectors.
• Consume StellMap registry watch events through SSE.
• Follow not_leader responses when the server returns a leader address.
• Keep the core SDK framework-neutral for Flask, FastAPI, Django, gateways, schedulers, and internal platform tooling.

Install

pip install stellmap-python-sdk

For local development:

pip install -e ".[dev]"

Quick Start

from stellmap import Endpoint, RegisterRequest, StellMapClient

client = StellMapClient("http://127.0.0.1:8080")

client.register(
    RegisterRequest(
        namespace="default",
        service="company.trade.order.order-center.api",
        instance_id="order-center-api-10.0.1.23",
        endpoints=[
            Endpoint(protocol="http", host="10.0.1.23", port=8080),
        ],
        labels={"runtime": "python"},
        metadata={"framework": "fastapi"},
    )
)

instances = client.query_instances(
    namespace="default",
    service="company.trade.order.order-center.api",
)
print(instances)

Watch

from stellmap import StellMapClient, WatchOptions

client = StellMapClient("http://127.0.0.1:8080")

for event in client.watch_instances(
    WatchOptions(
        namespace="default",
        service_prefix="company.trade.order",
        include_snapshot=True,
    )
):
    print(event.revision, event.type, event.service)

Public API

API	Description
StellMapClient.register(...)	Register an instance.
StellMapClient.deregister(...)	Deregister an instance.
StellMapClient.heartbeat(...)	Renew an instance lease.
StellMapClient.query_instances(...)	Query instance snapshots.
StellMapClient.watch_instances(...)	Stream registry watch events through SSE.
compose_service_name(...)	Build the five-part Stell service name.
parse_service_name(...)	Parse a five-part Stell service name.

Protocol

The SDK targets the existing StellMap registry API:

Method	Path	Description
POST	/api/v1/registry/register	Register a service instance.
POST	/api/v1/registry/deregister	Deregister a service instance.
POST	/api/v1/registry/heartbeat	Renew a service instance lease.
GET	/api/v1/registry/instances	Query service instances.
GET	/api/v1/registry/watch	Subscribe to registry changes through SSE.

Development

python -m pytest
python -m build

Project Status

This repository starts as a minimal but usable Python SDK baseline. Future work can add async clients, framework integrations, richer local directory caches, metrics hooks, and packaging automation without changing the core service-registry contract.