13 Python 骨架¶
目的¶
本章定义该开源参考框架的 Python 骨架。
核心要求¶
Python 实现必须与 canonical 架构保持一致，并在核心层保持模块化、强类型、可测试、后端无关。
结构原则¶
参考 Python 实现是一个面向一致性验证的骨架，而不是完整的生产级运行时。它的目标是让规范具备可执行性、可测试性与可扩展性，同时不破坏既定的分层边界。
canonical 包必须承载 UQCI 程序语义、sidecar 工件、校验逻辑以及兼容导出逻辑。后端专有的编译与执行细节必须保留在 canonical 包之外。
Canonical 包布局¶
在当前仓库中，canonical 包位于 src/qos_uqci/。其顶层模块已经体现出预期的职责划分：
ir.py：canonical 程序容器及相关 orchestration-facing 类型ops.py：GateOp、PulseOp、MeasureOp、SweepOp等操作对象devicespec.py：设备能力与约束模型calset.py：校准集模型result.py：ExecutionPlan、RunResult、ValidationReport等结果与报告对象bundle.py：Bundle 读写、完整性检查与辅助校验driver.py：后端驱动抽象接口lowering.py：仓库原生 lowering 辅助与转换逻辑openqasm_bridge.py：OpenQASM 兼容导出桥errors.py：标准异常类型cli.py：轻量命令行入口__init__.py：对用户与示例暴露稳定包导出
具体文件名可以根据实现需要调整，但职责边界必须保持清晰。
模块职责边界¶
Python 骨架应明确区分以下模块类型：
- canonical 语义模块
- sidecar 工件模块
- 校验与 Bundle 处理模块
- compatibility export 模块
- 面向后端的抽象模块
- 面向用户的仓库工具模块，例如 CLI
这种区分虽以实现为导向，但也有助于在代码结构中清楚体现语义归属。
类型系统与校验¶
参考实现宜采用适合 JSON 交换与 Schema 生成的强类型建模方式。本仓库优先使用 Pydantic v2，原因包括：
- 便于显式字段校验
- 便于导出 JSON Schema
- 便于版本化演进
- 便于稳定序列化 Bundle 工件
所有对外可见模型都应提供完整类型标注。公共模型命名应尽量与规范章节保持一致，避免仓库实现与规范术语分叉。
面向执行的职责¶
从仓库实践看，canonical 包至少应支持以下主流程：
- 建模 canonical UQCI 程序与 sidecar
- 读取并验证 Bundle 工件
- 生成或检查 compatibility export
- 提供标准化的 backend planning 与 result abstraction
- 暴露轻量 CLI，用于验证、检查、导出和 demo 执行
这意味着 canonical 包既要在语义层保持后端无关，也要足够务实，以支撑可运行示例与测试。
Python 中的执行流程¶
最小端到端流程如下：
- 构造或加载 canonical
UQCIProgram。 - 从执行包中加载
Manifest、DeviceSpec与CalSet。 - 对 canonical 程序与 sidecar 进行校验。
- 将 canonical IR 降低到后端内部执行计划，或导出到 OpenQASM 兼容配置。
- 将执行计划提交给后端驱动。
- 返回标准
RunResult以及可选诊断信息。
在这一流程的任何阶段，都不要求 OpenQASM 成为唯一的内存表示。
与 Backend 的关系¶
Python 骨架有意在 canonical 边界处停下。后端实现位于 backends/ 下，负责消费 canonical 包，而不是重新定义它。
这样做可以支持：
- 多个后端家族共享同一个语义核心
- mock backend 与未来真实 backend 共享 driver 契约
- 仓库测试覆盖从 bundle 到 bridge 再到 backend 与 result 的主链路
测试与质量要求¶
Python 骨架应能直接配合仓库原生质量工具工作。一个符合本章精神的参考实现通常应支持：
- 面向类型模型与校验行为的单元测试
- 面向 Bundle 与导出流程的集成测试
- 面向 mock backend 的后端测试
- lint 与类型检查等静态质量检查
v0.1 中的 Python 骨架应刻意保持轻量。大型运行时子系统、分布式编排服务与生产部署问题不属于本章目标。