py-agile-config 0.4.0

Python client SDK for AgileConfig

py-agile-config

面向 AgileConfig 的 Python 客户端 SDK。

本项目是 github.com/animacaeli/go-agile-config 的 Python 迁移版本，并在关键 行为上保持兼容：

• 通过 HTTP Basic Auth 拉取已发布配置。
• 通过 WebSocket 接收实时配置更新。
• 配置存在 group 时按 group:key 存储，否则按 key 存储。
• 默认要求 HTTPS/WSS，可信 HTTP/WS 需要显式开启。
• 限制 HTTP 响应体和 WebSocket 消息大小。
• 支持服务发现 API 和多 appId 客户端。

安装

pip install py-agile-config

快速开始

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()

本地开发或可信内网测试可以显式允许 HTTP：

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

配置读取

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()

SDK 也提供 client.GetString(...) 等 Go 风格兼容别名，便于迁移 Go SDK 示例 代码。

配置变更回调

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),
)

回调会收到新增、删除或修改的配置 key。初始加载时如果存在配置，也会触发回调， 以保持与 Go SDK 一致。

多 App ID

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()

服务发现

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)

开发

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

发布到 PyPI

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

使用 PyPI API token 时设置：

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<pypi-token>