Sync typeshed (#20505)

Source commit:

python/typeshed@9175667

Author: github-actions[bot]

mypy/typeshed/stdlib/_ctypes.pyi

@@ -1,4 +1,5 @@
 import _typeshed
+import builtins
 import sys
 from _typeshed import ReadableBuffer, StrOrBytesPath, WriteableBuffer
 from abc import abstractmethod
@@ -195,24 +196,45 @@ class CFuncPtr(_PointerLike, _CData, metaclass=_PyCFuncPtrType):
 _GetT = TypeVar("_GetT")
 _SetT = TypeVar("_SetT")
 
-# This class is not exposed. It calls itself _ctypes.CField.
-@final
-@type_check_only
-class _CField(Generic[_CT, _GetT, _SetT]):
-    offset: int
-    size: int
-    if sys.version_info >= (3, 10):
-        @overload
-        def __get__(self, instance: None, owner: type[Any] | None = None, /) -> Self: ...
-        @overload
-        def __get__(self, instance: Any, owner: type[Any] | None = None, /) -> _GetT: ...
-    else:
+if sys.version_info >= (3, 14):
+    @final
+    class CField(Generic[_CT, _GetT, _SetT]):
+        offset: int
+        size: int
+        name: str
+        type: builtins.type[_CT]
+        byte_offset: int
+        byte_size: int
+        is_bitfield: bool
+        bit_offset: int
+        bit_size: int
+        is_anonymous: bool
         @overload
-        def __get__(self, instance: None, owner: type[Any] | None, /) -> Self: ...
+        def __get__(self, instance: None, owner: builtins.type[Any] | None = None, /) -> Self: ...
         @overload
-        def __get__(self, instance: Any, owner: type[Any] | None, /) -> _GetT: ...
+        def __get__(self, instance: Any, owner: builtins.type[Any] | None = None, /) -> _GetT: ...
+        def __set__(self, instance: Any, value: _SetT, /) -> None: ...
+
+    _CField = CField
 
-    def __set__(self, instance: Any, value: _SetT, /) -> None: ...
+else:
+    @final
+    @type_check_only
+    class _CField(Generic[_CT, _GetT, _SetT]):
+        offset: int
+        size: int
+        if sys.version_info >= (3, 10):
+            @overload
+            def __get__(self, instance: None, owner: type[Any] | None = None, /) -> Self: ...
+            @overload
+            def __get__(self, instance: Any, owner: type[Any] | None = None, /) -> _GetT: ...
+        else:
+            @overload
+            def __get__(self, instance: None, owner: type[Any] | None, /) -> Self: ...
+            @overload
+            def __get__(self, instance: Any, owner: type[Any] | None, /) -> _GetT: ...
+
+        def __set__(self, instance: Any, value: _SetT, /) -> None: ...
 
 # This class is not exposed. It calls itself _ctypes.UnionType.
 @type_check_only

mypy/typeshed/stdlib/argparse.pyi

@@ -93,15 +93,40 @@ class _ActionsContainer:
         version: str = ...,
         **kwargs: Any,
     ) -> Action: ...
-    def add_argument_group(
-        self,
-        title: str | None = None,
-        description: str | None = None,
-        *,
-        prefix_chars: str = ...,
-        argument_default: Any = ...,
-        conflict_handler: str = ...,
-    ) -> _ArgumentGroup: ...
+    if sys.version_info >= (3, 14):
+        @overload
+        def add_argument_group(
+            self,
+            title: str | None = None,
+            description: str | None = None,
+            *,
+            # argument_default's type must be valid for the arguments in the group
+            argument_default: Any = ...,
+            conflict_handler: str = ...,
+        ) -> _ArgumentGroup: ...
+        @overload
+        @deprecated("The `prefix_chars` parameter deprecated since Python 3.14.")
+        def add_argument_group(
+            self,
+            title: str | None = None,
+            description: str | None = None,
+            *,
+            prefix_chars: str,
+            argument_default: Any = ...,
+            conflict_handler: str = ...,
+        ) -> _ArgumentGroup: ...
+    else:
+        def add_argument_group(
+            self,
+            title: str | None = None,
+            description: str | None = None,
+            *,
+            prefix_chars: str = ...,
+            # argument_default's type must be valid for the arguments in the group
+            argument_default: Any = ...,
+            conflict_handler: str = ...,
+        ) -> _ArgumentGroup: ...
+
     def add_mutually_exclusive_group(self, *, required: bool = False) -> _MutuallyExclusiveGroup: ...
     def _add_action(self, action: _ActionT) -> _ActionT: ...
     def _remove_action(self, action: Action) -> None: ...

mypy/typeshed/stdlib/asyncio/coroutines.pyi

@@ -17,12 +17,31 @@ if sys.version_info < (3, 11):
     @deprecated("Deprecated since Python 3.8; removed in Python 3.11. Use `async def` instead.")
     def coroutine(func: _FunctionT) -> _FunctionT: ...
 
-@overload
-def iscoroutinefunction(func: Callable[..., Coroutine[Any, Any, Any]]) -> bool: ...
-@overload
-def iscoroutinefunction(func: Callable[_P, Awaitable[_T]]) -> TypeGuard[Callable[_P, Coroutine[Any, Any, _T]]]: ...
-@overload
-def iscoroutinefunction(func: Callable[_P, object]) -> TypeGuard[Callable[_P, Coroutine[Any, Any, Any]]]: ...
-@overload
-def iscoroutinefunction(func: object) -> TypeGuard[Callable[..., Coroutine[Any, Any, Any]]]: ...
 def iscoroutine(obj: object) -> TypeIs[Coroutine[Any, Any, Any]]: ...
+
+if sys.version_info >= (3, 11):
+    @overload
+    @deprecated("Deprecated since Python 3.14. Use `inspect.iscoroutinefunction()` instead.")
+    def iscoroutinefunction(func: Callable[..., Coroutine[Any, Any, Any]]) -> bool: ...
+    @overload
+    @deprecated("Deprecated since Python 3.14. Use `inspect.iscoroutinefunction()` instead.")
+    def iscoroutinefunction(func: Callable[_P, Awaitable[_T]]) -> TypeGuard[Callable[_P, Coroutine[Any, Any, _T]]]: ...
+    @overload
+    @deprecated("Deprecated since Python 3.14. Use `inspect.iscoroutinefunction()` instead.")
+    def iscoroutinefunction(func: Callable[_P, object]) -> TypeGuard[Callable[_P, Coroutine[Any, Any, Any]]]: ...
+    @overload
+    @deprecated("Deprecated since Python 3.14. Use `inspect.iscoroutinefunction()` instead.")
+    def iscoroutinefunction(func: object) -> TypeGuard[Callable[..., Coroutine[Any, Any, Any]]]: ...
+
+else:
+    # Sometimes needed in Python < 3.11 due to the fact that it supports @coroutine
+    # which was removed in 3.11 which the inspect version doesn't support.
+
+    @overload
+    def iscoroutinefunction(func: Callable[..., Coroutine[Any, Any, Any]]) -> bool: ...
+    @overload
+    def iscoroutinefunction(func: Callable[_P, Awaitable[_T]]) -> TypeGuard[Callable[_P, Coroutine[Any, Any, _T]]]: ...
+    @overload
+    def iscoroutinefunction(func: Callable[_P, object]) -> TypeGuard[Callable[_P, Coroutine[Any, Any, Any]]]: ...
+    @overload
+    def iscoroutinefunction(func: object) -> TypeGuard[Callable[..., Coroutine[Any, Any, Any]]]: ...

mypy/typeshed/stdlib/codecs.pyi

@@ -5,7 +5,7 @@ from _typeshed import ReadableBuffer
 from abc import abstractmethod
 from collections.abc import Callable, Generator, Iterable
 from typing import Any, BinaryIO, ClassVar, Final, Literal, Protocol, TextIO, overload, type_check_only
