[stubtest] Allow runtime-existing aliases of types marked as @type_check_only (#19568)

brianschubert · web-flow · commit e8147f2bdcd8 · 2025-08-02T18:10:22.000+01:00
In typeshed, there's a few cases of stubs like this:
```python
class _DoesNotExist: ...  # does not exist at runtime

if sys.version_info &gt;= (3, X):
    Exists = _DoesNotExist
```
Ideally, it would be nice to mark `_DoesNotExit` as `@type_check_only`
to make it clear that this type isn't available at runtime. However,
this currently can't be done, because doing so will make stubtest think
that `Exists` is also `@type_check_only`, which sets off alarm bells due
to `Exists` being available at runtime.

This PR makes it so stubtest doesn't consider `@type_check_only`-status
when checking type alias targets, making it possible to mark types like
the above as `@type_check_only`.
diff --git a/mypy/stubtest.py b/mypy/stubtest.py
@@ -506,9 +506,13 @@ def _verify_metaclass(
 
 @verify.register(nodes.TypeInfo)
 def verify_typeinfo(
-    stub: nodes.TypeInfo, runtime: MaybeMissing[type[Any]], object_path: list[str]
+    stub: nodes.TypeInfo,
+    runtime: MaybeMissing[type[Any]],
+    object_path: list[str],
+    *,
+    is_alias_target: bool = False,
 ) -> Iterator[Error]:
-    if stub.is_type_check_only:
+    if stub.is_type_check_only and not is_alias_target:
         # This type only exists in stubs, we only check that the runtime part
         # is missing. Other checks are not required.
         if not isinstance(runtime, Missing):
@@ -1449,7 +1453,7 @@ def verify_typealias(
         # Okay, either we couldn't construct a fullname
         # or the fullname of the stub didn't match the fullname of the runtime.
         # Fallback to a full structural check of the runtime vis-a-vis the stub.
-        yield from verify(stub_origin, runtime_origin, object_path)
+        yield from verify_typeinfo(stub_origin, runtime_origin, object_path, is_alias_target=True)
         return
     if isinstance(stub_target, mypy.types.UnionType):
         # complain if runtime is not a Union or UnionType
diff --git a/mypy/test/teststubtest.py b/mypy/test/teststubtest.py
@@ -2472,6 +2472,17 @@ def func2() -> None: ...
             runtime="def func2() -> None: ...",
             error="func2",
         )
+        # A type that exists at runtime is allowed to alias a type marked
+        # as '@type_check_only' in the stubs.
+        yield Case(
+            stub="""
+            @type_check_only
+            class _X1: ...
+            X2 = _X1
+            """,
+            runtime="class X2: ...",
+            error=None,
+        )
 
 
 def remove_color_code(s: str) -> str:
