Metadata-Version: 2.4
Name: xy_health_measurement_sdk_configuration
Version: 1.0.5
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
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# 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
pip install -e ".[dev]"
```

运行单元测试（无需网络，使用 mock 数据）：

```bash
pytest -m "not integration"
```

运行集成测试（访问真实云端配置，验证网络获取正常）：

```bash
pytest -m integration
```

运行全部测试：

```bash
pytest
```

测试说明：

| 文件 | 类型 | 覆盖范围 |
| --- | --- | --- |
| `tests/test_load_config.py` | 单元 | `_load_config()` 网络请求、URL 正确性、异常传播 |
| `tests/test_config_utility.py` | 单元 | `get_config`、`get_validation`（深拷贝隔离）、`generate_error`、`validate_error`、`_get_validation_args`（占位符展开） |
| `tests/test_integration.py` | 集成 | 访问真实 OSS 端点，验证返回结构完整、所有验证码存在、字段类型正确 |

VS Code 用户可直接在**测试面板**（`⇧⌘T` / `Ctrl+Shift+T`）中运行和查看测试结果，无需额外配置。

### 构建发布

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

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

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