-from typing_extensions import Self, TypeAlias, disjoint_base
+from typing_extensions import Self, TypeAlias, deprecated, disjoint_base
 
 __all__ = [
     "register",
@@ -191,6 +191,7 @@ def getincrementaldecoder(encoding: _BufferedEncoding) -> _BufferedIncrementalDe
 def getincrementaldecoder(encoding: str) -> _IncrementalDecoder: ...
 def getreader(encoding: str) -> _StreamReader: ...
 def getwriter(encoding: str) -> _StreamWriter: ...
+@deprecated("Deprecated since Python 3.14. Use `open()` instead.")
 def open(
     filename: str, mode: str = "r", encoding: str | None = None, errors: str = "strict", buffering: int = -1
 ) -> StreamReaderWriter: ...

mypy/typeshed/stdlib/ctypes/__init__.pyi

@@ -55,6 +55,9 @@ if sys.version_info >= (3, 14):
 else:
     from _ctypes import POINTER as POINTER, pointer as pointer
 
+if sys.version_info >= (3, 14):
+    CField = _CField
+
 DEFAULT_MODE: Final[int]
 
 class ArgumentError(Exception): ...

mypy/typeshed/stdlib/enum.pyi

@@ -255,6 +255,7 @@ _auto_null: Any
 class Flag(Enum):
     _name_: str | None  # type: ignore[assignment]
     _value_: int
+    _numeric_repr_: Callable[[int], str]
     @_magic_enum_attr
     def name(self) -> str | None: ...  # type: ignore[override]
     @_magic_enum_attr

mypy/typeshed/stdlib/imaplib.pyi

@@ -61,7 +61,7 @@ class IMAP4:
     def socket(self) -> _socket: ...
     def recent(self) -> _CommandResults: ...
     def response(self, code: str) -> _CommandResults: ...
-    def append(self, mailbox: str, flags: str, date_time: str, message: ReadableBuffer) -> str: ...
+    def append(self, mailbox: str, flags: str, date_time: str, message: ReadableBuffer) -> tuple[str, _list[bytes]]: ...
     def authenticate(self, mechanism: str, authobject: Callable[[bytes], bytes | None]) -> tuple[str, str]: ...
     def capability(self) -> _CommandResults: ...
     def check(self) -> _CommandResults: ...

mypy/typeshed/stdlib/optparse.pyi

@@ -204,7 +204,7 @@ class OptionContainer:
         callback_kwargs: dict[str, Any] | None = None,
         help: str | None = None,
         metavar: str | None = None,
-        **kwargs,  # Allow arbitrary keyword arguments for user defined option_class
+        **kwargs: Any,  # Allow arbitrary keyword arguments for user defined option_class
     ) -> Option: ...
     def add_options(self, option_list: Iterable[Option]) -> None: ...
     def destroy(self) -> None: ...

mypy/typeshed/stdlib/os/__init__.pyi

@@ -710,6 +710,18 @@ class _Environ(MutableMapping[AnyStr, AnyStr], Generic[AnyStr]):
         encodevalue: _EnvironCodeFunc[AnyStr],
         decodevalue: _EnvironCodeFunc[AnyStr],
     ) -> None: ...
+    @overload
+    def get(self, key: AnyStr, default: None = None) -> AnyStr | None: ...
+    @overload
+    def get(self, key: AnyStr, default: AnyStr) -> AnyStr: ...
+    @overload
+    def get(self, key: AnyStr, default: _T) -> AnyStr | _T: ...
+    @overload
+    def pop(self, key: AnyStr) -> AnyStr: ...
+    @overload
+    def pop(self, key: AnyStr, default: AnyStr) -> AnyStr: ...
+    @overload
+    def pop(self, key: AnyStr, default: _T) -> AnyStr | _T: ...
     def setdefault(self, key: AnyStr, value: AnyStr) -> AnyStr: ...
     def copy(self) -> dict[AnyStr, AnyStr]: ...
     def __delitem__(self, key: AnyStr) -> None: ...
@@ -1395,19 +1407,48 @@ class _wrap_close:
     def write(self, s: str, /) -> int: ...
     def writelines(self, lines: Iterable[str], /) -> None: ...
 
-def popen(cmd: str, mode: str = "r", buffering: int = -1) -> _wrap_close: ...
-def spawnl(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: StrOrBytesPath) -> int: ...
-def spawnle(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: Any) -> int: ...  # Imprecise sig
+if sys.version_info >= (3, 14):
+    @deprecated("Soft deprecated. Use the subprocess module instead.")
+    def popen(cmd: str, mode: str = "r", buffering: int = -1) -> _wrap_close: ...
+    @deprecated("Soft deprecated. Use the subprocess module instead.")
+    def spawnl(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: StrOrBytesPath) -> int: ...
+    @deprecated("Soft deprecated. Use the subprocess module instead.")
+    def spawnle(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: Any) -> int: ...  # Imprecise sig
+
+else:
+    def popen(cmd: str, mode: str = "r", buffering: int = -1) -> _wrap_close: ...
+    def spawnl(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: StrOrBytesPath) -> int: ...
+    def spawnle(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: Any) -> int: ...  # Imprecise sig
 
 if sys.platform != "win32":
