Sync typeshed (#16969)

Source commit:

python/typeshed@e050986

mypy/typeshed/stdlib/VERSIONS

@@ -36,6 +36,7 @@ _heapq: 3.0-
 _imp: 3.0-
 _json: 3.0-
 _locale: 3.0-
+_lsprof: 3.0-
 _markupbase: 3.0-
 _msi: 3.0-
 _operator: 3.4-

mypy/typeshed/stdlib/_ctypes.pyi

@@ -64,6 +64,7 @@ class _CData(metaclass=_CDataMeta):
     # Structure.from_buffer(...)  # valid at runtime
     # Structure(...).from_buffer(...)  # invalid at runtime
     #
+
     @classmethod
     def from_buffer(cls, source: WriteableBuffer, offset: int = ...) -> Self: ...
     @classmethod
@@ -106,14 +107,15 @@ class _CArgObject: ...
 
 def byref(obj: _CData, offset: int = ...) -> _CArgObject: ...
 
-_ECT: TypeAlias = Callable[[type[_CData] | None, CFuncPtr, tuple[_CData, ...]], _CData]
+_ECT: TypeAlias = Callable[[_CData | None, CFuncPtr, tuple[_CData, ...]], _CData]
 _PF: TypeAlias = tuple[int] | tuple[int, str | None] | tuple[int, str | None, Any]
 
 class CFuncPtr(_PointerLike, _CData):
     restype: type[_CData] | Callable[[int], Any] | None
     argtypes: Sequence[type[_CData]]
     errcheck: _ECT
-    _flags_: ClassVar[int]  # Abstract attribute that must be defined on subclasses
+    # Abstract attribute that must be defined on subclasses
+    _flags_: ClassVar[int]
     @overload
     def __init__(self) -> None: ...
     @overload

mypy/typeshed/stdlib/_dummy_thread.pyi

@@ -1,13 +1,19 @@
 from collections.abc import Callable
 from types import TracebackType
-from typing import Any, NoReturn
+from typing import Any, NoReturn, overload
+from typing_extensions import TypeVarTuple, Unpack
 
 __all__ = ["error", "start_new_thread", "exit", "get_ident", "allocate_lock", "interrupt_main", "LockType", "RLock"]
 
+_Ts = TypeVarTuple("_Ts")
+
 TIMEOUT_MAX: int
 error = RuntimeError
 
-def start_new_thread(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any] = {}) -> None: ...
+@overload
+def start_new_thread(function: Callable[[Unpack[_Ts]], object], args: tuple[Unpack[_Ts]]) -> None: ...
+@overload
+def start_new_thread(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any]) -> None: ...
 def exit() -> NoReturn: ...
 def get_ident() -> int: ...
 def allocate_lock() -> LockType: ...

mypy/typeshed/stdlib/_lsprof.pyi

@@ -0,0 +1,35 @@
+import sys
+from _typeshed import structseq
+from collections.abc import Callable
+from types import CodeType
+from typing import Any, Final, final
+
+class Profiler:
+    def __init__(
+        self, timer: Callable[[], float] | None = None, timeunit: float = 0.0, subcalls: bool = True, builtins: bool = True
+    ) -> None: ...
+    def getstats(self) -> list[profiler_entry]: ...
+    def enable(self, subcalls: bool = True, builtins: bool = True) -> None: ...
+    def disable(self) -> None: ...
+    def clear(self) -> None: ...
+
+@final
+class profiler_entry(structseq[Any], tuple[CodeType | str, int, int, float, float, list[profiler_subentry]]):
+    if sys.version_info >= (3, 10):
+        __match_args__: Final = ("code", "callcount", "reccallcount", "totaltime", "inlinetime", "calls")
+    code: CodeType | str
+    callcount: int
+    reccallcount: int
+    totaltime: float
+    inlinetime: float
+    calls: list[profiler_subentry]
+
+@final
+class profiler_subentry(structseq[Any], tuple[CodeType | str, int, int, float, float]):
+    if sys.version_info >= (3, 10):
+        __match_args__: Final = ("code", "callcount", "reccallcount", "totaltime", "inlinetime")
+    code: CodeType | str
+    callcount: int
+    reccallcount: int
+    totaltime: float
+    inlinetime: float

