Sync typeshed (#16918)

Source commit:

python/typeshed@48a0497

mypy/typeshed/stdlib/_ast.pyi

@@ -6,6 +6,10 @@ PyCF_ONLY_AST: Literal[1024]
 PyCF_TYPE_COMMENTS: Literal[4096]
 PyCF_ALLOW_TOP_LEVEL_AWAIT: Literal[8192]
 
+# Alias used for fields that must always be valid identifiers
+# A string `x` counts as a valid identifier if both the following are True
+# (1) `x.isidentifier()` evaluates to `True`
+# (2) `keyword.iskeyword(x)` evaluates to `False`
 _Identifier: typing_extensions.TypeAlias = str
 
 class AST:
@@ -499,7 +503,7 @@ class keyword(AST):
 class alias(AST):
     if sys.version_info >= (3, 10):
         __match_args__ = ("name", "asname")
-    name: _Identifier
+    name: str
     asname: _Identifier | None
 
 class withitem(AST):

mypy/typeshed/stdlib/_curses.pyi

@@ -553,5 +553,6 @@ if sys.platform != "win32":
         major: int
         minor: int
         patch: int
+
     ncurses_version: _ncurses_version
     window = _CursesWindow  # undocumented

mypy/typeshed/stdlib/_msi.pyi

@@ -45,6 +45,7 @@ if sys.platform == "win32":
         # Don't exist at runtime
         __new__: None  # type: ignore[assignment]
         __init__: None  # type: ignore[assignment]
+
     def UuidCreate() -> str: ...
     def FCICreate(__cabname: str, __files: list[str]) -> None: ...
     def OpenDatabase(__path: str, __persist: int) -> _Database: ...

mypy/typeshed/stdlib/_thread.pyi

@@ -32,6 +32,7 @@ def get_native_id() -> int: ...  # only available on some platforms
 class _ExceptHookArgs(structseq[Any], tuple[type[BaseException], BaseException | None, TracebackType | None, Thread | None]):
     if sys.version_info >= (3, 10):
         __match_args__: Final = ("exc_type", "exc_value", "exc_traceback", "thread")
+
     @property
     def exc_type(self) -> type[BaseException]: ...
     @property

mypy/typeshed/stdlib/asyncio/sslproto.pyi

@@ -25,6 +25,7 @@ if sys.version_info >= (3, 11):
         STATE_CON_MADE: str
         STATE_EOF: str
         STATE_CON_LOST: str
+
     def add_flowcontrol_defaults(high: int | None, low: int | None, kb: int) -> tuple[int, int]: ...
 
 else:
@@ -155,9 +156,10 @@ class SSLProtocol(_SSLProtocolBase):
     def _check_handshake_timeout(self) -> None: ...
     def _on_handshake_complete(self, handshake_exc: BaseException | None) -> None: ...
     def _fatal_error(self, exc: BaseException, message: str = "Fatal error on transport") -> None: ...
-    def _abort(self) -> None: ...
     if sys.version_info >= (3, 11):
+        def _abort(self, exc: BaseException | None) -> None: ...
         def get_buffer(self, n: int) -> memoryview: ...
     else:
+        def _abort(self) -> None: ...
         def _finalize(self) -> None: ...
         def _process_write_backlog(self) -> None: ...

mypy/typeshed/stdlib/asyncio/unix_events.pyi

@@ -96,6 +96,7 @@ if sys.platform != "win32":
             def __exit__(self, a: type[BaseException] | None, b: BaseException | None, c: types.TracebackType | None) -> None: ...
             def add_child_handler(self, pid: int, callback: Callable[[Unpack[_Ts]], object], *args: Unpack[_Ts]) -> None: ...
             def remove_child_handler(self, pid: int) -> bool: ...
+
     else:
         class SafeChildWatcher(BaseChildWatcher):
             def __enter__(self) -> Self: ...
@@ -120,6 +121,7 @@ if sys.platform != "win32":
         else:
             def get_child_watcher(self) -> AbstractChildWatcher: ...
             def set_child_watcher(self, watcher: AbstractChildWatcher | None) -> None: ...
+
     SelectorEventLoop = _UnixSelectorEventLoop
 
     DefaultEventLoopPolicy = _UnixDefaultEventLoopPolicy
@@ -136,6 +138,7 @@ if sys.platform != "win32":
             def add_child_handler(self, pid: int, callback: Callable[[Unpack[_Ts]], object], *args: Unpack[_Ts]) -> None: ...
             def remove_child_handler(self, pid: int) -> bool: ...
             def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
+
     else:
         class MultiLoopChildWatcher(AbstractChildWatcher):
             def is_active(self) -> bool: ...

mypy/typeshed/stdlib/asyncio/windows_events.pyi

@@ -69,6 +69,7 @@ if sys.platform == "win32":
             def recvfrom_into(
                 self, conn: socket.socket, buf: WriteableBuffer, flags: int = 0
             ) -> futures.Future[tuple[int, socket._RetAddress]]: ...
+
     SelectorEventLoop = _WindowsSelectorEventLoop
 
     class WindowsSelectorEventLoopPolicy(events.BaseDefaultEventLoopPolicy):
@@ -80,4 +81,5 @@ if sys.platform == "win32":
         _loop_factory: ClassVar[type[ProactorEventLoop]]
         def get_child_watcher(self) -> NoReturn: ...
         def set_child_watcher(self, watcher: Any) -> NoReturn: ...
+
     DefaultEventLoopPolicy = WindowsSelectorEventLoopPolicy

mypy/typeshed/stdlib/calendar.pyi

@@ -124,7 +124,7 @@ class HTMLCalendar(Calendar):
     def formatyear(self, theyear: int, width: int = 3) -> str: ...
     def formatyearpage(
         self, theyear: int, width: int = 3, css: str | None = "calendar.css", encoding: str | None = None
-    ) -> str: ...
+    ) -> bytes: ...
 
 class different_locale:
     def __init__(self, locale: _LocaleType) -> None: ...
@@ -166,6 +166,7 @@ if sys.version_info >= (3, 12):
         OCTOBER: Literal[10]
         NOVEMBER: Literal[11]
         DECEMBER: Literal[12]
+
     JANUARY = Month.JANUARY
     FEBRUARY = Month.FEBRUARY
     MARCH = Month.MARCH
@@ -187,6 +188,7 @@ if sys.version_info >= (3, 12):
         FRIDAY: Literal[4]
         SATURDAY: Literal[5]
         SUNDAY: Literal[6]
+
     MONDAY = Day.MONDAY
     TUESDAY = Day.TUESDAY
     WEDNESDAY = Day.WEDNESDAY

mypy/typeshed/stdlib/contextlib.pyi

@@ -118,6 +118,7 @@ class closing(AbstractContextManager[_SupportsCloseT]):
 if sys.version_info >= (3, 10):
     class _SupportsAclose(Protocol):
         def aclose(self) -> Awaitable[object]: ...
+
     _SupportsAcloseT = TypeVar("_SupportsAcloseT", bound=_SupportsAclose)
 
     class aclosing(AbstractAsyncContextManager[_SupportsAcloseT]):

mypy/typeshed/stdlib/dbm/gnu.pyi

@@ -37,4 +37,5 @@ if sys.platform != "win32":
         # Don't exist at runtime
         __new__: None  # type: ignore[assignment]
         __init__: None  # type: ignore[assignment]
+
     def open(__filename: str, __flags: str = "r", __mode: int = 0o666) -> _gdbm: ...

mypy/typeshed/stdlib/dbm/ndbm.pyi

@@ -33,4 +33,5 @@ if sys.platform != "win32":
         # Don't exist at runtime
         __new__: None  # type: ignore[assignment]
         __init__: None  # type: ignore[assignment]
+
     def open(__filename: str, __flags: str = "r", __mode: int = 0o666) -> _dbm: ...

mypy/typeshed/stdlib/enum.pyi

@@ -175,6 +175,7 @@ if sys.version_info >= (3, 11):
         name: str
         clsname: str
         member: Enum | None
+
     _magic_enum_attr = property
 else:
     _magic_enum_attr = types.DynamicClassAttribute
@@ -261,6 +262,7 @@ if sys.version_info >= (3, 11):
         CONTINUOUS: str
         NAMED_FLAGS: str
         UNIQUE: str
+
     CONTINUOUS = EnumCheck.CONTINUOUS
     NAMED_FLAGS = EnumCheck.NAMED_FLAGS
     UNIQUE = EnumCheck.UNIQUE
@@ -274,6 +276,7 @@ if sys.version_info >= (3, 11):
         CONFORM: str
         EJECT: str
         KEEP: str
+
     STRICT = FlagBoundary.STRICT
     CONFORM = FlagBoundary.CONFORM
     EJECT = FlagBoundary.EJECT

mypy/typeshed/stdlib/ftplib.pyi

@@ -31,7 +31,7 @@ class FTP:
     sock: socket | None
     welcome: str | None
     passiveserver: int
-    timeout: int
+    timeout: float | None
     af: int
     lastresp: str
     file: TextIO | None
@@ -48,7 +48,7 @@ class FTP:
             user: str = "",
             passwd: str = "",
             acct: str = "",
-            timeout: float = ...,
+            timeout: float | None = ...,
             source_address: tuple[str, int] | None = None,
             *,
             encoding: str = "utf-8",
