Support and lints for `lazy` imports in Python 3.15+

[dylwil3]

This issue tracks support for lazy imports in Ruff.

Python 3.15 introduced PEP 810 - Explicit lazy imports. We have done the following:

• Update the parser
• Update the formatter
• Update the semantic model (though according to this subheading these will be treated the same as ordinary imports for our purposes)

But we may also want to consider some lints. For example:

1. ✅ Sorting these imports - Retain lazy keyword when sorting imports #23762
2. Adjust the fixes in flake8-type-checking to suggest that typing-only imports be lazily imported rather than gated behind if TYPE_CHECKING, as per this use-case in the PEP.
3. Relatedly - replacing existing if TYPE_CHECKING: ... imports with lazy imports.
4. Suggesting lazy imports any time we see an import not at the beginning of the file. (Developers sometimes approximate lazy imports these days by importing in the body of a function, for example.)
5. ✅ Enforce lazy imports always (or for configurable set of modules) - Add a rule to enforce lazy imports #23777
6. Conversely, removing lazy if we can guarantee that the import will be evaluated (e.g. by a top-level statement in the module).

[Avasam]

4. Suggesting lazy imports any time we see an import not at the beginning of the file. (Developers sometimes approximate lazy imports these days by importing in the body of a function, for example.)
5. More aggressive/opinionated lints - e.g. "make all imports lazy", with an unsafe autofix.

Somewhere in between, less aggressive: Suggesting lazy imports whenever a symbol isn't obviously used at the module root level (still imperfect, but less false-positives than "make all imports lazy")

In other words: "5. Make all imports lazy, except when detected to be used at module root".

Further refinement with code analysis could try to follow function calls, but that seems niche.

[brettcannon]

This is now in main.

[tobiasdiez]

@brettcannon This is awesome. Just for clarification, did only the 'basic' support landed (the first 3 points in the issue description) or are also the other ones already done? In particular, I'm curious about what ordering of the imports you decided to implement ("Sorting these imports (this requires a few design decisions)").

[ntBre]

I think Brett meant that this landed in CPython! We haven't added this support to Ruff yet, as far as I know.

[brettcannon]

I think Brett meant that this landed in CPython!

Correct! Sorry about the ambiguous wording. 😅

[hugovk]

From the PEP:

Compatibility for library authors was also a key concern. Many maintainers need a migration path that allows them to support both new and old versions of Python at once. For this reason, the proposal includes the __lazy_modules__ global as a transitional mechanism. A module can declare which imports should be treated as lazy (by listing the module names as strings), and on Python 3.15 or later those imports will become lazy automatically, as if they were imported with the lazy keyword. On earlier versions the declaration is ignored, leaving imports eager. This gives authors a practical bridge until they can rely on the keyword as the canonical syntax.

It would be useful to also sort __lazy_modules__. Two options:

• Alphabetical
• Follow the isort settings, for example: stdlib, third-party, local

And the Steering Council's acceptance said:

We agree that the PEP should take no position on any style recommendations for sorting lazy imports. While we generally like the idea of grouping lazy imports together, let’s leave that up to the linters and auto-formatters to decide the details.

See also PyCQA/isort#2462.