VeighNa框架的易盛启明星V10 API 封装

说明

vnpy_esunny10 是 VeighNa 框架的易盛启明星 V10 底层接口封装 （API-only Python binding），只导出底层 C++/pybind11 封装，不包含任何 gateway。

本项目不发布到 PyPI，仅供学习和接口研究使用，通过源码安装。

使用前请先明确：

• 这不是官方绑定，仅供学习和接口研究，不应直接用于生产环境。
• 仓库只提供 VeighNa 框架使用的底层接口封装，不提供 gateway。
• 当前只支持 Linux x86_64，不提供 Windows 动态库。

当前仓库对应的官方 SDK 版本为：

• 交易 API：1.0.1.19
• 行情 API：1.0.0.7

与 vnpy_ctp 等官方接口封装的设计差异

本项目没有刻意追求和 vnpy_ctp 保持同一套绑定层实现风格，而是更偏向 “强类型 + 显式字节语义”。这些差异是有意为之，主要目的是减少 C++ 层的 生命周期管理和编码假设风险，把字符串解释权留给 Python 业务层。

• 回调任务队列使用 enum class + TaskPayload = std::variant<...> 保存已经拷贝的具体 POD/字符串值，而不是 vnpy_ctp 常见的 Task { void* task_data, void* task_error } 裸指针模型。
• 这样做的重点不是“语法更新”，而是用值语义替代 new/delete、强制类型转换和手工释放，让回调转发链路更安全、更直接。
• 本项目不在 C++ binding 层做 Unicode decoding，不假设柜台返回值一定应该先被转成 Python str。
• 接口字段遵循显式映射：char -> Python int，char[]/const char* -> Python bytes；请求入参也保持同样规则，由 Python 业务层自行决定何时、按什么编码 .decode(...)。
• 这和 vnpy_ctp 常见的 C++ 层 toUtf()/string 路线不同。这里刻意不把编码策略写死在 binding 层，目的是在面对不同柜台、不同部署环境时更保险。

如果你已经习惯 vnpy_ctp 的接口风格，需要额外注意：

• 回调里看到的账号、合约、时间戳、路径、地址等文本字段，很多会是 bytes，需要在 Python 业务层自行 .decode(...)。
• 单字符枚举或标志位字段通常是整数，而不是长度为 1 的字符串。
• 输入侧同样如此，例如地址、路径、合约号等参数应传 bytes，而不是默认传 str。

示例：

api.setHostAddress(b"10.0.0.1", 12345)
api.subscribe(b"SHFE|cu2505")

contract: bytes = data["ContractNo"]
contract_text = contract.decode("utf-8", errors="ignore")

direct: int = data["Direct"]

安装

获取源码：

git clone https://github.com/lostleaf/vnpy_esunny10_api.git
cd vnpy_esunny10_api

构建需要 Python ≥ 3.10 和 uv 包管理器。 从仓库根目录执行：

uv sync
uv run python setup.py build_ext --inplace

构建完成后会在 vnpy_esunny10/api/ 下生成编译后的 .so 扩展模块，测试是否成功：

uv run python -c "from vnpy_esunny10 import MdApi, TdApi; print(MdApi, TdApi, MdApi.getApiVersion())"

如果一切正常，输出类似：

<class 'vnpy_esunny10.api.vnesunny10md.MdApi'> <class 'vnpy_esunny10.api.vnesunny10td.TdApi'> b'Version:V1.0.0.7-20240410'

目录约定

• vnpy_esunny10/api/include/：官方头文件
• vnpy_esunny10/api/libdstar*.so：官方 Linux 动态运行库
• vnpy_esunny10/api/vnesunny10/：生成后的 pybind11 源码
• script/：最小示例脚本和配置模板

Demo

• script/md_login_demo.py 自包含脚本，读取 script/md_demo_config.json 里的行情接入参数，不需要账号。
• script/td_login_demo.py 读取 script/td_demo_config.json，导入兜底逻辑由共享 helper td_demo_helpers.py 提供。账号和密码默认是占位值，运行前必须自行填写。
• script/td_first_change_pwd.py 首次登录改密码示例，同样依赖 td_demo_helpers.py，读取 script/td_demo_config.json 中的旧密码，新密码通过命令行 --new-password 传入。

常用运行方式：

uv run python script/md_login_demo.py --config script/md_demo_config.json
uv run python script/td_login_demo.py --config script/td_demo_config.json
uv run python script/td_first_change_pwd.py --config script/td_demo_config.json --new-password YOUR_NEW_PASSWORD

script/td_demo_config.json 中的 password 表示当前登录密码：

• 对 script/td_login_demo.py，它就是正常登录使用的密码。
• 对 script/td_first_change_pwd.py，它是首次登录时的旧密码，修改后的新密码由 --new-password 指定。

TD 示例默认仍链接正式库 libdstartradeapi.so。

如果要连接穿透式测试环境，需要先手工用libdstartradeapi_test.so 替换 vnpy_esunny10/api/ 下正在使用的libdstartradeapi.so。

附带资料

• 易盛启明星V10测试环境.txt 官方测试环境接入参数原文副本。
• 易盛启明星V10交易API使用说明.md 官方交易 API 使用说明。

更多项目开发约定见 AGENTS.md。

License

本项目基于 MIT 协议开源。