@@ -60,7 +60,7 @@ class FTP:
             user: str = "",
             passwd: str = "",
             acct: str = "",
-            timeout: float = ...,
+            timeout: float | None = ...,
             source_address: tuple[str, int] | None = None,
         ) -> None: ...
 
@@ -127,7 +127,7 @@ class FTP_TLS(FTP):
             acct: str = "",
             *,
             context: SSLContext | None = None,
-            timeout: float = ...,
+            timeout: float | None = ...,
             source_address: tuple[str, int] | None = None,
             encoding: str = "utf-8",
         ) -> None: ...
@@ -141,7 +141,7 @@ class FTP_TLS(FTP):
             keyfile: str | None = None,
             certfile: str | None = None,
             context: SSLContext | None = None,
-            timeout: float = ...,
+            timeout: float | None = ...,
             source_address: tuple[str, int] | None = None,
             *,
             encoding: str = "utf-8",
@@ -156,7 +156,7 @@ class FTP_TLS(FTP):
             keyfile: str | None = None,
             certfile: str | None = None,
             context: SSLContext | None = None,
-            timeout: float = ...,
+            timeout: float | None = ...,
             source_address: tuple[str, int] | None = None,
         ) -> None: ...
     ssl_version: int

mypy/typeshed/stdlib/grp.pyi

@@ -7,6 +7,7 @@ if sys.platform != "win32":
     class struct_group(structseq[Any], tuple[str, str | None, int, list[str]]):
         if sys.version_info >= (3, 10):
             __match_args__: Final = ("gr_name", "gr_passwd", "gr_gid", "gr_mem")
+
         @property
         def gr_name(self) -> str: ...
         @property

mypy/typeshed/stdlib/importlib/metadata/__init__.pyi

@@ -43,6 +43,7 @@ class PackageNotFoundError(ModuleNotFoundError):
 if sys.version_info >= (3, 11):
     class DeprecatedTuple:
         def __getitem__(self, item: int) -> str: ...
+
     _EntryPointBase = DeprecatedTuple
 else:
     class _EntryPointBase(NamedTuple):

mypy/typeshed/stdlib/inspect.pyi

@@ -430,6 +430,7 @@ if sys.version_info < (3, 11):
         varargs: str | None
         keywords: str | None
         defaults: tuple[Any, ...]
+
     def getargspec(func: object) -> ArgSpec: ...
 
 class FullArgSpec(NamedTuple):

mypy/typeshed/stdlib/io.pyi

@@ -6,7 +6,7 @@ from _typeshed import FileDescriptorOrPath, ReadableBuffer, WriteableBuffer
 from collections.abc import Callable, Iterable, Iterator
 from os import _Opener
 from types import TracebackType