-    def spawnv(mode: int, file: StrOrBytesPath, args: _ExecVArgs) -> int: ...
-    def spawnve(mode: int, file: StrOrBytesPath, args: _ExecVArgs, env: _ExecEnv) -> int: ...
+    if sys.version_info >= (3, 14):
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnv(mode: int, file: StrOrBytesPath, args: _ExecVArgs) -> int: ...
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnve(mode: int, file: StrOrBytesPath, args: _ExecVArgs, env: _ExecEnv) -> int: ...
+
+    else:
+        def spawnv(mode: int, file: StrOrBytesPath, args: _ExecVArgs) -> int: ...
+        def spawnve(mode: int, file: StrOrBytesPath, args: _ExecVArgs, env: _ExecEnv) -> int: ...
+
+else:
+    if sys.version_info >= (3, 14):
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnv(mode: int, path: StrOrBytesPath, argv: _ExecVArgs, /) -> int: ...
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnve(mode: int, path: StrOrBytesPath, argv: _ExecVArgs, env: _ExecEnv, /) -> int: ...
+
+    else:
+        def spawnv(mode: int, path: StrOrBytesPath, argv: _ExecVArgs, /) -> int: ...
+        def spawnve(mode: int, path: StrOrBytesPath, argv: _ExecVArgs, env: _ExecEnv, /) -> int: ...
+
+if sys.version_info >= (3, 14):
+    @deprecated("Soft deprecated. Use the subprocess module instead.")
+    def system(command: StrOrBytesPath) -> int: ...
 
 else:
-    def spawnv(mode: int, path: StrOrBytesPath, argv: _ExecVArgs, /) -> int: ...
-    def spawnve(mode: int, path: StrOrBytesPath, argv: _ExecVArgs, env: _ExecEnv, /) -> int: ...
+    def system(command: StrOrBytesPath) -> int: ...
 
-def system(command: StrOrBytesPath) -> int: ...
 @final
 class times_result(structseq[float], tuple[float, float, float, float, float]):
     if sys.version_info >= (3, 10):
@@ -1440,10 +1481,22 @@ if sys.platform == "win32":
         def startfile(filepath: StrOrBytesPath, operation: str = ...) -> None: ...
 
 else:
-    def spawnlp(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: StrOrBytesPath) -> int: ...
-    def spawnlpe(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: Any) -> int: ...  # Imprecise signature
-    def spawnvp(mode: int, file: StrOrBytesPath, args: _ExecVArgs) -> int: ...
-    def spawnvpe(mode: int, file: StrOrBytesPath, args: _ExecVArgs, env: _ExecEnv) -> int: ...
+    if sys.version_info >= (3, 14):
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnlp(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: StrOrBytesPath) -> int: ...
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnlpe(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: Any) -> int: ...  # Imprecise signature
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnvp(mode: int, file: StrOrBytesPath, args: _ExecVArgs) -> int: ...
+        @deprecated("Soft deprecated. Use the subprocess module instead.")
+        def spawnvpe(mode: int, file: StrOrBytesPath, args: _ExecVArgs, env: _ExecEnv) -> int: ...
+
+    else:
+        def spawnlp(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: StrOrBytesPath) -> int: ...
+        def spawnlpe(mode: int, file: StrOrBytesPath, arg0: StrOrBytesPath, *args: Any) -> int: ...  # Imprecise signature
+        def spawnvp(mode: int, file: StrOrBytesPath, args: _ExecVArgs) -> int: ...
+        def spawnvpe(mode: int, file: StrOrBytesPath, args: _ExecVArgs, env: _ExecEnv) -> int: ...
+
     def wait() -> tuple[int, int]: ...  # Unix only
     # Added to MacOS in 3.13
     if sys.platform != "darwin" or sys.version_info >= (3, 13):

mypy/typeshed/stdlib/pathlib/__init__.pyi

@@ -90,6 +90,7 @@ class PurePath(PathLike[str]):
     def __rtruediv__(self, key: StrPath) -> Self: ...
     def __bytes__(self) -> bytes: ...
     def as_posix(self) -> str: ...
+    @deprecated("Deprecated since Python 3.14; will be removed in Python 3.19. Use `Path.as_uri()` instead.")
     def as_uri(self) -> str: ...
     def is_absolute(self) -> bool: ...
     if sys.version_info >= (3, 13):
@@ -345,6 +346,8 @@ class Path(PurePath):
             self, top_down: bool = True, on_error: Callable[[OSError], object] | None = None, follow_symlinks: bool = False
         ) -> Iterator[tuple[Self, list[str], list[str]]]: ...
 
+    def as_uri(self) -> str: ...
+
 class PosixPath(Path, PurePosixPath):
     __slots__ = ()