Search papers, labs, and topics across Lattice.
This study empirically analyzes the adoption and maintenance of type hints in 1,000 popular Python libraries and frameworks, revealing that while 91% utilize type hints, their implementation is inconsistent. The research highlights that maintainers focus on annotating function parameters and return types, achieving median coverage rates of 45.8% and 35.9%, respectively, predominantly using built-in types. Notably, developers often add annotations even when types can be inferred, indicating a preference for explicitness in API contracts over comprehensive implementation details.
Despite widespread availability, Python type hints are adopted inconsistently, with maintainers favoring explicit annotations for public interfaces over inferred types.
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.
