Metadata-Version: 2.4
Name: unitpulse-discovery
Version: 0.1.0
Summary: Backend-agnostic service discovery and registration SDK
Author: UnitPulse
Author-email: xiaobao.jiang@tripalink.com
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: nacos
Requires-Dist: nacos-sdk-python>=2.0.0; extra == "nacos"
Provides-Extra: all
Requires-Dist: nacos-sdk-python>=2.0.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# unitpulse-discovery

Service registration and discovery SDK for Python microservices. Supports Nacos and Consul.

## Installation

```bash
# With Nacos support
pip install "./unitpulse-discovery[nacos]"

# With all backends
pip install "./unitpulse-discovery[all]"
```

## Usage

```python
from unitpulse_discovery import setup_discovery

setup_discovery(app, backend="nacos", **NACOS_CONFIG)
app.discovery.initialize()

client = app.discovery.get_client()
client.register(service_name="my-service", host="10.0.0.1", port=8080, ephemeral=True)
```

On shutdown:
```python
client.deregister("my-service", "10.0.0.1", 8080)
```

## Parameters

### `setup_discovery(app, backend, **config)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app` | Flask \| FastAPI | Yes | App instance |
| `backend` | str | Yes | `"nacos"` or `"consul"` |
| `**config` | | | Backend-specific config (see below) |

### Nacos Config

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `server_addresses` | str | — | Nacos server, e.g. `"nacos-server:8848"` |
| `namespace` | str | `"public"` | Nacos namespace ID |
| `username` | str | `None` | Auth username |
| `password` | str | `None` | Auth password |
| `group_name` | str | `"DEFAULT_GROUP"` | Service group |
| `timeout` | int | `5` | Request timeout (seconds) |
| `service_name` | str | `None` | Ignored by the backend; safe to include for config consolidation |

### `client.register(...)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `service_name` | str | — | Service name to register |
| `host` | str | — | Instance IP |
| `port` | int | — | Instance port |
| `metadata` | dict | `{}` | Extra metadata (e.g. `{"version": "1.0", "weight": 1}`) |
| `ephemeral` | bool | `True` | Temporary instance — requires heartbeat; auto-removed on crash |
| `heartbeat_interval` | int | `5` | Heartbeat interval in seconds (ephemeral only) |

## License

MIT
