Skip to content

Commit 304ab86

Browse files
authored
[flake8-type-checking] Prefer lazy imports over TYPE_CHECKING on 3.15+ (TC001, TC002, TC003) (#28541)
Summary -- This PR closes #25181 by recognizing and suggesting lazy imports in the typing-only runtime imports rules. As noted in [PEP 810], one common use for `TYPE_CHECKING` blocks is to avoid importing code that isn't actually needed at runtime: > Type annotations frequently require imports that are never used at runtime. The common workaround > is to wrap them in `if TYPE_CHECKING:` blocks \[1\]. With lazy imports, annotation-only imports > impose no runtime penalty, eliminating the need for such guards and making annotated codebases > cleaner. The footnote is even more relevant: > Furthermore, there’s also external tooling, in the form of flake8-type-checking, because it is > common for developers to mislocate imports and accidentally introduce a runtime dependency on an > import only imported in such a block. Ironically, the static type checker is of no help in these > circumstances. In line with this usage, this PR exempts existing lazy imports from these rules, which otherwise would still suggest moving them into `TYPE_CHECKING` blocks, and it also adds a new fix to all three rules that will add `lazy` in front of an import on 3.15+. In line with our fixes for `TID254` and `TID255`, we fall back on the existing `TYPE_CHECKING` fix if the `lazy` addition is too complicated, i.e. when multiple names are imported on the same line or when we'd have to edit `__lazy_modules__`. [PEP 810]: https://peps.python.org/pep-0810/ Test Plan -- New mdtests
1 parent d940b24 commit 304ab86

2 files changed

Lines changed: 369 additions & 33 deletions

File tree

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Typing-only imports (`TC001`, `TC002`, `TC003`)
2+
3+
```toml
4+
target-version = "py315"
5+
6+
[lint]
7+
select = ["TC001", "TC002", "TC003"]
8+
9+
[lint.isort]
10+
known-first-party = ["app"]
11+
```
12+
13+
## Module imports
14+
15+
On Python 3.15, a module-level import used only in annotations can become lazy. This applies to
16+
first-party, third-party, and standard-library imports without enabling preview.
17+
18+
```py
19+
import app as local # snapshot: typing-only-first-party-import
20+
from vendor import Model # snapshot: typing-only-third-party-import
21+
import pathlib # snapshot: typing-only-standard-library-import
22+
23+
def load(value: local.Item, model: Model) -> pathlib.Path: ...
24+
```
25+
26+
```snapshot
27+
error[TC001]: Make application import `app` lazy
28+
--> src/mdtest_snippet.py:1:15
29+
|
30+
1 | import app as local # snapshot: typing-only-first-party-import
31+
| ^^^^^
32+
help: Convert to a lazy import (or move into a type-checking block)
33+
|
34+
- import app as local # snapshot: typing-only-first-party-import
35+
1 + lazy import app as local # snapshot: typing-only-first-party-import
36+
2 | from vendor import Model # snapshot: typing-only-third-party-import
37+
|
38+
note: This is an unsafe fix and may change runtime behavior
39+
40+
41+
error[TC002]: Make third-party import `vendor.Model` lazy
42+
--> src/mdtest_snippet.py:2:20
43+
|
44+
2 | from vendor import Model # snapshot: typing-only-third-party-import
45+
| ^^^^^
46+
help: Convert to a lazy import (or move into a type-checking block)
47+
|
48+
1 | import app as local # snapshot: typing-only-first-party-import
49+
- from vendor import Model # snapshot: typing-only-third-party-import
50+
2 + lazy from vendor import Model # snapshot: typing-only-third-party-import
51+
3 | import pathlib # snapshot: typing-only-standard-library-import
52+
|
53+
note: This is an unsafe fix and may change runtime behavior
54+
55+
56+
error[TC003]: Make standard library import `pathlib` lazy
57+
--> src/mdtest_snippet.py:3:8
58+
|
59+
3 | import pathlib # snapshot: typing-only-standard-library-import
60+
| ^^^^^^^
61+
help: Convert to a lazy import (or move into a type-checking block)
62+
|
63+
2 | from vendor import Model # snapshot: typing-only-third-party-import
64+
- import pathlib # snapshot: typing-only-standard-library-import
65+
3 + lazy import pathlib # snapshot: typing-only-standard-library-import
66+
4 |
67+
|
68+
note: This is an unsafe fix and may change runtime behavior
69+
```
70+
71+
## Existing lazy imports
72+
73+
Explicit lazy imports and imports made lazy by `__lazy_modules__` already defer import work and do
74+
not need to move into a type-checking block.
75+
76+
```py
77+
lazy from pathlib import Path # no diagnostic
78+
__lazy_modules__ = ["vendor"]
79+
from vendor import Model # no diagnostic
80+
81+
def load(value: Path) -> Model: ...
82+
```
83+
84+
## Multiple imported names
85+
86+
An import with multiple names retains the type-checking-block fix, leaving its runtime-used names
87+
unchanged.
88+
89+
```py
90+
import pathlib, sys # error: [typing-only-standard-library-import] "type-checking block"
91+
92+
print(sys.version)
93+
def load(value: pathlib.Path): ...
94+
```
95+
96+
## Invalid lazy import locations
97+
98+
Lazy syntax is invalid inside functions and `try` statements, so these imports retain the
99+
type-checking-block fix.
100+
101+
```py
102+
try:
103+
from vendor import Model # error: [typing-only-third-party-import] "type-checking block"
104+
except ImportError:
105+
pass
106+
107+
def load(value: Model):
108+
from pathlib import Path # error: [typing-only-standard-library-import] "type-checking block"
109+
110+
path: Path
111+
```
112+
113+
## Lazy import declarations on older Python versions
114+
115+
A `__lazy_modules__` declaration can express a preference for lazy imports while supporting older
116+
Python versions. Ruff does not edit these declarations, so it falls back to the type-checking-block
117+
fix when the target version does not support the `lazy` keyword.
118+
119+
```toml
120+
target-version = "py314"
121+
122+
[lint]
123+
select = ["TC003"]
124+
```
125+
126+
```py
127+
__lazy_modules__ = ["pathlib"]
128+
from pathlib import Path # error: [typing-only-standard-library-import] "type-checking block"
129+
130+
def load(value: Path): ...
131+
```
132+
133+
## Lazy import policies
134+
135+
Imports prohibited by `ban-lazy` retain the type-checking-block fix. An excluded module can still be
136+
imported lazily, including with a `from` import.
137+
138+
```toml
139+
target-version = "py315"
140+
141+
[lint]
142+
preview = true
143+
select = ["TC003", "TID254", "TID255"]
144+
145+
[lint.flake8-tidy-imports]
146+
ban-lazy = { include = "all", exclude = ["pathlib"] }
147+
```
148+
149+
```py
150+
from pathlib import Path # error: [typing-only-standard-library-import] "lazy"
151+
from decimal import Decimal # error: [typing-only-standard-library-import] "type-checking block"
152+
153+
def load(value: Path) -> Decimal: ...
154+
```
155+
156+
## Banned lazy imports
157+
158+
With `ban-lazy = "all"`, both cases above receive a type-checking block suggestion.
159+
160+
```toml
161+
target-version = "py315"
162+
163+
[lint]
164+
preview = true
165+
select = ["TC003", "TID254", "TID255"]
166+
167+
[lint.flake8-tidy-imports]
168+
ban-lazy = "all"
169+
```
170+
171+
```py
172+
from pathlib import Path # error: [typing-only-standard-library-import] "type-checking block"
173+
from decimal import Decimal # error: [typing-only-standard-library-import] "type-checking block"
174+
175+
def load(value: Path) -> Decimal: ...
176+
```

0 commit comments

Comments
 (0)