Mark stub-only private symbols as @type_check_only in third-party stubs (#14545)

Author: brianschubert

stubs/Authlib/authlib/oauth2/rfc6750/token.pyi

@@ -1,8 +1,9 @@
 from collections.abc import Callable
-from typing import Protocol
+from typing import Protocol, type_check_only
 
 from authlib.oauth2.rfc6749 import ClientMixin
 
+@type_check_only
 class _TokenGenerator(Protocol):
     def __call__(self, *, client: ClientMixin, grant_type: str, user, scope: str) -> str: ...
 

stubs/Flask-Cors/flask_cors/core.pyi

@@ -2,7 +2,7 @@ from collections.abc import Iterable
 from datetime import timedelta
 from logging import Logger
 from re import Match, Pattern
-from typing import Any, Final, Literal, TypedDict, TypeVar, overload
+from typing import Any, Final, Literal, TypedDict, TypeVar, overload, type_check_only
 from typing_extensions import TypeAlias
 
 import flask
@@ -11,6 +11,7 @@ _IterableT = TypeVar("_IterableT", bound=Iterable[Any])
 _T = TypeVar("_T")
 _MultiDict: TypeAlias = Any  # werkzeug is not part of typeshed
 
+@type_check_only
 class _Options(TypedDict, total=False):
     resources: dict[str, dict[str, Any]] | list[str] | str | None
     origins: str | list[str] | None

stubs/Flask-Migrate/flask_migrate/__init__.pyi

@@ -5,7 +5,7 @@ from _typeshed import StrPath, SupportsFlush, SupportsKeysAndGetItem, SupportsWr
 from argparse import Namespace
 from collections.abc import Callable, Iterable, Sequence
 from logging import Logger
-from typing import Any, Protocol, TypeVar
+from typing import Any, Protocol, TypeVar, type_check_only
 from typing_extensions import ParamSpec, TypeAlias
 
 import flask
@@ -20,6 +20,7 @@ _AlembicConfigValue: TypeAlias = Any
 alembic_version: tuple[int, int, int]
 log: Logger
 
+@type_check_only
 class _SupportsWriteAndFlush(SupportsWrite[_T_contra], SupportsFlush, Protocol): ...
 
 class Config:  # should inherit from alembic.config.Config which is not possible yet

stubs/Flask-SocketIO/flask_socketio/__init__.pyi

@@ -2,7 +2,7 @@ from _typeshed import Incomplete
 from collections.abc import Callable
 from logging import Logger
 from threading import Thread
-from typing import Any, Literal, Protocol, TypedDict, TypeVar, overload
+from typing import Any, Literal, Protocol, TypedDict, TypeVar, overload, type_check_only
 from typing_extensions import ParamSpec, TypeAlias, Unpack
 
 from flask import Flask
@@ -16,19 +16,23 @@ _R_co = TypeVar("_R_co", covariant=True)
 _ExceptionHandler: TypeAlias = Callable[[BaseException], _R_co]
 _Handler: TypeAlias = Callable[_P, _R_co]
 
+@type_check_only
 class _HandlerDecorator(Protocol):
     def __call__(self, handler: _Handler[_P, _R_co]) -> _Handler[_P, _R_co]: ...
 
+@type_check_only
 class _ExceptionHandlerDecorator(Protocol):
     def __call__(self, exception_handler: _ExceptionHandler[_R_co]) -> _ExceptionHandler[_R_co]: ...
 
+@type_check_only
 class _SocketIOServerOptions(TypedDict, total=False):
     client_manager: Incomplete
     logger: Logger | bool
     json: Incomplete
     async_handlers: bool
     always_connect: bool
 
+@type_check_only
 class _EngineIOServerConfig(TypedDict, total=False):
     async_mode: Literal["threading", "eventlet", "gevent", "gevent_uwsgi"]
     ping_interval: float | tuple[float, float]  # seconds
@@ -43,6 +47,7 @@ class _EngineIOServerConfig(TypedDict, total=False):
     monitor_clients: bool
     engineio_logger: Logger | bool
 
+@type_check_only
 class _SocketIOKwargs(_SocketIOServerOptions, _EngineIOServerConfig): ...
 
 class SocketIO:

stubs/Flask-SocketIO/flask_socketio/namespace.pyi

@@ -1,10 +1,11 @@
 from _typeshed import Incomplete
 from collections.abc import Callable
-from typing import Any, Protocol, TypeVar
+from typing import Any, Protocol, TypeVar, type_check_only
 
 _T = TypeVar("_T")
 
 # at runtime, socketio.namespace.BaseNamespace, but socketio isn't py.typed
+@type_check_only
 class _BaseNamespace(Protocol):
     def is_asyncio_based(self) -> bool: ...
     def trigger_event(self, event: str, *args): ...

stubs/Flask-SocketIO/flask_socketio/test_client.pyi

@@ -1,9 +1,10 @@
 from _typeshed import Incomplete
-from typing import Any, TypedDict
+from typing import Any, TypedDict, type_check_only
 
 from flask import Flask
 from flask.testing import FlaskClient
 
+@type_check_only
 class _Packet(TypedDict):
     name: str
     args: Any

stubs/JACK-Client/jack/__init__.pyi

@@ -1,6 +1,6 @@
 from _typeshed import Unused
 from collections.abc import Callable, Generator, Iterable, Iterator, Sequence
-from typing import Any, Final, Literal, NoReturn, overload
+from typing import Any, Final, Literal, NoReturn, overload, type_check_only
 from typing_extensions import Self
 
 import numpy
@@ -11,6 +11,7 @@ from numpy.typing import NDArray
 # Actual type: _cffi_backend.__CDataOwn <cdata 'struct _jack_position *'>
 # This is not a real subclassing. Just ensuring type-checkers sees this type as compatible with _CDataBase
 # pyright has no error code for subclassing final
+@type_check_only
 class _JackPositionT(_CDataBase):  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues]
     audio_frames_per_video_frame: float
     bar: int
@@ -33,6 +34,7 @@ class _JackPositionT(_CDataBase):  # type: ignore[misc]  # pyright: ignore[repor
     valid: int
     video_offset: int
 
+@type_check_only
 class _CBufferType:
     @overload
     def __getitem__(self, key: int) -> str: ...

stubs/Markdown/markdown/extensions/toc.pyi

@@ -1,6 +1,6 @@
 from collections.abc import Iterator, MutableSet
 from re import Pattern
-from typing import Any, TypedDict
+from typing import Any, TypedDict, type_check_only
 from typing_extensions import deprecated
 from xml.etree.ElementTree import Element
 
@@ -10,11 +10,13 @@ from markdown.treeprocessors import Treeprocessor
 
 IDCOUNT_RE: Pattern[str]
 
+@type_check_only
 class _FlatTocToken(TypedDict):
     level: int
     id: str
     name: str
 
+@type_check_only
 class _TocToken(_FlatTocToken):
     children: list[_TocToken]
 

stubs/Markdown/markdown/util.pyi

@@ -1,7 +1,7 @@
 import sys
 from collections.abc import Iterator
 from re import Pattern
-from typing import Final, Generic, TypedDict, TypeVar, overload
+from typing import Final, Generic, TypedDict, TypeVar, overload, type_check_only
 
 from markdown.core import Markdown
 
@@ -40,6 +40,7 @@ class Processor:
     md: Markdown
     def __init__(self, md: Markdown | None = None) -> None: ...
 
+@type_check_only
 class _TagData(TypedDict):
     tag: str
     attrs: dict[str, str]

stubs/PyYAML/yaml/emitter.pyi

@@ -1,12 +1,13 @@
 from collections.abc import Callable
-from typing import Any, NoReturn, Protocol, TypeVar
+from typing import Any, NoReturn, Protocol, TypeVar, type_check_only
 
 from yaml.error import YAMLError
 
 from .events import Event
 
 _T_contra = TypeVar("_T_contra", str, bytes, contravariant=True)
 
+@type_check_only
 class _WriteStream(Protocol[_T_contra]):
     def write(self, data: _T_contra, /) -> object: ...
     # Optional fields: