Python typing项目：类型存根文件编写规范统一化探讨

在Python生态系统中，类型注解已成为提升代码质量的重要工具。作为类型系统的核心基础设施，typeshed仓库和官方typing文档都包含了关于编写类型存根文件(stubs)的规范指南。然而，这两个来源的指导原则存在部分重复和差异，引发了社区关于规范统一化的讨论。

背景与现状

类型存根文件(.pyi)是包含类型注解但不包含实现代码的特殊文件，它们为Python模块提供静态类型信息。目前存在两套指导原则：

1. typeshed仓库的CONTRIBUTING.md文件包含详细的存根编写规范
2. 官方typing文档中的"Writing and Maintaining Stubs"章节

历史原因导致这两套规范存在重复内容。实际上，官方文档的部分内容最初就是从typeshed移植而来，但由于规范演进过程中的时间差，未能及时完成内容整合。

关键差异点分析

文档与实现不一致的处理

当模块的实际实现与其文档描述存在分歧时，两个规范给出了不同建议：

• typeshed建议优先遵循实现行为
• 官方文档建议开发者根据上下文判断设计意图

经过社区讨论，更倾向于采用官方文档的灵活方案，因为这更能适应复杂场景下的类型标注需求。

文档字符串的处理

关于是否在存根文件中保留文档字符串(docstrings)，存在明显分歧：

• typeshed为保持简洁性建议移除
• Pyright等类型检查器则推荐保留以增强IDE体验

技术专家建议权衡以下因素：

1. 维护成本：文档字符串的同步问题
2. 开发体验：IDE中的代码提示功能
3. 技术限制：类型检查器会忽略这些字符串

规范整合方向

社区已达成以下共识：

1. 将通用性规范统一到官方typing文档
2. typeshed仅保留仓库特定的指导原则
3. 需要迁移的内容包括：
   • 不完整注解处理方案
   • Any与Incomplete的类型区别
   • "Any技巧"等高级模式

技术决策建议

对于存根文件编写者，建议遵循以下最佳实践：

1. 优先参考官方typing文档的通用规范
2. 针对typeshed贡献时，补充参考仓库特定的要求
3. 处理文档与实现分歧时，综合考虑上下文和设计意图
4. 文档字符串的取舍应根据具体项目需求决定

这一整合工作将提升Python类型系统的文档一致性，降低开发者的学习成本，同时保持各项目的技术自主性。随着类型系统在Python生态中的重要性不断提升，规范的统一化和明确化将有助于推动类型注解的广泛应用。