发表机构
Universidade Federal de Minas Gerais; École de Technologie Supérieure（米纳斯吉拉斯联邦大学; 高等技术学院）
机构由 AI 辅助整理，请以论文原文为准。AI 中文总结
本研究通过分析1000个热门GitHub仓库，探究Python库与框架中类型提示的采用、维护等情况，发现其主要作为API契约，为相关工具开发提供了方向。
AI 中文摘要
背景：在Python中，类型提示允许开发者为变量和函数标注明确的类型信息，提升代码的清晰度与可靠性。尽管类型提示已广泛可用，但人们对其在库和框架中的采用与维护情况知之甚少。目标：我们研究Python库与框架中类型提示的采用、使用、维护及背后的原理。方法：我们分析了1000个热门GitHub仓库，识别其中的库和框架，提取它们的类型标注，检查标注覆盖率、标注的位置与来源、其在Git历史中的演变，以及开发者标注与Pyright推断类型之间的关系。结果：在分析的仓库中，91%的库至少使用过一次类型提示，不过采用情况并不一致。在系统使用类型提示的库中，维护者优先标注函数参数和返回类型，其中位数覆盖率分别为45.8%和35.9%，且主要使用内置类型（占73.0%）。当标注被修改时，往往会迁移到更具表达力的类型。即使Pyright能够推断出类型，开发者仍会为成员添加标注，且这些标注通常会简化推断出的类型。结论：Python库与框架中的类型提示主要用作API契约，而非对实现细节的全面描述。研究结果表明，在工具开发方面存在机遇，包括优先处理公共接口、识别有意义的标注变更，以及支持维护者更新类型信息。
英文摘要
Context: In Python, type hints allow developers to annotate variables and functions with explicit type information, improving code clarity and reliability. Although type hints are widely available, little is known about how they are adopted and maintained in libraries and frameworks. Objective: We investigate the adoption, usage, maintenance, and rationale of type hints in Python libraries and frameworks. Method: We analyzed 1,000 popular GitHub repositories, identifying libraries and frameworks and extracting their type annotations. We examined annotation coverage, the locations and origins of annotations, their evolution across git histories, and the relationship between developer annotations and types inferred by Pyright. Results: Of the analyzed repositories, 91% of libraries use type hints at least once, although adoption is inconsistent. Among libraries with systematic usage, maintainers prioritize function parameters and return types, with median coverage of 45.8% and 35.9%, respectively, and mainly use built-in types (73.0%). When modified, annotations tend to migrate to more expressive types. Developers annotate members even when Pyright can infer their types, and these annotations often simplify the inferred type. Conclusion: Type hints in Python libraries and frameworks primarily serve as API contracts rather than comprehensive descriptions of implementation details. The findings suggest opportunities for tooling that prioritizes public interfaces, identifies meaningful annotation changes, and supports maintainers in evolving type information.