mypy/typeshed/stdlib/_operator.pyi

@@ -95,16 +95,16 @@ def length_hint(__obj: object, __default: int = 0) -> int: ...
 @final
 class attrgetter(Generic[_T_co]):
     @overload
-    def __new__(cls, attr: str) -> attrgetter[Any]: ...
+    def __new__(cls, attr: str, /) -> attrgetter[Any]: ...
     @overload
-    def __new__(cls, attr: str, __attr2: str) -> attrgetter[tuple[Any, Any]]: ...
+    def __new__(cls, attr: str, attr2: str, /) -> attrgetter[tuple[Any, Any]]: ...
     @overload
-    def __new__(cls, attr: str, __attr2: str, __attr3: str) -> attrgetter[tuple[Any, Any, Any]]: ...
+    def __new__(cls, attr: str, attr2: str, attr3: str, /) -> attrgetter[tuple[Any, Any, Any]]: ...
     @overload
-    def __new__(cls, attr: str, __attr2: str, __attr3: str, __attr4: str) -> attrgetter[tuple[Any, Any, Any, Any]]: ...
+    def __new__(cls, attr: str, attr2: str, attr3: str, attr4: str, /) -> attrgetter[tuple[Any, Any, Any, Any]]: ...
     @overload
-    def __new__(cls, attr: str, *attrs: str) -> attrgetter[tuple[Any, ...]]: ...
-    def __call__(self, obj: Any) -> _T_co: ...
+    def __new__(cls, attr: str, /, *attrs: str) -> attrgetter[tuple[Any, ...]]: ...
+    def __call__(self, obj: Any, /) -> _T_co: ...
 
 @final
 class itemgetter(Generic[_T_co]):

mypy/typeshed/stdlib/_thread.pyi

@@ -3,7 +3,10 @@ from _typeshed import structseq
 from collections.abc import Callable
 from threading import Thread
 from types import TracebackType
-from typing import Any, Final, NoReturn, final
+from typing import Any, Final, NoReturn, final, overload
+from typing_extensions import TypeVarTuple, Unpack
+
+_Ts = TypeVarTuple("_Ts")
 
 error = RuntimeError
 
@@ -18,7 +21,10 @@ class LockType:
         self, type: type[BaseException] | None, value: BaseException | None, traceback: TracebackType | None
     ) -> None: ...
 
-def start_new_thread(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any] = ...) -> int: ...
+@overload
+def start_new_thread(function: Callable[[Unpack[_Ts]], object], args: tuple[Unpack[_Ts]]) -> int: ...
+@overload
+def start_new_thread(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any]) -> int: ...
 def interrupt_main() -> None: ...
 def exit() -> NoReturn: ...
 def allocate_lock() -> LockType: ...

mypy/typeshed/stdlib/abc.pyi

@@ -3,7 +3,7 @@ import sys
 from _typeshed import SupportsWrite
 from collections.abc import Callable
 from typing import Any, Literal, TypeVar
-from typing_extensions import Concatenate, ParamSpec
+from typing_extensions import Concatenate, ParamSpec, deprecated
 
 _T = TypeVar("_T")
 _R_co = TypeVar("_R_co", covariant=True)
@@ -28,15 +28,17 @@ class ABCMeta(type):
     def register(cls: ABCMeta, subclass: type[_T]) -> type[_T]: ...
 
 def abstractmethod(funcobj: _FuncT) -> _FuncT: ...
-
+@deprecated("Deprecated, use 'classmethod' with 'abstractmethod' instead")
 class abstractclassmethod(classmethod[_T, _P, _R_co]):
     __isabstractmethod__: Literal[True]
     def __init__(self, callable: Callable[Concatenate[type[_T], _P], _R_co]) -> None: ...
 
