Metadata-Version: 2.4
Name: xy_health_measurement_sdk_configuration
Version: 1.0.4
Summary: 小阳心健康测量SDK配置
Author-email: Colin Chang <zhangcheng@xymind.cn>
License: MIT
Keywords: 健康测量,生理测量,情绪测量,健康风险,小阳科技
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: <3.12,>=3.8
Description-Content-Type: text/markdown
Requires-Dist: protobuf==3.19.6

# xy-health-measurement-sdk-configuration

小阳心健康测量 SDK 共享配置包，提供服务端点、测量参数、验证规则及 Protobuf 数据类型。

## 环境要求

- Python 3.8 – 3.11
- protobuf 3.19.6

## 安装

```bash
pip install xy_health_measurement_sdk_configuration
```

## 快速上手

```python
from xy_health_measurement_sdk_configuration import ConfigUtility, Validation

# 读取全局配置
auth_url = ConfigUtility.get_config("auth_url")
min_duration = ConfigUtility.get_config("min_measurement_duration")  # 毫秒

# 读取某个验证码对应的规则配置
fps_rule = ConfigUtility.get_validation(Validation.TooLowFps)
# {'min_fps': 12, 'exception': {'level': 'error', 'msg': '...', 'msg_cn': '...', 'code': 3007}}

# 构造并抛出结构化错误
ConfigUtility.generate_error(
    code=Validation.AuthenticationFailure,
    message="app_id=xxx sdk_key=yyy",
    exception=original_ex,
)

# 构造但不抛出，返回 ValueError 对象
err = ConfigUtility.generate_error(
    config=fps_rule["exception"],
    raising=False,
)

# 解析错误等级
try:
    ...
except Exception as e:
    is_fatal, exc_config, addition = ConfigUtility.validate_error(e)
    # is_fatal: bool — level == "error" 时为 True
    # exc_config: {'level': ..., 'msg': ..., 'msg_cn': ..., 'code': ...}
    # addition: {'message': ..., 'exception': ...}
```

## API 参考

### `ConfigUtility`

| 方法 | 说明 |
|------|------|
| `get_config(key)` | 按键名读取全局配置值 |
| `get_validation(code)` | 返回指定 `Validation` 枚举值对应的规则配置（深拷贝） |
| `generate_error(code, raising, **kwargs)` | 构造结构化 `ValueError`；`raising=True`（默认）时直接抛出 |
| `validate_error(error)` | 解析结构化错误，返回 `(is_fatal, exc_config, addition)` |

### 全局配置键（`get_config`）

| 键 | 类型 | 说明 |
|----|------|------|
| `auth_url` | `str` | 鉴权服务地址 |
| `measurement_url` | `str` | 测量特征上报地址 |
| `min_measurement_duration` | `int` | 最短测量时长（毫秒） |
| `max_measurement_duration` | `int` | 最长测量时长（毫秒） |
| `min_chunk_timespan` | `int` | 最小数据块时间跨度（毫秒） |
| `chunk_frame_span` | `int` | 每个数据块的帧数 |
| `min_frames_cnt` | `int` | 最少帧数要求 |

### Protobuf 类型

| 类型 | 说明 |
|------|------|
| `Validation` | 错误/验证码枚举（3001–3018） |
| `MeasurementCategory` | 测量类别枚举（心率、血压、情绪等） |
| `Chunk` / `Feature` / `DoubleArray` | 测量数据块结构 |
| `Report` 及子类型 | 健康报告结构 |
| `Gender` | 性别枚举 |

## 开发

### 初始化环境

```bash
conda create -n measurement_sdk_configuration -y python=3.10
conda activate measurement_sdk_configuration
pip install build twine
pip install protobuf==3.19.6
```

### 构建

```bash
rm -rf dist *.egg-info
python -m build
```

### 发布

```bash
# 发布到阿里云私有 PyPI
twine upload -r packages-pypi dist/*

# 发布到公共 PyPI
twine upload dist/*
```

