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

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

Author: brianschubert

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,12 +1,13 @@
 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"]
 
 _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: