Sync typeshed (#15334)

Co-authored-by: Shantanu <[email protected]>
Co-authored-by: hauntsaninja <[email protected]>

Author: github-actions[bot]

mypy/typeshed/stdlib/VERSIONS

@@ -61,7 +61,7 @@ antigravity: 2.7-
 argparse: 2.7-
 array: 2.7-
 ast: 2.7-
-asynchat: 2.7-
+asynchat: 2.7-3.11
 asyncio: 3.4-
 asyncio.mixins: 3.10-
 asyncio.exceptions: 3.8-
@@ -72,7 +72,7 @@ asyncio.taskgroups: 3.11-
 asyncio.threads: 3.9-
 asyncio.timeouts: 3.11-
 asyncio.trsock: 3.8-
-asyncore: 2.7-
+asyncore: 2.7-3.11
 atexit: 2.7-
 audioop: 2.7-
 base64: 2.7-
@@ -228,7 +228,7 @@ shlex: 2.7-
 shutil: 2.7-
 signal: 2.7-
 site: 2.7-
-smtpd: 2.7-
+smtpd: 2.7-3.11
 smtplib: 2.7-
 sndhdr: 2.7-
 socket: 2.7-

mypy/typeshed/stdlib/_collections_abc.pyi

@@ -1,4 +1,5 @@
 import sys
+from abc import abstractmethod
 from types import MappingProxyType
 from typing import (  # noqa: Y022,Y038
     AbstractSet as Set,
@@ -23,11 +24,13 @@ from typing import (  # noqa: Y022,Y038
     MutableMapping as MutableMapping,
     MutableSequence as MutableSequence,
     MutableSet as MutableSet,
+    Protocol,
     Reversible as Reversible,
     Sequence as Sequence,
     Sized as Sized,
     TypeVar,
     ValuesView as ValuesView,
+    runtime_checkable,
 )
 from typing_extensions import final
 
@@ -58,6 +61,8 @@ __all__ = [
     "MutableSequence",
     "ByteString",
 ]
+if sys.version_info >= (3, 12):
+    __all__ += ["Buffer"]
 
 _KT_co = TypeVar("_KT_co", covariant=True)  # Key type covariant containers.
 _VT_co = TypeVar("_VT_co", covariant=True)  # Value type covariant containers.
@@ -79,3 +84,9 @@ class dict_items(ItemsView[_KT_co, _VT_co], Generic[_KT_co, _VT_co]):  # undocum
     if sys.version_info >= (3, 10):
         @property
         def mapping(self) -> MappingProxyType[_KT_co, _VT_co]: ...
+
+if sys.version_info >= (3, 12):
+    @runtime_checkable
+    class Buffer(Protocol):
+        @abstractmethod
+        def __buffer__(self, __flags: int) -> memoryview: ...

mypy/typeshed/stdlib/_ctypes.pyi

@@ -63,6 +63,8 @@ class _CData(metaclass=_CDataMeta):
     def from_param(cls, obj: Any) -> Self | _CArgObject: ...
     @classmethod
     def in_dll(cls, library: CDLL, name: str) -> Self: ...
+    def __buffer__(self, __flags: int) -> memoryview: ...
+    def __release_buffer__(self, __buffer: memoryview) -> None: ...
 
 class _SimpleCData(Generic[_T], _CData):
     value: _T

mypy/typeshed/stdlib/_typeshed/__init__.pyi

@@ -2,17 +2,13 @@
 #
 # See the README.md file in this directory for more information.
 
-import array
-import ctypes
-import mmap
-import pickle
 import sys
-from collections.abc import Awaitable, Callable, Iterable, Set as AbstractSet
+from collections.abc import Awaitable, Callable, Iterable, Sequence, Set as AbstractSet, Sized
 from dataclasses import Field
 from os import PathLike
 from types import FrameType, TracebackType
-from typing import Any, AnyStr, ClassVar, Generic, Protocol, TypeVar
-from typing_extensions import Final, Literal, LiteralString, TypeAlias, final
+from typing import Any, AnyStr, ClassVar, Generic, Protocol, TypeVar, overload
+from typing_extensions import Buffer, Final, Literal, LiteralString, TypeAlias, final
 
 _KT = TypeVar("_KT")
 _KT_co = TypeVar("_KT_co", covariant=True)
@@ -227,42 +223,33 @@ class SupportsNoArgReadline(Protocol[_T_co]):
 class SupportsWrite(Protocol[_T_contra]):
     def write(self, __s: _T_contra) -> object: ...
 
-ReadOnlyBuffer: TypeAlias = bytes  # stable
+# Unfortunately PEP 688 does not allow us to distinguish read-only
+# from writable buffers. We use these aliases for readability for now.
+# Perhaps a future extension of the buffer protocol will allow us to
+# distinguish these cases in the type system.
+ReadOnlyBuffer: TypeAlias = Buffer  # stable
 # Anything that implements the read-write buffer interface.
-# The buffer interface is defined purely on the C level, so we cannot define a normal Protocol
-# for it (until PEP 688 is implemented). Instead we have to list the most common stdlib buffer classes in a Union.
-if sys.version_info >= (3, 8):
-    WriteableBuffer: TypeAlias = (
-        bytearray | memoryview | array.array[Any] | mmap.mmap | ctypes._CData | pickle.PickleBuffer
-    )  # stable
-else:
-    WriteableBuffer: TypeAlias = bytearray | memoryview | array.array[Any] | mmap.mmap | ctypes._CData  # stable
-# Same as _WriteableBuffer, but also includes read-only buffer types (like bytes).
-ReadableBuffer: TypeAlias = ReadOnlyBuffer | WriteableBuffer  # stable
-_BufferWithLen: TypeAlias = ReadableBuffer  # not stable  # noqa: Y047
-
-# Anything that implements the read-write buffer interface, and can be sliced/indexed.
-SliceableBuffer: TypeAlias = bytes | bytearray | memoryview | array.array[Any] | mmap.mmap
-IndexableBuffer: TypeAlias = bytes | bytearray | memoryview | array.array[Any] | mmap.mmap
-# https://github.com/python/typeshed/pull/9115#issuecomment-1304905864
-# Post PEP 688, they should be rewritten as such:
-# from collections.abc import Sequence
-# from typing import Sized, overload
-# class SliceableBuffer(Protocol):
-#     def __buffer__(self, __flags: int) -> memoryview: ...
-#     def __getitem__(self, __slice: slice) -> Sequence[int]: ...
-# class IndexableBuffer(Protocol):
-#     def __buffer__(self, __flags: int) -> memoryview: ...
-#     def __getitem__(self, __i: int) -> int: ...
-# class SupportsGetItemBuffer(SliceableBuffer, IndexableBuffer, Protocol):
-#     def __buffer__(self, __flags: int) -> memoryview: ...
-#     def __contains__(self, __x: Any) -> bool: ...
-#     @overload
-#     def __getitem__(self, __slice: slice) -> Sequence[int]: ...
-#     @overload
-#     def __getitem__(self, __i: int) -> int: ...
-# class SizedBuffer(Sized, Protocol):  # instead of _BufferWithLen
-#     def __buffer__(self, __flags: int) -> memoryview: ...
+WriteableBuffer: TypeAlias = Buffer
+# Same as WriteableBuffer, but also includes read-only buffer types (like bytes).
+ReadableBuffer: TypeAlias = Buffer  # stable
+
+class SliceableBuffer(Buffer, Protocol):
+    def __getitem__(self, __slice: slice) -> Sequence[int]: ...
+
+class IndexableBuffer(Buffer, Protocol):
+    def __getitem__(self, __i: int) -> int: ...
+
+class SupportsGetItemBuffer(SliceableBuffer, IndexableBuffer, Protocol):
+    def __contains__(self, __x: Any) -> bool: ...
+    @overload
+    def __getitem__(self, __slice: slice) -> Sequence[int]: ...
+    @overload
+    def __getitem__(self, __i: int) -> int: ...
+
+class SizedBuffer(Sized, Buffer, Protocol): ...
+
+# for compatibility with third-party stubs that may use this
+_BufferWithLen: TypeAlias = SizedBuffer  # not stable  # noqa: Y047
 
 ExcInfo: TypeAlias = tuple[type[BaseException], BaseException, TracebackType]
 OptExcInfo: TypeAlias = ExcInfo | tuple[None, None, None]

mypy/typeshed/stdlib/argparse.pyi

@@ -2,7 +2,7 @@ import sys
 from collections.abc import Callable, Generator, Iterable, Sequence
 from re import Pattern
 from typing import IO, Any, Generic, NewType, NoReturn, Protocol, TypeVar, overload
-from typing_extensions import Literal, TypeAlias
+from typing_extensions import Literal, Self, TypeAlias
 
 __all__ = [
     "ArgumentParser",
@@ -236,11 +236,19 @@ class HelpFormatter:
     _current_indent: int
     _level: int
     _action_max_length: int
-    _root_section: Any
-    _current_section: Any
+    _root_section: _Section
+    _current_section: _Section
     _whitespace_matcher: Pattern[str]
     _long_break_matcher: Pattern[str]
-    _Section: type[Any]  # Nested class
+
+    class _Section:
+        formatter: HelpFormatter
+        heading: str | None
+        parent: Self | None
+        items: list[tuple[Callable[..., str], Iterable[Any]]]
+        def __init__(self, formatter: HelpFormatter, parent: Self | None, heading: str | None = None) -> None: ...
+        def format_help(self) -> str: ...
+
     def __init__(self, prog: str, indent_increment: int = 2, max_help_position: int = 24, width: int | None = None) -> None: ...
     def _indent(self) -> None: ...
     def _dedent(self) -> None: ...
@@ -249,16 +257,16 @@ class HelpFormatter:
     def end_section(self) -> None: ...
     def add_text(self, text: str | None) -> None: ...
     def add_usage(
-        self, usage: str | None, actions: Iterable[Action], groups: Iterable[_ArgumentGroup], prefix: str | None = None
+        self, usage: str | None, actions: Iterable[Action], groups: Iterable[_MutuallyExclusiveGroup], prefix: str | None = None
     ) -> None: ...
     def add_argument(self, action: Action) -> None: ...
     def add_arguments(self, actions: Iterable[Action]) -> None: ...
     def format_help(self) -> str: ...
     def _join_parts(self, part_strings: Iterable[str]) -> str: ...
     def _format_usage(
-        self, usage: str | None, actions: Iterable[Action], groups: Iterable[_ArgumentGroup], prefix: str | None
+        self, usage: str | None, actions: Iterable[Action], groups: Iterable[_MutuallyExclusiveGroup], prefix: str | None
     ) -> str: ...
-    def _format_actions_usage(self, actions: Iterable[Action], groups: Iterable[_ArgumentGroup]) -> str: ...
+    def _format_actions_usage(self, actions: Iterable[Action], groups: Iterable[_MutuallyExclusiveGroup]) -> str: ...
     def _format_text(self, text: str) -> str: ...
     def _format_action(self, action: Action) -> str: ...
     def _format_action_invocation(self, action: Action) -> str: ...

mypy/typeshed/stdlib/array.pyi

@@ -80,5 +80,7 @@ class array(MutableSequence[_T], Generic[_T]):
     def __rmul__(self, __value: int) -> array[_T]: ...
     def __copy__(self) -> array[_T]: ...
     def __deepcopy__(self, __unused: Any) -> array[_T]: ...
+    def __buffer__(self, __flags: int) -> memoryview: ...
+    def __release_buffer__(self, __buffer: memoryview) -> None: ...
 
 ArrayType = array

mypy/typeshed/stdlib/asyncio/__init__.pyi

@@ -1,5 +1,5 @@
 import sys
-from collections.abc import Coroutine, Generator
+from collections.abc import Awaitable, Coroutine, Generator
 from typing import Any, TypeVar
 from typing_extensions import TypeAlias
 
@@ -36,6 +36,8 @@ _T = TypeVar("_T")
 
 # Aliases imported by multiple submodules in typeshed
 if sys.version_info >= (3, 12):
+    _AwaitableLike: TypeAlias = Awaitable[_T]
     _CoroutineLike: TypeAlias = Coroutine[Any, Any, _T]
 else:
+    _AwaitableLike: TypeAlias = Generator[Any, None, _T] | Awaitable[_T]
     _CoroutineLike: TypeAlias = Generator[Any, None, _T] | Coroutine[Any, Any, _T]

mypy/typeshed/stdlib/asyncio/base_events.pyi

@@ -1,13 +1,13 @@
 import ssl
 import sys
 from _typeshed import FileDescriptorLike, ReadableBuffer, WriteableBuffer
-from asyncio import _CoroutineLike
+from asyncio import _AwaitableLike, _CoroutineLike
 from asyncio.events import AbstractEventLoop, AbstractServer, Handle, TimerHandle, _TaskFactory
 from asyncio.futures import Future
 from asyncio.protocols import BaseProtocol
 from asyncio.tasks import Task
 from asyncio.transports import BaseTransport, DatagramTransport, ReadTransport, SubprocessTransport, Transport, WriteTransport
-from collections.abc import Awaitable, Callable, Generator, Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
 from contextvars import Context
 from socket import AddressFamily, SocketKind, _Address, _RetAddress, socket
 from typing import IO, Any, TypeVar, overload
@@ -64,11 +64,7 @@ class Server(AbstractServer):
 
 class BaseEventLoop(AbstractEventLoop):
     def run_forever(self) -> None: ...
-    # Can't use a union, see mypy issue  # 1873.
-    @overload
-    def run_until_complete(self, future: Generator[Any, None, _T]) -> _T: ...
-    @overload
-    def run_until_complete(self, future: Awaitable[_T]) -> _T: ...
+    def run_until_complete(self, future: _AwaitableLike[_T]) -> _T: ...
     def stop(self) -> None: ...
     def is_running(self) -> bool: ...
     def is_closed(self) -> bool: ...

mypy/typeshed/stdlib/asyncio/events.pyi

@@ -2,13 +2,13 @@ import ssl
 import sys
 from _typeshed import FileDescriptorLike, ReadableBuffer, StrPath, Unused, WriteableBuffer
 from abc import ABCMeta, abstractmethod
-from collections.abc import Awaitable, Callable, Coroutine, Generator, Sequence
+from collections.abc import Callable, Coroutine, Generator, Sequence
 from contextvars import Context
 from socket import AddressFamily, SocketKind, _Address, _RetAddress, socket
 from typing import IO, Any, Protocol, TypeVar, overload
 from typing_extensions import Literal, Self, TypeAlias
 
-from . import _CoroutineLike
+from . import _AwaitableLike, _CoroutineLike
 from .base_events import Server
 from .futures import Future
 from .protocols import BaseProtocol
@@ -113,13 +113,8 @@ class AbstractEventLoop:
     slow_callback_duration: float
     @abstractmethod
     def run_forever(self) -> None: ...
-    # Can't use a union, see mypy issue  # 1873.
-    @overload
     @abstractmethod
-    def run_until_complete(self, future: Generator[Any, None, _T]) -> _T: ...
-    @overload
-    @abstractmethod
-    def run_until_complete(self, future: Awaitable[_T]) -> _T: ...
+    def run_until_complete(self, future: _AwaitableLike[_T]) -> _T: ...
     @abstractmethod
     def stop(self) -> None: ...
     @abstractmethod

mypy/typeshed/stdlib/asyncio/tasks.pyi

@@ -1,6 +1,6 @@
 import concurrent.futures
 import sys
-from collections.abc import Awaitable, Generator, Iterable, Iterator
+from collections.abc import Awaitable, Coroutine, Generator, Iterable, Iterator
 from types import FrameType
 from typing import Any, Generic, TextIO, TypeVar, overload
 from typing_extensions import Literal, TypeAlias
@@ -275,25 +275,24 @@ else:
     ) -> tuple[set[Task[_T]], set[Task[_T]]]: ...
     async def wait_for(fut: _FutureLike[_T], timeout: float | None, *, loop: AbstractEventLoop | None = None) -> _T: ...
 
+if sys.version_info >= (3, 12):
+    _TaskCompatibleCoro: TypeAlias = 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], Generic[_T_co]):  # type: ignore[type-var]  # pyright: ignore[reportGeneralTypeIssues]
     if sys.version_info >= (3, 8):
         def __init__(
-            self,
-            coro: Generator[_TaskYieldType, None, _T_co] | Awaitable[_T_co],
-            *,
-            loop: AbstractEventLoop = ...,
-            name: str | None = ...,
+            self, coro: _TaskCompatibleCoro[_T_co], *, loop: AbstractEventLoop = ..., name: str | None = ...
         ) -> None: ...
     else:
-        def __init__(
-            self, coro: Generator[_TaskYieldType, None, _T_co] | Awaitable[_T_co], *, loop: AbstractEventLoop = ...
-        ) -> None: ...
+        def __init__(self, coro: _TaskCompatibleCoro[_T_co], *, loop: AbstractEventLoop = ...) -> None: ...
     if sys.version_info >= (3, 8):
-        def get_coro(self) -> Generator[_TaskYieldType, None, _T_co] | Awaitable[_T_co]: ...
+        def get_coro(self) -> _TaskCompatibleCoro[_T_co]: ...
         def get_name(self) -> str: ...
         def set_name(self, __value: object) -> None: ...
 

mypy/typeshed/stdlib/binhex.pyi

@@ -1,4 +1,4 @@
-from _typeshed import _BufferWithLen
+from _typeshed import SizedBuffer
 from typing import IO, Any
 from typing_extensions import Literal, TypeAlias
 
@@ -28,9 +28,9 @@ class openrsrc:
 
 class BinHex:
     def __init__(self, name_finfo_dlen_rlen: _FileInfoTuple, ofp: _FileHandleUnion) -> None: ...
-    def write(self, data: _BufferWithLen) -> None: ...
+    def write(self, data: SizedBuffer) -> None: ...
     def close_data(self) -> None: ...
-    def write_rsrc(self, data: _BufferWithLen) -> None: ...
+    def write_rsrc(self, data: SizedBuffer) -> None: ...
     def close(self) -> None: ...
 
 def binhex(inp: str, out: str) -> None: ...