修改大型 Python 数据系统，不破坏延迟执行

## 把需求的行为追溯到负责它的那一层 更改大型 Python 数据处理或并行计算代码库之前，应建立针对当前任务的结构图，而不是不加区分地阅读整个仓库。 确定涉及的层： 1. 公开集合或面向用户的接口。 2. 用于规划和优化的符号表达式或高层图。 3. 已具体化的底层任务和依赖边。 4. 调度器或执行后端。 5. 配置、分派、序列化和工具层。 从公开入口开始追踪所请求的行为，直到找到负责该行为的最小实现层。编辑前阅读相邻的测试和配置。 按照任务类型导航： - 调度行为：依次查看公开计算 API、图工具、任务表示和调度器适配器。 - 图优化：依次查看高层图协议、分块或表达式层，以及具体化过程。 - 数组或数据框功能：依次查看集合 API、操作实现、分派和聚焦测试。 - 配置变更：查看运行时访问器、默认配置、模式和文档。 - 后端支持：查看后端接口、入口点注册、分派和兼容性测试。 将仓库说明中的模块名称、行数和依赖版本视为导航提示，而不是永远不变的事实。在本地确认当前源代码和清单。 明确保持各子系统的边界。公开集合中的变更可能需要同步更新元数据、图、调度器、测试和文档，但不要编辑无关的层。 ## 使用代码库的环境，并选择最小的测试范围 使用仓库声明的环境管理器和命令。不要假定全局 Python 安装与受支持的依赖组合一致。 实现前： 1. 检查项目清单和可用环境。 2. 选择能够代表受影响功能的最小环境。 3. 找到距离目标最近的现有测试、夹具、标记和断言辅助函数。 4. 记录相关的可选依赖、功能开关和警告策略。 对于以下操作，优先使用仓库提供的命令包装器： - 单个失败测试； - 受影响模块的测试文件； - 代码检查和静态检查； - 公开示例的文档测试； - 最低依赖或可选功能环境； - 只有在变更确有需要时，才运行范围更广且等同于持续集成的检查。 遵守严格的测试行为，例如将警告视为错误、严格的预期失败、超时和环境特定标记。对于延迟集合，如果共享相等性辅助函数能够考虑元数据、类型、分区或数值容差，就应使用这些辅助函数。 对于可选依赖，应使用项目规定的导入和跳过辅助函数，而不是临时编写条件分支。使用新 API 时，应同时考虑最低支持版本和最新支持版本。 除非任务明确授权，否则不要安装包、更改环境或启用依赖网络的测试。将缺少依赖报告为环境限制，不要悄然更改计算机。 ## 构建图时不调用`compute()`，保持延迟执行 维护延迟图系统的核心不变量：图构建代码必须描述计算，而不能执行计算。 定义集合操作、图层或符号表达式时，绝不能调用 `compute()` 或 `persist()` 等立即具体化的方法。具体化只能发生在明确的用户边界或执行边界。 构建图时： - 尽可能从元数据推断输出； - 保持任务依赖关系明确且确定； - 维持稳定的键和标记化行为； - 避免隐藏的输入输出或调度器选择； - 保持符号优化与底层执行相互分离。 遵循仓库约定： - 为新代码添加完整的类型提示； - 保持兼容性导入和延迟注解一致； - 使用受保护的仅类型导入来避免循环； - 按照可预测的顺序组织标准库、第三方和本地导入； - 为公开 API 使用规定的文档字符串样式和可运行示例； - 对私有辅助函数、测试和分派函数采用既有命名方式。 添加后端、表达式、层或配置选项时，应更新每个必要的注册点，并添加聚焦测试，证明分派或规划过程能够到达新实现。 影响导入时注册或查询规划的功能开关，必须在相关模块首次导入前设置。如果启用和禁用两种行为仍受支持，就要测试这两种行为。 修复范围明确的缺陷时，应避免大范围重构。保留无关行为，并只进行能够解释新测试结果的最小变更。 ## 逐步扩大测试范围，未经许可不发布 逐步扩大验证范围： 1. 使用聚焦测试重现之前的失败。 2. 运行距离目标最近的测试文件或子系统测试套件。 3. 运行受本次编辑直接影响的代码检查、类型检查或文档测试。 4. 实际运行相关的可选功能、最低依赖或功能开关变体。 5. 只有当变更跨越较大的架构边界时，才使用完整测试套件。 检查常见失败模式： - 导入循环和注册顺序； - 首次导入后才更改的功能开关； - 与计算结果不一致的元数据； - 在部分解释器中不可用的可选包； - 相关包之间不一致的依赖版本锁定； - 模式定义中缺少的配置默认值； - 无法继续运行的文档测试示例； - 只在某一个调度器或后端中通过的测试。 报告完成前，应审查变更差异，并说明实际运行了哪些检查、哪些检查通过以及哪些检查未运行。不要仅凭查看代码推断成功。 发布工作属于独立的权限边界。除非获得明确授权，否则绝不能创建发布、发布包、推送标签、上传产物或修改外部发布系统。 如果已获准进行发布准备，应在更改任何外部状态前，验证变更日志条目、版本和跨包固定版本、打包产物以及仓库文档规定的步骤。 当被要求与他人沟通时，应提供证据和选项，不要冒充用户，也不要编造用户的决定。