How do third-party Python libraries use type annotations?
Type hints (a.k.a. type annotations) in Python have become an important tool for improving code readability, supporting static analysis, and enabling early bug detection. Accordingly, it makes sense for third-party libraries whose code is expected to be consumed by external clients to adopt type annotations for these benefits. However, it is unclear how pervasive the use of type annotations is in third-party libraries. In this paper, we investigate the extent to which third-party libraries have adopted type annotations and whether library developers place annotations where they offer the most benefit, such as on a library’s public API. We analyze 76,327 versions across 11,021 libraries on the Python Package Index (PyPI). Our results show that 83.39% of libraries have at least one annotation. We identify six evolution patterns and find that most libraries maintain stable or gradually increasing annotation coverage, while only 4.13% abandon annotations once adopted. We find that library developers adopt type annotations to improve code clarity, linting, documentation, and static analysis, but may remove them when they cause errors or when the hints are considered unnecessary. Perhaps surprisingly, we find that developers prioritize annotating private functions over public/client-facing ones. Encouragingly though, many of these annotations are constrained and precise, with few instances of the Any type, most of which occur in parameters of public functions. Based on our findings, we provide implications for library developers and maintainers, package users, community contributors and researchers.