Metadata-Version: 2.4
Name: py-agile-config
Version: 0.1.0
Summary: Python client SDK for AgileConfig
Project-URL: Homepage, https://github.com/animacaeli/go-agile-config
Project-URL: Repository, https://github.com/animacaeli/go-agile-config
Project-URL: Issues, https://github.com/animacaeli/go-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

Python client SDK for [AgileConfig](https://github.com/dotnetcore/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

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

## Quick Start

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

For local development or private test networks:

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

## Config APIs

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

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

## Change Callback

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

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

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

## Service Discovery

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

## Development

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

## Publishing

```bash
.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.
