PyPI API Drift: A Release-Level Record of Public API Changes in 1,872 Popular Python Libraries, with a Checker and a Benchmark for Version-Aware Code Generation

在现代软件不断变化的广阔景观中，Python 已成为一种主导语言，为从科学研究到 Web 应用程序的一切领域提供动力。它的优势在于拥有庞大的预构建工具生态系统，即所谓的“库”（libraries），开发者可以将这些工具插入到自己的项目中，从而无需重复造轮子即可处理复杂的任务。然而，这些工具并非静止的纪念碑；它们是不断进化的生命体。开发者经常通过更新它们来修复漏洞、提高速度或添加新功能。在这一过程中，他们有时会悄悄地移除或更改用户所依赖的特定命令和指令。对于人类程序员来说，追踪这些变化是一个可以应对的挑战，通常可以通过阅读发行说明（release notes）或询问同事来解决。但对于新一代编写代码的人工智能助手而言，这种演变呈现出了一个独特且持久的问题。这些 AI 模型是在来自许多不同时代的庞大代码档案上训练出来的，它们学习编写在几年前仍然正确的指令，但现在可能已经失效。由于缺乏了解用户安装了哪个具体版本的工具的方法，AI 可能会自信地建议一个已不存在的命令，从而导致项目停滞并产生错误。

为了解决这个问题，研究员 Pushkar Devanahalli Gopalakrishna 创建了一个关于这些工具如何随时间变化的庞大且详细的记录。这个名为 PyPI API Drift 的项目，充当了 1,872 个最受欢迎 Python 库的历史档案馆。该研究员并没有尝试运行并测试每一个代码片段（因为这会极其缓慢且昂贵），而是开发了一种直接观察构成这些库的数字文件的方法。通过仅检查这些文件的必要部分，该系统可以绘制出每个库在每一次近期发布中究竟提供了哪些命令、函数和设置。这一过程涵盖了 2021 年至 2026 年底发布的超过 55,000 个特定软件版本。其结果是一个精确的账本，追踪了特定功能何时被添加、何时被重命名以及何时被完全移除。至关重要的是，该系统能够区分哪些是真正消失了的东西，哪些仅仅是移动或更名了，并为每个条目标注了置信水平，以指示记录的确定程度。

这种变化的规模是显著的。分析显示，大约 13.4% 的次要软件更新（通常被认为是非常安全且向后兼容的）实际上包含至少一个会导致现有代码失效的变化。更令人震惊的是，约 64% 的主要版本跳跃和近 30% 的次要版本更新包含了会导致旧代码失败的变化。这些数据挑战了“软件更新遵循严格且可预测的安全模式”这一普遍假设。研究人员发现，只有极小部分的移除功能被正式标记为“弃用”（deprecated）或“即将移除”（coming soon to be removed），且是以自动化工具能够轻松识别的方式进行标记。通常，这些警告隐藏在文本文档或条件消息中，计算机程序无法读取，使得开发者和 AI 助手在代码崩溃之前处于信息真空状态。

为了证明这一记录的实用性，研究人员构建了一套工具来测试其准确性和效用。其中一个工具作为检查器，扫描代码以查看其是否使用了对特定软件版本而言不再有效的命令。另一个工具则作为 AI 助手的查询系统，允许它们在编写代码前查询命令的历史记录。最重要的是，一系列实验测试了为 AI 提供这一历史记录是否真的有助于它编写更好的代码。在 AI 需要修复因软件更新而损坏的代码的测试中，如果能够查阅这一记录，AI 的表现明显更好。在没有帮助的情况下，AI 成功修复代码的概率不足一半；而在获得历史记录的帮助下，其成功率跃升至接近 70%，甚至超越了在获得新软件版本官方文档时的表现。这表明，拥有精确的、针对特定版本的变更历史，比阅读通用的说明文档对 AI 更有价值。

该项目还产出了一个基准测试（benchmark），即一个包含数千个代码片段的标准测试集，以帮助其他研究人员衡量其自身的 AI 模型在处理这些版本变化时的表现。研究结果证实，虽然 AI 模型功能强大，但除非配备可靠且最新的“存在与消失”地图，否则它们难以应对软件演进的快速节奏。记录显示，Python 库的景观比此前理解的更加流动，即使在微小的更新中也会频繁出现破坏性变更。通过提供一张清晰、高精度的变化地图，这项工作为构建能够驾驭不断演变的软件世界而不至于迷失方向的更智能的编码助手奠定了基础。这些数据现已向公众开放，确保社区能够继续构建足以跟上数字世界持续运动步伐的工具。