Metadata-Version: 2.4
Name: py-agile-config
Version: 0.4.1
Summary: Python client SDK for AgileConfig
Project-URL: Homepage, https://github.com/animacaeli/py-agile-config
Project-URL: Repository, https://github.com/animacaeli/py-agile-config
Project-URL: Issues, https://github.com/animacaeli/py-agile-config/issues
Author: animacaeli
License-Expression: MIT
License-File: LICENSE
Keywords: agileconfig,configuration,sdk,service-discovery
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: requests>=2.32.0
Requires-Dist: websocket-client>=1.8.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# py-agile-config

面向 [AgileConfig](https://github.com/dotnetcore/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 客户端。

## 安装

```bash
pip install py-agile-config
```

## 快速开始

```python
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：

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

## 配置读取

```python
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 示例
代码。

## 配置变更回调

```python
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

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

## 服务发现

```python
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)
```

## 开发

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

## 发布到 PyPI

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

使用 PyPI API token 时设置：

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