xy-health-measurement-sdk-configuration 1.0.5

小阳心健康测量SDK配置

xy-health-measurement-sdk-configuration

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

环境要求

• Python 3.8 – 3.11
• protobuf 3.19.6

安装

pip install xy_health_measurement_sdk_configuration

快速上手

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	性别枚举

开发

初始化环境

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

单元测试

安装测试依赖：

pip install -e ".[dev]"

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

pytest -m "not integration"

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

pytest -m integration

运行全部测试：

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）中运行和查看测试结果，无需额外配置。

构建发布

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

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

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