initpyi

initpyi is a term used in Python typing circles to refer to a type stub file that specifies the public API of a package’s initialization module. It is typically named __init__.pyi and resides in the package directory alongside the actual implementation. The purpose is to provide static type information to type checkers without running package code, which can help avoid side effects during type checking and improve the accuracy of API typings for packages with complex initialization logic.

The main role of an initpyi is to declare the types of objects that the package exposes at its top level. This often includes re-exported types from submodules, top-level classes and functions, and any public constants. A stub file uses the same syntax as a normal Python module but contains only type annotations and signatures; it does not include executable code. Typical content includes class and function signatures, type aliases, and imports used solely for typing. It may also define __all__ to control what the package exports.

In practice, initpyi works with type checkers such as mypy and Pyright and is part of the broader typing ecosystem described in PEP 561. When present, the stub informs the checker about the package’s public interface, which can improve type checking accuracy for users of the package and for those importing it from statically typed code. At runtime, Python ignores the .pyi file unless a tool imports it for typing purposes.

Maintainers must keep initpyi in sync with the actual runtime API to avoid false positives or negatives in type checking. See also: __init__.py, __init__.pyi, PEP 561, type stubs.