PEP 810 – Explicit lazy imports

Summary

The dominant convention in Python code is to place all imports at the module level, typically at the beginning of the file. This avoids repetition, makes dependencies clear and minimizes runtime overhead by only evaluating an import statement once per module. A major drawback with this approach is that importing the first module for an execution of Python (the “main” module) often triggers an immediate cascade of imports, and optimistically loads many dependencies that may never be used. The effect is especially costly for command-line tools with multiple subcommands, where even running the command with --help can load dozens of unnecessary modules and take several seconds. This basic example demonstrates what must be loaded just to get helpful feedback to the user on how to run the program at all. Inefficiently, the user incurs this overhead again when they figure out the command they want and invoke the program “for real.” A somewhat common way to delay imports is to move the imports into functions (inline imports), but this practice requires more work to implement and maintain, and can be subverted by a single inadvertent top-level import. Additionally, it obfuscates the full set of dependencies for a module. Analysis of the Python standard library shows that approximately 17% of all imports outside tests (nearly 3500 total imports across 730 files) are already placed inside functions or methods specifically to defer their execution. This demonstrates that developers are already manually implementing lazy imports in performance-sensitive code, but doing so requires scattering imports throughout the codebase and makes the full dependency graph harder to understand at a glance. The standard library provides the LazyLoader class to solve some of these inefficiency problems. It permits imports at the module level to work mostly like inline imports do. Many scientific Python libraries have adopted a similar pattern, formalized in SPEC 1. There’s also the third-party l...