modernize-scientific-stack

现代化科学计算技术栈

本技能为将旧版 Python 2 科学计算代码迁移到采用现代库和最佳实践的现代 Python 3 提供指导。

何时使用此技能

适用于以下情形：

• 将 Python 2 科学计算脚本迁移到 Python 3
• 更新使用过时模式的旧版数据处理代码
• 现代化使用已弃用的文件处理、字符串编码或数值库的脚本
• 将脚本从 csv 模块转换为 pandas，以进行数据分析
• 在路径操作中用 pathlib 替换 os.path

方法

阶段 1：完整发现代码

进行任何更改之前，确保充分了解现有代码库：

1. 完整读取所有源文件 —— 如果文件读取内容被截断，请先请求完整内容再继续。切勿根据不完整的读取结果猜测文件内容。

2. 识别所有依赖项 —— 检查以下内容：

   • 导入语句（标准库和第三方库）
   • 配置文件（JSON、YAML、INI）
   • 数据文件（CSV、Excel、pickle）
   • 环境要求

3. 梳理数据流 —— 了解以下内容：

   • 输入文件格式和编码
   • 应用的数据转换
   • 输出格式要求
   • 任何中间文件或缓存

阶段 2：确定迁移要求

科学计算代码从 Python 2 迁移到 Python 3 时的常见模式：

旧版模式	现代替代方案
print "text"	print("text")
unicode() / str()	使用显式编码的 str()
open(file)	open(file, encoding='utf-8')
os.path.join()	pathlib.Path()
csv 模块	pandas.read_csv()
for key in dict.keys()	for key in dict
dict.has_key(x)	x in dict
手动遍历文件	上下文管理器（with 语句）
xrange()	range()
整数除法 /	显式使用 // 或浮点除法

阶段 3：实施策略

1. 创建现代化脚本，并优先考虑以下事项：

   • 所有文件操作均使用 UTF-8 编码
   • 所有文件路径操作均使用 pathlib.Path
   • 使用 pandas 处理 CSV／数据
   • 在适用时添加类型提示
   • 使用上下文管理器处理资源

2. 处理配置文件 —— 读取前检查文件是否存在：

   config_path = Path("config.json")
   if config_path.exists():
       config = json.loads(config_path.read_text(encoding='utf-8'))
   

3. 创建 requirements.txt —— 添加所有依赖项及版本约束

阶段 4：验证流程

关键：务必验证文件操作

写入任何文件后，都要重新读取并确认：

• 内容已完整写入（未被截断）
• 语法有效
• 包含所有导入项

测试顺序：

1. 语法验证 —— 运行 Python 语法检查：

   python -m py_compile script.py
   

2. 导入验证 —— 测试所有导入项均可正常解析：

   python -c "from script import *"
   

3. 功能测试 —— 运行脚本，并将输出与预期结果进行比较

4. 输出验证 —— 确认输出格式与要求完全一致

应避免的常见问题

1. 文件内容被截断 —— 切勿在文件读取不完整时继续操作。如果响应中出现 ... [truncated] 或内容不完整，请在继续之前请求完整文件。

2. 未验证写入结果 —— 使用写入操作后，务必重新读取文件，确认内容已正确完整写入。

3. 编码问题 —— 文件操作时务必显式指定 encoding='utf-8'。旧版脚本通常默认采用 ASCII 编码。

4. 路径字符串拼接 —— 使用 pathlib.Path 操作替换所有 os.path.join() 和路径字符串拼接。

5. 未处理的边缘情况：

   • 空数据文件或数据集
   • 缺少必需文件
   • CSV 列中的数据类型无效
   • 没有匹配数据的站点／实体

6. 重复设置环境 —— 设置环境（venv、PATH）时，确认设置能够持续生效，而不是在每条命令中重复设置。

验证清单

标记任务完成前，请确认：

• 已完整读取所有源文件（没有截断）
• 已通过回读验证写入的文件
• 已转换所有 Python 2 模式
• 已明确指定文件编码
• 所有路径操作均使用 pathlib
• 使用 pandas 进行数据处理（适用时）
• requirements.txt 包含所有依赖项
• 脚本运行无错误
• 输出与预期格式完全一致
• 已处理边缘情况（空数据、缺失文件）

输出验证

如果任务指定了预期输出格式，请验证输出完全匹配：

1. 运行现代化后的脚本
2. 捕获输出
3. 必要时逐字符对比预期格式
4. 注意以下方面：
   • 数值输出的小数精度
   • 空白字符和格式
   • 输出项的顺序
   • 单位和标签