Add @type_check_only to stub-only private classes in stdlib (#14512)

stdlib/asyncio/events.pyi

@@ -12,7 +12,7 @@ from collections.abc import Callable, Sequence
 from concurrent.futures import Executor
 from contextvars import Context
 from socket import AddressFamily, SocketKind, _Address, _RetAddress, socket
-from typing import IO, Any, Literal, Protocol, TypeVar, overload
+from typing import IO, Any, Literal, Protocol, TypeVar, overload, type_check_only
 from typing_extensions import Self, TypeAlias, TypeVarTuple, Unpack, deprecated
 
 from . import _AwaitableLike, _CoroutineLike
@@ -68,6 +68,7 @@ _ExceptionHandler: TypeAlias = Callable[[AbstractEventLoop, _Context], object]
 _ProtocolFactory: TypeAlias = Callable[[], BaseProtocol]
 _SSLContext: TypeAlias = bool | None | ssl.SSLContext
 
+@type_check_only
 class _TaskFactory(Protocol):
     def __call__(self, loop: AbstractEventLoop, factory: _CoroutineLike[_T], /) -> Future[_T]: ...
 
@@ -599,6 +600,9 @@ class AbstractEventLoop:
     @abstractmethod
     async def shutdown_default_executor(self) -> None: ...
 
+# This class does not exist at runtime, but stubtest complains if it's marked as
+# @type_check_only because it has an alias that does exist at runtime. See mypy#19568.
+# @type_check_only
 class _AbstractEventLoopPolicy:
     @abstractmethod
     def get_event_loop(self) -> AbstractEventLoop: ...

stdlib/asyncio/format_helpers.pyi

@@ -3,9 +3,10 @@ import sys
 import traceback
 from collections.abc import Iterable
 from types import FrameType, FunctionType
-from typing import Any, overload
+from typing import Any, overload, type_check_only
 from typing_extensions import TypeAlias
 
+@type_check_only
 class _HasWrapper:
     __wrapper__: _HasWrapper | FunctionType
 

stdlib/asyncio/streams.pyi

@@ -3,7 +3,7 @@ import sys
 from _typeshed import ReadableBuffer, StrPath
 from collections.abc import Awaitable, Callable, Iterable, Sequence, Sized
 from types import ModuleType
-from typing import Any, Protocol, SupportsIndex
+from typing import Any, Protocol, SupportsIndex, type_check_only
 from typing_extensions import Self, TypeAlias
 
 from . import events, protocols, transports
@@ -25,6 +25,7 @@ else:
 
 _ClientConnectedCallback: TypeAlias = Callable[[StreamReader, StreamWriter], Awaitable[None] | None]
 
+@type_check_only
 class _ReaduntilBuffer(ReadableBuffer, Sized, Protocol): ...
 
 if sys.version_info >= (3, 10):

stdlib/asyncio/tasks.pyi

@@ -8,7 +8,7 @@ from _asyncio import (
     _unregister_task as _unregister_task,
 )
 from collections.abc import AsyncIterator, Awaitable, Coroutine, Generator, Iterable, Iterator
-from typing import Any, Literal, Protocol, TypeVar, overload
+from typing import Any, Literal, Protocol, TypeVar, overload, type_check_only
 from typing_extensions import TypeAlias
 
 from . import _CoroutineLike
@@ -87,6 +87,7 @@ FIRST_EXCEPTION = concurrent.futures.FIRST_EXCEPTION
 ALL_COMPLETED = concurrent.futures.ALL_COMPLETED
 
 if sys.version_info >= (3, 13):
+    @type_check_only
     class _SyncAndAsyncIterator(Iterator[_T_co], AsyncIterator[_T_co], Protocol[_T_co]): ...
 
     def as_completed(fs: Iterable[_FutureLike[_T]], *, timeout: float | None = None) -> _SyncAndAsyncIterator[Future[_T]]: ...
@@ -445,6 +446,7 @@ elif sys.version_info >= (3, 12):
 if sys.version_info >= (3, 12):
     _TaskT_co = TypeVar("_TaskT_co", bound=Task[Any], covariant=True)
 
+    @type_check_only
     class _CustomTaskConstructor(Protocol[_TaskT_co]):
         def __call__(
             self,
@@ -457,6 +459,7 @@ if sys.version_info >= (3, 12):
             eager_start: bool,
         ) -> _TaskT_co: ...
 
+    @type_check_only
     class _EagerTaskFactoryType(Protocol[_TaskT_co]):
         def __call__(
             self,