Summary -- For a bit of background, `__lazy_modules__` is a backwards compatibility mechanism for lazy imports, introduced in [PEP 810](https://peps.python.org/pep-0810/) alongside the `lazy` keyword itself. Instead of declaring an import `lazy` with the keyword, it can also be listed in a module-level constant named `__lazy_modules__`: ```py lazy import foo # equivalently __lazy_modules__ = ["foo"] import foo ``` This can be used in projects that support older Python versions, as well as 3.15. It also supports more dynamic approaches (that this PR doesn't), as noted in one of my inline comments, such as: ```py class LazyImporter: def __contains__(self, name): return True __lazy_modules__ = LazyImporter() ``` As one example from the PEP for emulating wildcard lazy imports. <hr> The PR is pretty big in total, but it's intended to be reviewed commit-by-commit. As usual, the very first commit is empty for filling the PR summary, so the numbers below refer to the remaining non-empty commits. The first commit adds `__lazy_modules__` tracking to the semantic model. Because the declaration affects later imports and can also be overwritten, we just store whatever was assigned to it last for later lookup when visiting other code. The second commit expands [TID254] to recognize `__lazy_modules__` and includes a few helper methods on the semantic model that are used by later rules as well. The third commit adds `__lazy_modules__` support to [TID255], which also relies on a new `BindingFlags::LAZY` variant. This marks bindings as originating from a lazy import, which is easier than trying to resolve a sequence of potentially shadowed `__lazy_modules__` bindings to check if an import was lazy. For example, we set the `LAZY` flag on `foo` here, which would otherwise require resolve multiple previous bindings: ```py __lazy_modules__ = ["foo"] import foo __lazy_modules__ = [] class C(foo.Something): ... ``` The last four commits make smaller changes to four other rules. As with TID254 and TID255, the primary change is that we withhold a fix that involves `__lazy_modules__` when it would change the module's lazy status. Initially I had hoped to add fixes that modified `__lazy_modules__` (adding to it when we'd otherwise add `lazy`, removing from it when we'd remove `lazy`), but this turned out to be quite complicated. Unlike the `lazy` keyword, `__lazy_modules__` has nonlocal effects that could change the behavior of _any_ import from the same module in the file. Trying to resolve all of that to be sure the fix is reasaonable was a real mess, and reverting Codex's attempt saved almost 700 lines for TID255 alone. Similarly, in case this comes up in someone else's Codex review, my Codex initially tried to handle even more edge cases with `__lazy_modules__` definitions, such as definitions in a loop or redefining it with `*` imports and things like that. I tried to rein it in toward something more like our `__all__` and `from __future__ import annotations` handling, which again seemed like the better tradeoff to me. Closes #25170. [TID254]: https://docs.astral.sh/ruff/rules/lazy-import-mismatch/ [TID255]: https://docs.astral.sh/ruff/rules/lazy-import-immediately-resolved/ Test Plan -- New mdtests. The ecosystem results all look correct. They are cases where `TID255` now fires in modules where `__lazy_modules__` is defined.

Support __lazy_modules__ in lazy import rules #25170

Description

Activity

ayush-singh-0601 commented on Sep 6, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Support `__lazy_modules__` in lazy import rules #25170