Bringing NumPy's type-completeness score to nearly 90% – Pyrefly

Summary

Because NumPy is one of the most downloaded packages in the Python ecosystem, any incremental improvement can have a large impact on the data science ecosystem. In particular, improvements related to static typing can improve developer experience and help downstream libraries write safer code. We'll tell the story about how we (Quansight Labs, with support from Meta's Pyrefly team) helped bring its type-completeness score to nearly 90% from an initial 33%. TL;DR: NumPy's type-completeness score was ~33%. A one-line fix doubled coverage to over 80%. Fully typing MaskedArray pushed the score to nearly 90%. What's left? Top-level numpy.ma functions, more precise overloads, and adding a type-checker to NumPy's CI. Wait, what's type completeness?​ Modern IDEs use type annotations to help developers by showing them helpful suggestions and highlighting syntax. Pyright is a popular type-checker which, as well as checking for correctness and consistency, can also measure what percentage of a library's public API has type annotations. We call the percentage of fully-typed symbols exported by a library the type-completeness score. For example, a module which exports functions foo and bar: def foo(a: int): return Nonedef bar() -> int: return 1 would have a 50% type-completeness score, because: foo is partially unknown, as it's missing a return annotation. bar is type-complete. By changing the foo signature to be def foo(a: int) -> None:, the type-completeness score would jump to 100%. The more type-complete a library is, the more helpful the suggestions an IDE can show to the user. Note that type-completeness only measures how much of the public API (at least, the part known to Pyright) is covered by types. If you want to verify that those types are correct and self-consistent, you'll also need to run a type checker. The most used type checkers currently are mypy and Pyright, but Pyrefly and ty are also attracting a lot of attention due to their impressive performance character...