Fix incorrect removal of runtime import shadowed by TYPE_CHECKING import (#313)

When the same name is imported both at runtime and inside an
`if TYPE_CHECKING:` block, unimport incorrectly flagged the runtime
import as unused because the TYPE_CHECKING import won duplicate
resolution (being closer to usage). Since TYPE_CHECKING blocks only
execute during static analysis, their imports should never shadow
runtime imports.

Add _is_type_checking_block() to ImportAnalyzer.visit_If to detect
`if TYPE_CHECKING:`, `if typing.TYPE_CHECKING:`, and alias forms
like `if t.TYPE_CHECKING:`. When detected, imports in the body are
skipped entirely — they are not registered as imports, so they cannot
interfere with runtime import analysis.

Update existing type_variable test expectations (TYPE_CHECKING-body
imports are no longer in IMPORTS list). Add a new test case
reproducing the exact scenario from issue #313. Update
supported-behaviors.md with TYPE_CHECKING documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hakancelikdev

docs/tutorial/supported-behaviors.md

@@ -55,6 +55,29 @@ For more information
 
 ---
 
+#### TYPE_CHECKING
+
+Unimport recognizes `if TYPE_CHECKING:` blocks and skips imports inside them. These
+imports only run during static analysis and are not available at runtime, so they should
+never shadow or conflict with runtime imports.
+
+```python
+from qtpy import QtCore
+import typing as t
+
+if t.TYPE_CHECKING:
+    from PySide6 import QtCore
+
+class MyThread(QtCore.QThread):
+    pass
+```
+
+In this example, unimport correctly keeps `from qtpy import QtCore` (the runtime import)
+and ignores the `TYPE_CHECKING`-guarded import. Both `if TYPE_CHECKING:` and
+`if typing.TYPE_CHECKING:` (or any alias like `if t.TYPE_CHECKING:`) are supported.
+
+---
+
 ## All
 
 Unimport looks at the items in the `__all__` list, if it matches the imports, marks it

src/unimport/analyzers/import_statement.py

@@ -84,7 +84,21 @@ def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
                 node=node,
             )
 
+    @staticmethod
+    def _is_type_checking_block(if_node: ast.If) -> bool:
+        test = if_node.test
+        if isinstance(test, ast.Name) and test.id == "TYPE_CHECKING":
+            return True
+        if isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING":
+            return True
+        return False
+
     def visit_If(self, if_node: ast.If) -> None:
+        if self._is_type_checking_block(if_node):
+            for node in if_node.orelse:
+                self.visit(node)
+            return
+
         self.if_names = {
             name.asname or name.name
             for n in filter(lambda node: isinstance(node, (ast.Import, ast.ImportFrom)), if_node.body)

tests/cases/analyzer/type_variable/type_assing_cast.py

@@ -21,13 +21,5 @@
         star=False,
         suggestions=[],
     ),
-    ImportFrom(
-        lineno=4,
-        column=1,
-        name="QtWebKit",
-        package="PyQt5",
-        star=False,
-        suggestions=[],
-    ),
 ]
 UNUSED_IMPORTS: list[Union[Import, ImportFrom]] = []

tests/cases/analyzer/type_variable/type_assing_list.py

@@ -28,13 +28,5 @@
         star=False,
         suggestions=[],
     ),
-    ImportFrom(
-        lineno=4,
-        column=1,
-        name="QWebHistory",
-        package="PyQt5.QtWebKit",
-        star=False,
-        suggestions=[],
-    ),
 ]
 UNUSED_IMPORTS: list[Union[Import, ImportFrom]] = []

tests/cases/analyzer/type_variable/type_assing_union.py

@@ -29,21 +29,5 @@
         star=False,
         suggestions=[],
     ),
-    ImportFrom(
-        lineno=4,
-        column=1,
-        name="QtWebEngineWidgets",
-        package="PyQt5",
-        star=False,
-        suggestions=[],
-    ),
-    ImportFrom(
-        lineno=4,
-        column=2,
-        name="QtWebKit",
-        package="PyQt5",
-        star=False,
-        suggestions=[],
-    ),
 ]
 UNUSED_IMPORTS: list[Union[Import, ImportFrom]] = []

tests/cases/analyzer/type_variable/type_checking_duplicate_import.py

@@ -0,0 +1,28 @@
+from typing import Union
+
+from unimport.statement import Import, ImportFrom, Name
+
+__all__ = ["NAMES", "IMPORTS", "UNUSED_IMPORTS"]
+
+
+NAMES: list[Name] = [
+    Name(lineno=4, name="t.TYPE_CHECKING", is_all=False),
+    Name(lineno=7, name="QtCore.QThread", is_all=False),
+]
+IMPORTS: list[Union[Import, ImportFrom]] = [
+    ImportFrom(
+        lineno=1,
+        column=1,
+        name="QtCore",
+        package="qtpy",
+        star=False,
+        suggestions=[],
+    ),
+    Import(
+        lineno=2,
+        column=1,
+        name="t",
+        package="typing",
+    ),
+]
+UNUSED_IMPORTS: list[Union[Import, ImportFrom]] = []

tests/cases/refactor/type_variable/type_checking_duplicate_import.py

@@ -0,0 +1,8 @@
+from qtpy import QtCore
+import typing as t
+
+if t.TYPE_CHECKING:
+    from PySide6 import QtCore
+
+class MyThread(QtCore.QThread):
+    pass

tests/cases/source/type_variable/type_checking_duplicate_import.py

@@ -0,0 +1,8 @@
+from qtpy import QtCore
+import typing as t
+
+if t.TYPE_CHECKING:
+    from PySide6 import QtCore
+
+class MyThread(QtCore.QThread):
+    pass