Add @type_check_only to various typeshed-only procotols in stdlib (#14465)

Mark various typeshed-only protocols as `@type_check_only` in stdlib

stdlib/_operator.pyi

@@ -2,7 +2,7 @@ import sys
 from _typeshed import SupportsGetItem
 from collections.abc import Callable, Container, Iterable, MutableMapping, MutableSequence, Sequence
 from operator import attrgetter as attrgetter, itemgetter as itemgetter, methodcaller as methodcaller
-from typing import Any, AnyStr, Protocol, SupportsAbs, SupportsIndex, TypeVar, overload
+from typing import Any, AnyStr, Protocol, SupportsAbs, SupportsIndex, TypeVar, overload, type_check_only
 from typing_extensions import ParamSpec, TypeAlias, TypeIs
 
 _R = TypeVar("_R")
@@ -16,12 +16,15 @@ _P = ParamSpec("_P")
 # operators can be overloaded to return an arbitrary object. For example,
 # the numpy.array comparison dunders return another numpy.array.
 
+@type_check_only
 class _SupportsDunderLT(Protocol):
     def __lt__(self, other: Any, /) -> Any: ...
 
+@type_check_only
 class _SupportsDunderGT(Protocol):
     def __gt__(self, other: Any, /) -> Any: ...
 
+@type_check_only
 class _SupportsDunderLE(Protocol):
     def __le__(self, other: Any, /) -> Any: ...
 
@@ -30,12 +33,15 @@ class _SupportsDunderGE(Protocol):
 
 _SupportsComparison: TypeAlias = _SupportsDunderLE | _SupportsDunderGE | _SupportsDunderGT | _SupportsDunderLT
 
+@type_check_only
 class _SupportsInversion(Protocol[_T_co]):
     def __invert__(self) -> _T_co: ...
 
+@type_check_only
 class _SupportsNeg(Protocol[_T_co]):
     def __neg__(self) -> _T_co: ...
 
+@type_check_only
 class _SupportsPos(Protocol[_T_co]):
     def __pos__(self) -> _T_co: ...
 

stdlib/argparse.pyi

@@ -2,7 +2,7 @@ import sys
 from _typeshed import SupportsWrite, sentinel
 from collections.abc import Callable, Generator, Iterable, Sequence
 from re import Pattern
-from typing import IO, Any, ClassVar, Final, Generic, NoReturn, Protocol, TypeVar, overload
+from typing import IO, Any, ClassVar, Final, Generic, NoReturn, Protocol, TypeVar, overload, type_check_only
 from typing_extensions import Self, TypeAlias, deprecated
 
 __all__ = [
@@ -112,6 +112,7 @@ class _ActionsContainer:
     def _handle_conflict_error(self, action: Action, conflicting_actions: Iterable[tuple[str, Action]]) -> NoReturn: ...
     def _handle_conflict_resolve(self, action: Action, conflicting_actions: Iterable[tuple[str, Action]]) -> None: ...
 
+@type_check_only
 class _FormatterClass(Protocol):
     def __call__(self, *, prog: str) -> HelpFormatter: ...
 

stdlib/builtins.pyi

@@ -452,9 +452,11 @@ class complex:
         @classmethod
         def from_number(cls, number: complex | SupportsComplex | SupportsFloat | SupportsIndex, /) -> Self: ...
 
+@type_check_only
 class _FormatMapMapping(Protocol):
     def __getitem__(self, key: str, /) -> Any: ...
 
+@type_check_only
 class _TranslateTable(Protocol):
     def __getitem__(self, key: int, /) -> str | int | None: ...
 
@@ -1355,7 +1357,7 @@ def chr(i: int | SupportsIndex, /) -> str: ...
 
 if sys.version_info >= (3, 10):
     def aiter(async_iterable: SupportsAiter[_SupportsAnextT_co], /) -> _SupportsAnextT_co: ...
-
+    @type_check_only
     class _SupportsSynchronousAnext(Protocol[_AwaitableT_co]):
         def __anext__(self) -> _AwaitableT_co: ...
 

stdlib/cgi.pyi

@@ -3,7 +3,7 @@ from builtins import list as _list, type as _type
 from collections.abc import Iterable, Iterator, Mapping
 from email.message import Message
 from types import TracebackType
-from typing import IO, Any, Protocol
+from typing import IO, Any, Protocol, type_check_only
 from typing_extensions import Self
 
 __all__ = [
@@ -31,7 +31,7 @@ def parse(
 def parse_multipart(
     fp: IO[Any], pdict: SupportsGetItem[str, bytes], encoding: str = "utf-8", errors: str = "replace", separator: str = "&"
 ) -> dict[str, list[Any]]: ...
-
+@type_check_only
 class _Environ(Protocol):
     def __getitem__(self, k: str, /) -> str: ...
     def keys(self) -> Iterable[str]: ...

stdlib/compileall.pyi

@@ -1,10 +1,11 @@
 import sys
 from _typeshed import StrPath
 from py_compile import PycInvalidationMode
-from typing import Any, Protocol
+from typing import Any, Protocol, type_check_only
 
 __all__ = ["compile_dir", "compile_file", "compile_path"]
 
+@type_check_only
 class _SupportsSearch(Protocol):
     def search(self, string: str, /) -> Any: ...
 

stdlib/contextlib.pyi

@@ -4,7 +4,7 @@ from _typeshed import FileDescriptorOrPath, Unused
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Generator, Iterator
 from types import TracebackType
-from typing import IO, Any, Generic, Protocol, TypeVar, overload, runtime_checkable
+from typing import IO, Any, Generic, Protocol, TypeVar, overload, runtime_checkable, type_check_only
 from typing_extensions import ParamSpec, Self, TypeAlias
 
 __all__ = [
@@ -112,7 +112,7 @@ else:
         ) -> bool | None: ...
 
 def asynccontextmanager(func: Callable[_P, AsyncIterator[_T_co]]) -> Callable[_P, _AsyncGeneratorContextManager[_T_co]]: ...
-
+@type_check_only
 class _SupportsClose(Protocol):
     def close(self) -> object: ...
 
@@ -123,6 +123,7 @@ class closing(AbstractContextManager[_SupportsCloseT, None]):
     def __exit__(self, *exc_info: Unused) -> None: ...
 
 if sys.version_info >= (3, 10):
+    @type_check_only
     class _SupportsAclose(Protocol):
         def aclose(self) -> Awaitable[object]: ...
 

stdlib/copy.pyi

@@ -1,5 +1,5 @@
 import sys
-from typing import Any, Protocol, TypeVar
+from typing import Any, Protocol, TypeVar, type_check_only
 from typing_extensions import Self
 
 __all__ = ["Error", "copy", "deepcopy"]
@@ -7,6 +7,7 @@ __all__ = ["Error", "copy", "deepcopy"]
 _T = TypeVar("_T")
 _SR = TypeVar("_SR", bound=_SupportsReplace)
 
+@type_check_only
 class _SupportsReplace(Protocol):
     # In reality doesn't support args, but there's no other great way to express this.
     def __replace__(self, *args: Any, **kwargs: Any) -> Self: ...

stdlib/fileinput.pyi

@@ -2,7 +2,7 @@ import sys
 from _typeshed import AnyStr_co, StrOrBytesPath
 from collections.abc import Callable, Iterable
 from types import GenericAlias, TracebackType
-from typing import IO, Any, AnyStr, Generic, Literal, Protocol, overload
+from typing import IO, Any, AnyStr, Generic, Literal, Protocol, overload, type_check_only
 from typing_extensions import Self, TypeAlias
 
 __all__ = [
@@ -25,6 +25,7 @@ if sys.version_info >= (3, 11):
 else:
     _TextMode: TypeAlias = Literal["r", "rU", "U"]
 
+@type_check_only
 class _HasReadlineAndFileno(Protocol[AnyStr_co]):
     def readline(self) -> AnyStr_co: ...
     def fileno(self) -> int: ...

stdlib/fractions.pyi

@@ -2,13 +2,14 @@ import sys
 from collections.abc import Callable
 from decimal import Decimal
 from numbers import Rational, Real
-from typing import Any, Literal, Protocol, SupportsIndex, overload
+from typing import Any, Literal, Protocol, SupportsIndex, overload, type_check_only
 from typing_extensions import Self, TypeAlias
 
 _ComparableNum: TypeAlias = int | float | Decimal | Real
 
 __all__ = ["Fraction"]
 
+@type_check_only
 class _ConvertibleToIntegerRatio(Protocol):
     def as_integer_ratio(self) -> tuple[int | Rational, int | Rational]: ...
 

stdlib/gettext.pyi

@@ -2,7 +2,7 @@ import io
 import sys
 from _typeshed import StrPath
 from collections.abc import Callable, Container, Iterable, Sequence
-from typing import Any, Final, Literal, Protocol, TypeVar, overload
+from typing import Any, Final, Literal, Protocol, TypeVar, overload, type_check_only
 
 __all__ = [
     "NullTranslations",
@@ -26,6 +26,7 @@ __all__ = [
 if sys.version_info < (3, 11):
     __all__ += ["bind_textdomain_codeset", "ldgettext", "ldngettext", "lgettext", "lngettext"]
 
+@type_check_only
 class _TranslationsReader(Protocol):
     def read(self) -> bytes: ...
     # optional:

stdlib/gzip.pyi

@@ -2,7 +2,7 @@ import sys
 import zlib
 from _typeshed import ReadableBuffer, SizedBuffer, StrOrBytesPath, WriteableBuffer
 from io import FileIO, TextIOWrapper
-from typing import Final, Literal, Protocol, overload
+from typing import Final, Literal, Protocol, overload, type_check_only
 from typing_extensions import TypeAlias
 
 if sys.version_info >= (3, 14):
@@ -25,6 +25,7 @@ FEXTRA: Final[int]  # actually Literal[4] # undocumented
 FNAME: Final[int]  # actually Literal[8] # undocumented
 FCOMMENT: Final[int]  # actually Literal[16] # undocumented
 
+@type_check_only
 class _ReadableFileobj(Protocol):
     def read(self, n: int, /) -> bytes: ...
     def seek(self, n: int, /) -> object: ...
@@ -33,6 +34,7 @@ class _ReadableFileobj(Protocol):
     # mode: str
     # def fileno() -> int: ...
 
+@type_check_only
 class _WritableFileobj(Protocol):
     def write(self, b: bytes, /) -> object: ...
     def flush(self) -> object: ...

stdlib/imghdr.pyi

@@ -1,9 +1,10 @@
 from _typeshed import StrPath
 from collections.abc import Callable
-from typing import Any, BinaryIO, Protocol, overload
+from typing import Any, BinaryIO, Protocol, overload, type_check_only
 
 __all__ = ["what"]
 
+@type_check_only
 class _ReadableBinary(Protocol):
     def tell(self) -> int: ...
     def read(self, size: int, /) -> bytes: ...

stdlib/inspect.pyi

@@ -25,7 +25,7 @@ from types import (
     TracebackType,
     WrapperDescriptorType,
 )
-from typing import Any, ClassVar, Final, Literal, NamedTuple, Protocol, TypeVar, overload
+from typing import Any, ClassVar, Final, Literal, NamedTuple, Protocol, TypeVar, overload, type_check_only
 from typing_extensions import ParamSpec, Self, TypeAlias, TypeGuard, TypeIs
 
 if sys.version_info >= (3, 14):
@@ -240,10 +240,11 @@ def isasyncgenfunction(obj: Callable[..., AsyncGenerator[Any, Any]]) -> bool: ..
 def isasyncgenfunction(obj: Callable[_P, Any]) -> TypeGuard[Callable[_P, AsyncGeneratorType[Any, Any]]]: ...
 @overload
 def isasyncgenfunction(obj: object) -> TypeGuard[Callable[..., AsyncGeneratorType[Any, Any]]]: ...
-
+@type_check_only
 class _SupportsSet(Protocol[_T_contra, _V_contra]):
     def __set__(self, instance: _T_contra, value: _V_contra, /) -> None: ...
 
+@type_check_only
 class _SupportsDelete(Protocol[_T_contra]):
     def __delete__(self, instance: _T_contra, /) -> None: ...
 

stdlib/math.pyi

@@ -1,7 +1,7 @@
 import sys
 from _typeshed import SupportsMul, SupportsRMul
 from collections.abc import Iterable
-from typing import Any, Final, Literal, Protocol, SupportsFloat, SupportsIndex, TypeVar, overload
+from typing import Any, Final, Literal, Protocol, SupportsFloat, SupportsIndex, TypeVar, overload, type_check_only
 from typing_extensions import TypeAlias
 
 _T = TypeVar("_T")
@@ -26,6 +26,7 @@ def atanh(x: _SupportsFloatOrIndex, /) -> float: ...
 if sys.version_info >= (3, 11):
     def cbrt(x: _SupportsFloatOrIndex, /) -> float: ...
 
+@type_check_only
 class _SupportsCeil(Protocol[_T_co]):
     def __ceil__(self) -> _T_co: ...
 
@@ -49,7 +50,7 @@ if sys.version_info >= (3, 11):
 def expm1(x: _SupportsFloatOrIndex, /) -> float: ...
 def fabs(x: _SupportsFloatOrIndex, /) -> float: ...
 def factorial(x: SupportsIndex, /) -> int: ...
-
+@type_check_only
 class _SupportsFloor(Protocol[_T_co]):
     def __floor__(self) -> _T_co: ...
 
@@ -99,6 +100,7 @@ _LiteralInteger = _PositiveInteger | _NegativeInteger | Literal[0]  # noqa: Y026
 _MultiplicableT1 = TypeVar("_MultiplicableT1", bound=SupportsMul[Any, Any])
 _MultiplicableT2 = TypeVar("_MultiplicableT2", bound=SupportsMul[Any, Any])
 
+@type_check_only
 class _SupportsProdWithNoDefaultGiven(SupportsMul[Any, Any], SupportsRMul[int, Any], Protocol): ...
 
 _SupportsProdNoDefaultT = TypeVar("_SupportsProdNoDefaultT", bound=_SupportsProdWithNoDefaultGiven)
@@ -127,6 +129,7 @@ def tan(x: _SupportsFloatOrIndex, /) -> float: ...
 def tanh(x: _SupportsFloatOrIndex, /) -> float: ...
 
 # Is different from `_typeshed.SupportsTrunc`, which is not generic
+@type_check_only
 class _SupportsTrunc(Protocol[_T_co]):
     def __trunc__(self) -> _T_co: ...
 

stdlib/socket.pyi

@@ -136,7 +136,7 @@ from _typeshed import ReadableBuffer, Unused, WriteableBuffer
 from collections.abc import Iterable
 from enum import IntEnum, IntFlag
 from io import BufferedReader, BufferedRWPair, BufferedWriter, IOBase, RawIOBase, TextIOWrapper
-from typing import Any, Literal, Protocol, SupportsIndex, overload
+from typing import Any, Literal, Protocol, SupportsIndex, overload, type_check_only
 from typing_extensions import Self
 
 __all__ = [
@@ -1290,6 +1290,7 @@ if sys.platform != "win32" and sys.platform != "linux":
 if sys.platform == "win32":
     errorTab: dict[int, str]  # undocumented
 
+@type_check_only
 class _SendableFile(Protocol):
     def read(self, size: int, /) -> bytes: ...
     def seek(self, offset: int, /) -> object: ...