py-agile-config 0.1.0

Python client SDK for AgileConfig

py-agile-config

Python client SDK for AgileConfig.

This package is the Python migration of github.com/animacaeli/go-agile-config. It keeps the Go SDK's behavior aligned where it matters:

• Fetch published configs via HTTP Basic Auth.
• Receive real-time updates through WebSocket.
• Store config keys as group:key when group is present, otherwise key.
• Require HTTPS/WSS by default, with explicit opt-in for trusted HTTP.
• Limit HTTP response bodies and WebSocket message size.
• Provide service discovery APIs and multi-app client support.

Installation

pip install py-agile-config

Quick Start

from agileconfig import Client, Options

client = Client(
    "https://config.example.com",
    "my-app-id",
    "my-app-secret",
    Options(env="DEV"),
)

client.start()
try:
    host = client.get_string("db.host", "localhost")
    print("DB Host:", host)
finally:
    client.stop()

For local development or private test networks:

client = Client(
    "http://localhost:5000",
    "my-app-id",
    "my-app-secret",
    Options(allow_insecure_http=True),
)

Config APIs

value, ok = client.get("db:host")
host = client.get_string("db.host", "localhost")
value, ok = client.get_by_group("database", "host")
all_configs = client.get_all()

The SDK also exposes Go-style compatibility aliases such as client.GetString(...) for users porting snippets from the Go SDK.

Change Callback

def on_change(keys: list[str]) -> None:
    for key in keys:
        print("changed:", key)

client = Client(
    server_url,
    app_id,
    secret,
    Options(on_change=on_change),
)

The callback receives keys that were added, removed, or modified. Initial load also triggers the callback when configs are present, matching the Go SDK.

Multi App IDs

from agileconfig import MultiClient, MultiClientApp, Options

client = MultiClient(
    server_url,
    [
        MultiClientApp("mysql", "mysql-secret"),
        MultiClientApp("redis", "redis-secret"),
    ],
    Options(env="DEV"),
    on_change=lambda app_id, keys: print(app_id, keys),
)

client.start()
try:
    mysql_host, ok = client.get_by_group("mysql", "db", "host")
    redis_addr = client.get_string("redis", "addr", "localhost:6379")
finally:
    client.stop()

Service Discovery

from agileconfig import HeartbeatMode, RegisterService

services = client.list_services()
online = client.list_online_services()
offline = client.list_offline_services()

result = client.register_service(
    RegisterService(
        service_id="order-service",
        service_name="Order Service",
        ip="10.0.0.8",
        port=8080,
        metadata=["version=1.0.0"],
        heartbeat_mode=HeartbeatMode.CLIENT,
    )
)

client.heartbeat(result.unique_id)
client.unregister_service(result.unique_id)

Development

python3.13 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/python -m pytest -q

Publishing

.venv/bin/python -m pip install build twine
.venv/bin/python -m build
.venv/bin/python -m twine upload dist/*

Set TWINE_USERNAME=__token__ and TWINE_PASSWORD=<pypi-token> when using a PyPI API token.