change_code/python_bindings/INTEGRATION_GUIDE.md

Python 项目集成指南

本指南说明如何将 F:/04.python/04.python/uf2touft3 项目与 Qt 应用程序集成。

两个方案对比

方案一：增强的 QProcess 方案 (推荐用于生产环境)

优点：

• 简单稳定，不易出错
• 进程隔离，不会影响主应用程序
• Python 依赖问题独立解决
• 调试方便

缺点：

• 进程间通信开销
• 无法直接共享内存

状态：已实现并集成 ✅

方案二：pybind11 嵌入方案 (高级选项)

优点：

• 更紧密的集成
• 可以直接调用 Python 函数
• 更好的性能

缺点：

• 配置复杂
• 需要 C++ 编译环境
• 调试困难
• Python 全局解释器锁 (GIL) 问题

状态：提供示例代码 ⚠️

使用方案一 (推荐)

1. 确保 Python 环境可用

确保系统已安装 Python 3.8+，并且可以在命令行中运行：

python --version

2. 确保 Python 项目完整

确保 F:/04.python/04.python/uf2touft3 目录包含所有必要文件：

• main.py
• processCombination.py
• config.ini
• 其他依赖的模块和配置文件

3. 使用 Qt 应用程序

直接运行编译好的 Uft30ChangeCode.exe，点击"开始转换"按钮即可调用 Python 代码。

构建方案二 (高级)

如果你想使用 pybind11 方案，按以下步骤：

1. 安装依赖

pip install pybind11

2. 创建构建目录

cd python_bindings/pybind11_binding
mkdir build
cd build

3. 配置 CMake

cmake .. -G "MinGW Makefiles"
# 或使用 Visual Studio
# cmake .. -G "Visual Studio 16 2019" -A x64

4. 编译

cmake --build . --config Release

5. 集成到 Qt 项目

在你的 Qt 代码中动态加载编译好的库。

Python 项目的依赖

确保你的 Python 项目所需的所有依赖都已安装：

pip install -r requirements.txt

(需要在 uf2touft3 项目中创建 requirements.txt)

故障排查

Python 无法启动

• 检查 Python 是否在 PATH 中
• 尝试设置完整的 Python 路径
• 检查是否有多个 Python 版本

模块导入错误

• 确保工作目录设置正确
• 检查所有依赖的模块是否都在 Python 路径中
• 检查 config.ini 中的路径配置是否正确

中文路径问题

• 确保所有路径使用 UTF-8 编码
• 避免在路径中使用特殊字符

自定义配置

如需修改 Python 脚本路径，可以编辑 mainwindow.cpp 中的配置：

QString scriptPath = "F:/04.python/04.python/uf2touft3/main.py";