+@deprecated("Deprecated, use 'staticmethod' with 'abstractmethod' instead")
 class abstractstaticmethod(staticmethod[_P, _R_co]):
     __isabstractmethod__: Literal[True]
     def __init__(self, callable: Callable[_P, _R_co]) -> None: ...
 
+@deprecated("Deprecated, use 'property' with 'abstractmethod' instead")
 class abstractproperty(property):
     __isabstractmethod__: Literal[True]
 

mypy/typeshed/stdlib/argparse.pyi

@@ -3,7 +3,7 @@ from _typeshed import sentinel
 from collections.abc import Callable, Generator, Iterable, Sequence
 from re import Pattern
 from typing import IO, Any, Generic, Literal, NewType, NoReturn, Protocol, TypeVar, overload
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self, TypeAlias, deprecated
 
 __all__ = [
     "ArgumentParser",
@@ -339,11 +339,23 @@ class Action(_AttributeHolder):
 
 if sys.version_info >= (3, 12):
     class BooleanOptionalAction(Action):
+        @overload
         def __init__(
             self,
             option_strings: Sequence[str],
             dest: str,
-            default: _T | str | None = None,
+            default: bool | None = None,
+            *,
+            required: bool = False,
+            help: str | None = None,
+        ) -> None: ...
+        @overload
+        @deprecated("The `type`, `choices`, and `metavar` parameters are ignored and will be removed in Python 3.14.")
+        def __init__(
+            self,
+            option_strings: Sequence[str],
+            dest: str,
+            default: _T | bool | None = None,
             type: Callable[[str], _T] | FileType | None = sentinel,
             choices: Iterable[_T] | None = sentinel,
             required: bool = False,
@@ -353,11 +365,23 @@ if sys.version_info >= (3, 12):
 
 elif sys.version_info >= (3, 9):
     class BooleanOptionalAction(Action):
+        @overload
+        def __init__(
+            self,
+            option_strings: Sequence[str],
+            dest: str,
+            default: bool | None = None,
+            *,
+            required: bool = False,
+            help: str | None = None,
+        ) -> None: ...
+        @overload
+        @deprecated("The `type`, `choices`, and `metavar` parameters are ignored and will be removed in Python 3.14.")
         def __init__(
             self,
             option_strings: Sequence[str],
             dest: str,
-            default: _T | str | None = None,
+            default: _T | bool | None = None,
             type: Callable[[str], _T] | FileType | None = None,
             choices: Iterable[_T] | None = None,
             required: bool = False,

mypy/typeshed/stdlib/asyncio/events.pyi

@@ -543,10 +543,18 @@ class AbstractEventLoopPolicy:
     @abstractmethod
     def new_event_loop(self) -> AbstractEventLoop: ...
     # Child processes handling (Unix only).
-    @abstractmethod
-    def get_child_watcher(self) -> AbstractChildWatcher: ...
-    @abstractmethod
-    def set_child_watcher(self, watcher: AbstractChildWatcher) -> None: ...
+    if sys.version_info >= (3, 12):
+        @abstractmethod
+        @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+        def get_child_watcher(self) -> AbstractChildWatcher: ...
+        @abstractmethod
+        @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+        def set_child_watcher(self, watcher: AbstractChildWatcher) -> None: ...
+    else:
+        @abstractmethod
+        def get_child_watcher(self) -> AbstractChildWatcher: ...
+        @abstractmethod
+        def set_child_watcher(self, watcher: AbstractChildWatcher) -> None: ...
 
 class BaseDefaultEventLoopPolicy(AbstractEventLoopPolicy, metaclass=ABCMeta):
     def get_event_loop(self) -> AbstractEventLoop: ...

mypy/typeshed/stdlib/asyncio/tasks.pyi

@@ -375,14 +375,16 @@ else:
 
 if sys.version_info >= (3, 12):
     _TaskCompatibleCoro: TypeAlias = Coroutine[Any, Any, _T_co]
+elif sys.version_info >= (3, 9):
+    _TaskCompatibleCoro: TypeAlias = Generator[_TaskYieldType, None, _T_co] | Coroutine[Any, Any, _T_co]
 else:
     _TaskCompatibleCoro: TypeAlias = Generator[_TaskYieldType, None, _T_co] | Awaitable[_T_co]
 
 # mypy and pyright complain that a subclass of an invariant class shouldn't be covariant.
 # While this is true in general, here it's sort-of okay to have a covariant subclass,
 # since the only reason why `asyncio.Future` is invariant is the `set_result()` method,
 # and `asyncio.Task.set_result()` always raises.
-class Task(Future[_T_co]):  # type: ignore[type-var]  # pyright: ignore[reportGeneralTypeIssues]
+class Task(Future[_T_co]):  # type: ignore[type-var]  # pyright: ignore[reportInvalidTypeArguments]
     if sys.version_info >= (3, 12):
         def __init__(
             self,

mypy/typeshed/stdlib/builtins.pyi

@@ -437,7 +437,7 @@ class str(Sequence[str]):
     def capitalize(self) -> str: ...  # type: ignore[misc]
     def casefold(self) -> str: ...  # type: ignore[misc]
     def center(self, __width: SupportsIndex, __fillchar: str = " ") -> str: ...  # type: ignore[misc]
-    def count(self, x: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
+    def count(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
     def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes: ...
     def endswith(
         self, __suffix: str | tuple[str, ...], __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...
@@ -1130,7 +1130,7 @@ class property:
 class _NotImplementedType(Any):
     # A little weird, but typing the __call__ as NotImplemented makes the error message
     # for NotImplemented() much better
-    __call__: NotImplemented  # type: ignore[valid-type]  # pyright: ignore[reportGeneralTypeIssues]
+    __call__: NotImplemented  # type: ignore[valid-type]  # pyright: ignore[reportInvalidTypeForm]
 
 NotImplemented: _NotImplementedType
 
@@ -1544,9 +1544,9 @@ def quit(code: sys._ExitCode = None) -> NoReturn: ...
 
 class reversed(Iterator[_T]):
     @overload
-    def __init__(self, __sequence: Reversible[_T]) -> None: ...
+    def __new__(cls, __sequence: Reversible[_T]) -> Iterator[_T]: ...  # type: ignore[misc]
     @overload
-    def __init__(self, __sequence: SupportsLenAndGetItem[_T]) -> None: ...
+    def __new__(cls, __sequence: SupportsLenAndGetItem[_T]) -> Iterator[_T]: ...  # type: ignore[misc]
     def __iter__(self) -> Self: ...
     def __next__(self) -> _T: ...
     def __length_hint__(self) -> int: ...

mypy/typeshed/stdlib/cProfile.pyi

@@ -1,3 +1,4 @@
+import _lsprof
 from _typeshed import StrOrBytesPath, Unused
 from collections.abc import Callable
 from types import CodeType
@@ -15,13 +16,8 @@ _T = TypeVar("_T")
 _P = ParamSpec("_P")
 _Label: TypeAlias = tuple[str, int, str]
 
-class Profile:
+class Profile(_lsprof.Profiler):
     stats: dict[_Label, tuple[int, int, int, int, dict[_Label, tuple[int, int, int, int]]]]  # undocumented
-    def __init__(
-        self, timer: Callable[[], float] = ..., timeunit: float = ..., subcalls: bool = ..., builtins: bool = ...
-    ) -> None: ...
-    def enable(self) -> None: ...
-    def disable(self) -> None: ...
     def print_stats(self, sort: str | int = -1) -> None: ...
     def dump_stats(self, file: StrOrBytesPath) -> None: ...
     def create_stats(self) -> None: ...

mypy/typeshed/stdlib/datetime.pyi

@@ -1,16 +1,14 @@
 import sys
 from abc import abstractmethod
 from time import struct_time
-from typing import ClassVar, Literal, NamedTuple, NoReturn, SupportsIndex, TypeVar, final, overload
-from typing_extensions import Self, TypeAlias
+from typing import ClassVar, Literal, NamedTuple, NoReturn, SupportsIndex, final, overload
+from typing_extensions import Self, TypeAlias, deprecated
 
 if sys.version_info >= (3, 11):
     __all__ = ("date", "datetime", "time", "timedelta", "timezone", "tzinfo", "MINYEAR", "MAXYEAR", "UTC")
 elif sys.version_info >= (3, 9):
     __all__ = ("date", "datetime", "time", "timedelta", "timezone", "tzinfo", "MINYEAR", "MAXYEAR")
 
-_D = TypeVar("_D", bound=date)
-
 MINYEAR: Literal[1]
 MAXYEAR: Literal[9999]
 
@@ -90,11 +88,11 @@ class date:
     def __add__(self, __value: timedelta) -> Self: ...
     def __radd__(self, __value: timedelta) -> Self: ...
     @overload
-    def __sub__(self, __value: timedelta) -> Self: ...
-    @overload
     def __sub__(self, __value: datetime) -> NoReturn: ...
     @overload
-    def __sub__(self: _D, __value: _D) -> timedelta: ...
+    def __sub__(self, __value: Self) -> timedelta: ...
+    @overload
+    def __sub__(self, __value: timedelta) -> Self: ...
     def __hash__(self) -> int: ...
     def weekday(self) -> int: ...
     def isoweekday(self) -> int: ...
@@ -251,10 +249,12 @@ class datetime(date):
         def fromtimestamp(cls, __timestamp: float, tz: _TzInfo | None = ...) -> Self: ...
 
     @classmethod
+    @deprecated("Use timezone-aware objects to represent datetimes in UTC; e.g. by calling .fromtimestamp(datetime.UTC)")
     def utcfromtimestamp(cls, __t: float) -> Self: ...
     @classmethod
     def now(cls, tz: _TzInfo | None = None) -> Self: ...
     @classmethod
+    @deprecated("Use timezone-aware objects to represent datetimes in UTC; e.g. by calling .now(datetime.UTC)")
     def utcnow(cls) -> Self: ...
     @classmethod
     def combine(cls, date: _Date, time: _Time, tzinfo: _TzInfo | None = ...) -> Self: ...
@@ -290,6 +290,6 @@ class datetime(date):
     def __eq__(self, __value: object) -> bool: ...
     def __hash__(self) -> int: ...
     @overload  # type: ignore[override]
-    def __sub__(self, __value: timedelta) -> Self: ...
+    def __sub__(self, __value: Self) -> timedelta: ...
     @overload
-    def __sub__(self: _D, __value: _D) -> timedelta: ...
+    def __sub__(self, __value: timedelta) -> Self: ...

mypy/typeshed/stdlib/difflib.pyi

@@ -1,6 +1,6 @@
 import sys
 from collections.abc import Callable, Iterable, Iterator, Sequence
-from typing import Any, AnyStr, Generic, NamedTuple, TypeVar, overload
+from typing import Any, AnyStr, Generic, Literal, NamedTuple, TypeVar, overload
 
 if sys.version_info >= (3, 9):
     from types import GenericAlias
@@ -49,7 +49,7 @@ class SequenceMatcher(Generic[_T]):
         def find_longest_match(self, alo: int, ahi: int, blo: int, bhi: int) -> Match: ...
 
     def get_matching_blocks(self) -> list[Match]: ...
-    def get_opcodes(self) -> list[tuple[str, int, int, int, int]]: ...
+    def get_opcodes(self) -> list[tuple[Literal["replace", "delete", "insert", "equal"], int, int, int, int]]: ...
     def get_grouped_opcodes(self, n: int = 3) -> Iterable[list[tuple[str, int, int, int, int]]]: ...
     def ratio(self) -> float: ...
     def quick_ratio(self) -> float: ...