-from typing import IO, Any, BinaryIO, Literal, TextIO, TypeVar, overload
+from typing import IO, Any, BinaryIO, Literal, Protocol, TextIO, TypeVar, overload, type_check_only
 from typing_extensions import Self
 
 __all__ = [
@@ -94,7 +94,10 @@ class BufferedIOBase(IOBase):
 
 class FileIO(RawIOBase, BinaryIO):  # type: ignore[misc]  # incompatible definitions of writelines in the base classes
     mode: str
-    name: FileDescriptorOrPath
+    # The type of "name" equals the argument passed in to the constructor,
+    # but that can make FileIO incompatible with other I/O types that assume
+    # "name" is a str. In the future, making FileIO generic might help.
+    name: Any
     def __init__(
         self, file: FileDescriptorOrPath, mode: str = ..., closefd: bool = ..., opener: _Opener | None = ...
     ) -> None: ...
@@ -146,16 +149,43 @@ class TextIOBase(IOBase):
     def readlines(self, __hint: int = -1) -> list[str]: ...  # type: ignore[override]
     def read(self, __size: int | None = ...) -> str: ...
 
+@type_check_only
+class _WrappedBuffer(Protocol):
+    # "name" is wrapped by TextIOWrapper. Its type is inconsistent between
+    # the various I/O types, see the comments on TextIOWrapper.name and
+    # TextIO.name.
+    @property
+    def name(self) -> Any: ...
+    @property
+    def closed(self) -> bool: ...
+    def read(self, size: int = ..., /) -> ReadableBuffer: ...
+    # Optional: def read1(self, size: int, /) -> ReadableBuffer: ...
+    def write(self, b: bytes, /) -> object: ...
+    def flush(self) -> object: ...
+    def close(self) -> object: ...
+    def seekable(self) -> bool: ...
+    def readable(self) -> bool: ...
+    def writable(self) -> bool: ...
+    def truncate(self, size: int, /) -> int: ...
+    def fileno(self) -> int: ...
+    def isatty(self) -> int: ...
+    # Optional: Only needs to be present if seekable() returns True.
+    # def seek(self, offset: Literal[0], whence: Literal[2]) -> int: ...
+    # def tell(self) -> int: ...
+
+# TODO: Should be generic over the buffer type, but needs to wait for
+# TypeVar defaults.
 class TextIOWrapper(TextIOBase, TextIO):  # type: ignore[misc]  # incompatible definitions of write in the base classes
     def __init__(
         self,
-        buffer: IO[bytes],
+        buffer: _WrappedBuffer,
         encoding: str | None = ...,
         errors: str | None = ...,
         newline: str | None = ...,
         line_buffering: bool = ...,
         write_through: bool = ...,
     ) -> None: ...
+    # Equals the "buffer" argument passed in to the constructor.
     @property
     def buffer(self) -> BinaryIO: ...
     @property
@@ -180,7 +210,11 @@ class TextIOWrapper(TextIOBase, TextIO):  # type: ignore[misc]  # incompatible d
     def writelines(self, __lines: Iterable[str]) -> None: ...  # type: ignore[override]
     def readline(self, __size: int = -1) -> str: ...  # type: ignore[override]
     def readlines(self, __hint: int = -1) -> list[str]: ...  # type: ignore[override]
-    def seek(self, __cookie: int, __whence: int = 0) -> int: ...  # stubtest needs this
+    # Equals the "buffer" argument passed in to the constructor.
+    def detach(self) -> BinaryIO: ...
+    # TextIOWrapper's version of seek only supports a limited subset of
+    # operations.
+    def seek(self, __cookie: int, __whence: int = 0) -> int: ...
 
 class StringIO(TextIOWrapper):
     def __init__(self, initial_value: str | None = ..., newline: str | None = ...) -> None: ...

mypy/typeshed/stdlib/msilib/__init__.pyi

@@ -56,6 +56,7 @@ if sys.platform == "win32":
         def gen_id(self, file: str) -> str: ...
         def append(self, full: str, file: str, logical: str) -> tuple[int, str]: ...
         def commit(self, db: _Database) -> None: ...
+
     _directories: set[str]
 
     class Directory:

mypy/typeshed/stdlib/multiprocessing/reduction.pyi

@@ -86,4 +86,5 @@ class AbstractReducer(metaclass=ABCMeta):
         sendfds = _sendfds
         recvfds = _recvfds
         DupFd = _DupFd
+
     def __init__(self, *args: Unused) -> None: ...

mypy/typeshed/stdlib/os/__init__.pyi

@@ -341,6 +341,7 @@ class stat_result(structseq[float], tuple[int, int, int, int, int, int, int, flo
     # More items may be added at the end by some implementations.
     if sys.version_info >= (3, 10):
         __match_args__: Final = ("st_mode", "st_ino", "st_dev", "st_nlink", "st_uid", "st_gid", "st_size")
+
     @property
     def st_mode(self) -> int: ...  # protection bits,
     @property
@@ -446,6 +447,7 @@ class statvfs_result(structseq[int], tuple[int, int, int, int, int, int, int, in
             "f_flag",
             "f_namemax",
         )
+
     @property
     def f_bsize(self) -> int: ...
     @property
@@ -488,6 +490,7 @@ def umask(__mask: int) -> int: ...
 class uname_result(structseq[str], tuple[str, str, str, str, str]):
     if sys.version_info >= (3, 10):
         __match_args__: Final = ("sysname", "nodename", "release", "version", "machine")
+
     @property
     def sysname(self) -> str: ...
     @property
@@ -704,6 +707,7 @@ if sys.platform != "win32":
 class terminal_size(structseq[int], tuple[int, int]):
     if sys.version_info >= (3, 10):
         __match_args__: Final = ("columns", "lines")
+
     @property
     def columns(self) -> int: ...
     @property
@@ -925,6 +929,7 @@ def system(command: StrOrBytesPath) -> int: ...
 class times_result(structseq[float], tuple[float, float, float, float, float]):
     if sys.version_info >= (3, 10):
         __match_args__: Final = ("user", "system", "children_user", "children_system", "elapsed")
+
     @property
     def user(self) -> float: ...
     @property
@@ -962,6 +967,7 @@ else:
         class waitid_result(structseq[int], tuple[int, int, int, int, int]):
             if sys.version_info >= (3, 10):
                 __match_args__: Final = ("si_pid", "si_uid", "si_signo", "si_status", "si_code")
+
             @property
             def si_pid(self) -> int: ...
             @property
@@ -1022,6 +1028,7 @@ if sys.platform != "win32":
     class sched_param(structseq[int], tuple[int]):
         if sys.version_info >= (3, 10):
             __match_args__: Final = ("sched_priority",)
+
         def __new__(cls, sched_priority: int) -> Self: ...
         @property
         def sched_priority(self) -> int: ...