Sync typeshed

Source commit:
python/typeshed@ea0ae21

mypy/typeshed/stdlib/_typeshed/__init__.pyi

@@ -36,6 +36,9 @@ AnyStr_co = TypeVar("AnyStr_co", str, bytes, covariant=True)  # noqa: Y001
 # "Incomplete | None" instead of "Any | None".
 Incomplete: TypeAlias = Any
 
+# To describe a function parameter that is unused and will work with anything.
+Unused: TypeAlias = object
+
 # stable
 class IdentityFunction(Protocol):
     def __call__(self, __x: _T) -> _T: ...
@@ -205,6 +208,7 @@ class HasFileno(Protocol):
 
 FileDescriptor: TypeAlias = int  # stable
 FileDescriptorLike: TypeAlias = int | HasFileno  # stable
+FileDescriptorOrPath: TypeAlias = int | StrOrBytesPath
 
 # stable
 class SupportsRead(Protocol[_T_co]):

mypy/typeshed/stdlib/builtins.pyi

@@ -4,14 +4,14 @@ import types
 from _collections_abc import dict_items, dict_keys, dict_values
 from _typeshed import (
     AnyStr_co,
+    FileDescriptorOrPath,
     OpenBinaryMode,
     OpenBinaryModeReading,
     OpenBinaryModeUpdating,
     OpenBinaryModeWriting,
     OpenTextMode,
     ReadableBuffer,
     Self,
-    StrOrBytesPath,
     SupportsAdd,
     SupportsAiter,
     SupportsAnext,
@@ -54,7 +54,7 @@ from typing import (  # noqa: Y027
     overload,
     type_check_only,
 )
-from typing_extensions import Literal, SupportsIndex, TypeAlias, TypeGuard, final
+from typing_extensions import Literal, LiteralString, SupportsIndex, TypeAlias, TypeGuard, final
 
 if sys.version_info >= (3, 9):
     from types import GenericAlias
@@ -413,20 +413,38 @@ class str(Sequence[str]):
     def __new__(cls: type[Self], object: object = ...) -> Self: ...
     @overload
     def __new__(cls: type[Self], object: ReadableBuffer, encoding: str = ..., errors: str = ...) -> Self: ...
+    @overload
+    def capitalize(self: LiteralString) -> LiteralString: ...
+    @overload
     def capitalize(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def casefold(self: LiteralString) -> LiteralString: ...
+    @overload
     def casefold(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def center(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
+    @overload
     def center(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...  # type: ignore[misc]
     def count(self, x: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
     def encode(self, encoding: str = ..., errors: str = ...) -> bytes: ...
     def endswith(
         self, __suffix: str | tuple[str, ...], __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...
     ) -> bool: ...
     if sys.version_info >= (3, 8):
+        @overload
+        def expandtabs(self: LiteralString, tabsize: SupportsIndex = ...) -> LiteralString: ...
+        @overload
         def expandtabs(self, tabsize: SupportsIndex = ...) -> str: ...  # type: ignore[misc]
     else:
+        @overload
+        def expandtabs(self: LiteralString, tabsize: int = ...) -> LiteralString: ...
+        @overload
         def expandtabs(self, tabsize: int = ...) -> str: ...  # type: ignore[misc]
 
     def find(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
+    @overload
+    def format(self: LiteralString, *args: LiteralString, **kwargs: LiteralString) -> LiteralString: ...
+    @overload
     def format(self, *args: object, **kwargs: object) -> str: ...  # type: ignore[misc]
     def format_map(self, map: _FormatMapMapping) -> str: ...
     def index(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
@@ -442,53 +460,127 @@ class str(Sequence[str]):
     def isspace(self) -> bool: ...
     def istitle(self) -> bool: ...
     def isupper(self) -> bool: ...
+    @overload
+    def join(self: LiteralString, __iterable: Iterable[LiteralString]) -> LiteralString: ...
+    @overload
     def join(self, __iterable: Iterable[str]) -> str: ...  # type: ignore[misc]
+    @overload
+    def ljust(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
+    @overload
     def ljust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def lower(self: LiteralString) -> LiteralString: ...
+    @overload
     def lower(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def lstrip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
+    @overload
     def lstrip(self, __chars: str | None = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def partition(self: LiteralString, __sep: LiteralString) -> tuple[LiteralString, LiteralString, LiteralString]: ...
+    @overload
     def partition(self, __sep: str) -> tuple[str, str, str]: ...  # type: ignore[misc]
+    @overload
+    def replace(
+        self: LiteralString, __old: LiteralString, __new: LiteralString, __count: SupportsIndex = ...
+    ) -> LiteralString: ...
+    @overload
     def replace(self, __old: str, __new: str, __count: SupportsIndex = ...) -> str: ...  # type: ignore[misc]
     if sys.version_info >= (3, 9):
+        @overload
+        def removeprefix(self: LiteralString, __prefix: LiteralString) -> LiteralString: ...
+        @overload
         def removeprefix(self, __prefix: str) -> str: ...  # type: ignore[misc]
+        @overload
+        def removesuffix(self: LiteralString, __suffix: LiteralString) -> LiteralString: ...
+        @overload
         def removesuffix(self, __suffix: str) -> str: ...  # type: ignore[misc]
 
     def rfind(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
     def rindex(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
+    @overload
+    def rjust(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
+    @overload
     def rjust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def rpartition(self: LiteralString, __sep: LiteralString) -> tuple[LiteralString, LiteralString, LiteralString]: ...
+    @overload
     def rpartition(self, __sep: str) -> tuple[str, str, str]: ...  # type: ignore[misc]
+    @overload
+    def rsplit(self: LiteralString, sep: LiteralString | None = ..., maxsplit: SupportsIndex = ...) -> list[LiteralString]: ...
+    @overload
     def rsplit(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...  # type: ignore[misc]
+    @overload
+    def rstrip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
+    @overload
     def rstrip(self, __chars: str | None = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def split(self: LiteralString, sep: LiteralString | None = ..., maxsplit: SupportsIndex = ...) -> list[LiteralString]: ...
+    @overload
     def split(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...  # type: ignore[misc]
+    @overload
+    def splitlines(self: LiteralString, keepends: bool = ...) -> list[LiteralString]: ...
+    @overload
     def splitlines(self, keepends: bool = ...) -> list[str]: ...  # type: ignore[misc]
     def startswith(
         self, __prefix: str | tuple[str, ...], __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...
     ) -> bool: ...
+    @overload
+    def strip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
+    @overload
     def strip(self, __chars: str | None = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def swapcase(self: LiteralString) -> LiteralString: ...
+    @overload
     def swapcase(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def title(self: LiteralString) -> LiteralString: ...
+    @overload
     def title(self) -> str: ...  # type: ignore[misc]
     def translate(self, __table: _TranslateTable) -> str: ...
+    @overload
+    def upper(self: LiteralString) -> LiteralString: ...
+    @overload
     def upper(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def zfill(self: LiteralString, __width: SupportsIndex) -> LiteralString: ...
+    @overload
     def zfill(self, __width: SupportsIndex) -> str: ...  # type: ignore[misc]
     @staticmethod
     @overload
     def maketrans(__x: dict[int, _T] | dict[str, _T] | dict[str | int, _T]) -> dict[int, _T]: ...
     @staticmethod
     @overload
     def maketrans(__x: str, __y: str, __z: str | None = ...) -> dict[int, int | None]: ...
+    @overload
+    def __add__(self: LiteralString, __s: LiteralString) -> LiteralString: ...
+    @overload
     def __add__(self, __s: str) -> str: ...  # type: ignore[misc]
     # Incompatible with Sequence.__contains__
     def __contains__(self, __o: str) -> bool: ...  # type: ignore[override]
     def __eq__(self, __x: object) -> bool: ...
     def __ge__(self, __x: str) -> bool: ...
     def __getitem__(self, __i: SupportsIndex | slice) -> str: ...
     def __gt__(self, __x: str) -> bool: ...
+    @overload
+    def __iter__(self: LiteralString) -> Iterator[LiteralString]: ...
+    @overload
     def __iter__(self) -> Iterator[str]: ...  # type: ignore[misc]
     def __le__(self, __x: str) -> bool: ...
     def __len__(self) -> int: ...
     def __lt__(self, __x: str) -> bool: ...
+    @overload
+    def __mod__(self: LiteralString, __x: LiteralString | tuple[LiteralString, ...]) -> LiteralString: ...
+    @overload
     def __mod__(self, __x: Any) -> str: ...  # type: ignore[misc]
+    @overload
+    def __mul__(self: LiteralString, __n: SupportsIndex) -> LiteralString: ...
+    @overload
     def __mul__(self, __n: SupportsIndex) -> str: ...  # type: ignore[misc]
     def __ne__(self, __x: object) -> bool: ...
+    @overload
+    def __rmul__(self: LiteralString, __n: SupportsIndex) -> LiteralString: ...
+    @overload
     def __rmul__(self, __n: SupportsIndex) -> str: ...  # type: ignore[misc]
     def __getnewargs__(self) -> tuple[str]: ...
 
@@ -1320,13 +1412,12 @@ def next(__i: SupportsNext[_T]) -> _T: ...
 def next(__i: SupportsNext[_T], __default: _VT) -> _T | _VT: ...
 def oct(__number: int | SupportsIndex) -> str: ...
 
-_OpenFile = StrOrBytesPath | int  # noqa: Y026  # TODO: Use TypeAlias once mypy bugs are fixed
 _Opener: TypeAlias = Callable[[str, int], int]
 
 # Text mode: always returns a TextIOWrapper
 @overload
 def open(
-    file: _OpenFile,
+    file: FileDescriptorOrPath,
     mode: OpenTextMode = ...,
     buffering: int = ...,
     encoding: str | None = ...,
@@ -1339,7 +1430,7 @@ def open(
 # Unbuffered binary mode: returns a FileIO
 @overload
 def open(
-    file: _OpenFile,
+    file: FileDescriptorOrPath,
     mode: OpenBinaryMode,
     buffering: Literal[0],
     encoding: None = ...,
@@ -1352,7 +1443,7 @@ def open(
 # Buffering is on: return BufferedRandom, BufferedReader, or BufferedWriter
 @overload
 def open(
-    file: _OpenFile,
+    file: FileDescriptorOrPath,
     mode: OpenBinaryModeUpdating,
     buffering: Literal[-1, 1] = ...,
     encoding: None = ...,
@@ -1363,7 +1454,7 @@ def open(
 ) -> BufferedRandom: ...
 @overload
 def open(
-    file: _OpenFile,
+    file: FileDescriptorOrPath,
     mode: OpenBinaryModeWriting,
     buffering: Literal[-1, 1] = ...,
     encoding: None = ...,
@@ -1374,7 +1465,7 @@ def open(
 ) -> BufferedWriter: ...
 @overload
 def open(
-    file: _OpenFile,
+    file: FileDescriptorOrPath,
     mode: OpenBinaryModeReading,
     buffering: Literal[-1, 1] = ...,
     encoding: None = ...,
@@ -1387,7 +1478,7 @@ def open(
 # Buffering cannot be determined: fall back to BinaryIO
 @overload
 def open(
-    file: _OpenFile,
+    file: FileDescriptorOrPath,
     mode: OpenBinaryMode,
     buffering: int = ...,
     encoding: None = ...,
@@ -1400,7 +1491,7 @@ def open(
 # Fallback if mode is not specified
 @overload
 def open(
-    file: _OpenFile,
+    file: FileDescriptorOrPath,
     mode: str,
     buffering: int = ...,
     encoding: str | None = ...,
@@ -1565,11 +1656,11 @@ _SupportsSumNoDefaultT = TypeVar("_SupportsSumNoDefaultT", bound=_SupportsSumWit
 # Instead, we special-case the most common examples of this: bool and literal integers.
 if sys.version_info >= (3, 8):
     @overload
-    def sum(__iterable: Iterable[bool], start: int = ...) -> int: ...  # type: ignore[misc]
+    def sum(__iterable: Iterable[bool | _LiteralInteger], start: int = ...) -> int: ...  # type: ignore[misc]
 
 else:
     @overload
-    def sum(__iterable: Iterable[bool], __start: int = ...) -> int: ...  # type: ignore[misc]
+    def sum(__iterable: Iterable[bool | _LiteralInteger], __start: int = ...) -> int: ...  # type: ignore[misc]
 
 @overload
 def sum(__iterable: Iterable[_SupportsSumNoDefaultT]) -> _SupportsSumNoDefaultT | Literal[0]: ...

mypy/typeshed/stdlib/compileall.pyi

@@ -8,7 +8,7 @@ __all__ = ["compile_dir", "compile_file", "compile_path"]
 class _SupportsSearch(Protocol):
     def search(self, string: str) -> Any: ...
 
-if sys.version_info >= (3, 9):
+if sys.version_info >= (3, 10):
     def compile_dir(
         dir: StrPath,
         maxlevels: int | None = ...,
@@ -21,7 +21,7 @@ if sys.version_info >= (3, 9):
         workers: int = ...,
         invalidation_mode: PycInvalidationMode | None = ...,
         *,
-        stripdir: str | None = ...,  # TODO: change to StrPath | None once https://bugs.python.org/issue40447 is resolved
+        stripdir: StrPath | None = ...,
         prependdir: StrPath | None = ...,
         limit_sl_dest: StrPath | None = ...,
         hardlink_dupes: bool = ...,
@@ -36,7 +36,41 @@ if sys.version_info >= (3, 9):
         optimize: int = ...,
         invalidation_mode: PycInvalidationMode | None = ...,
         *,
-        stripdir: str | None = ...,  # TODO: change to StrPath | None once https://bugs.python.org/issue40447 is resolved
+        stripdir: StrPath | None = ...,
+        prependdir: StrPath | None = ...,
+        limit_sl_dest: StrPath | None = ...,
+        hardlink_dupes: bool = ...,
+    ) -> int: ...
+
+elif sys.version_info >= (3, 9):
+    def compile_dir(
+        dir: StrPath,
+        maxlevels: int | None = ...,
+        ddir: StrPath | None = ...,
+        force: bool = ...,
+        rx: _SupportsSearch | None = ...,
+        quiet: int = ...,
+        legacy: bool = ...,
+        optimize: int = ...,
+        workers: int = ...,
+        invalidation_mode: PycInvalidationMode | None = ...,
+        *,
+        stripdir: str | None = ...,  # https://bugs.python.org/issue40447
+        prependdir: StrPath | None = ...,
+        limit_sl_dest: StrPath | None = ...,
+        hardlink_dupes: bool = ...,
+    ) -> int: ...
+    def compile_file(
+        fullname: StrPath,
+        ddir: StrPath | None = ...,
+        force: bool = ...,
+        rx: _SupportsSearch | None = ...,
+        quiet: int = ...,
+        legacy: bool = ...,
+        optimize: int = ...,
+        invalidation_mode: PycInvalidationMode | None = ...,
+        *,
+        stripdir: str | None = ...,  # https://bugs.python.org/issue40447
         prependdir: StrPath | None = ...,
         limit_sl_dest: StrPath | None = ...,
         hardlink_dupes: bool = ...,

mypy/typeshed/stdlib/contextlib.pyi

@@ -1,6 +1,6 @@
 import abc
 import sys
-from _typeshed import Self, StrOrBytesPath
+from _typeshed import FileDescriptorOrPath, Self
 from abc import abstractmethod
 from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Generator, Iterator
 from types import TracebackType
@@ -193,7 +193,7 @@ else:
         def __exit__(self, *exctype: object) -> None: ...
 
 if sys.version_info >= (3, 11):
-    _T_fd_or_any_path = TypeVar("_T_fd_or_any_path", bound=int | StrOrBytesPath)
+    _T_fd_or_any_path = TypeVar("_T_fd_or_any_path", bound=FileDescriptorOrPath)
 
     class chdir(AbstractContextManager[None], Generic[_T_fd_or_any_path]):
         path: _T_fd_or_any_path

mypy/typeshed/stdlib/ctypes/__init__.pyi

@@ -266,7 +266,11 @@ class Array(Generic[_CT], _CData):
     def _type_(self) -> type[_CT]: ...
     @_type_.setter
     def _type_(self, value: type[_CT]) -> None: ...
-    raw: bytes  # Note: only available if _CT == c_char
+    # Note: only available if _CT == c_char
+    @property
+    def raw(self) -> bytes: ...
+    @raw.setter
+    def raw(self, value: ReadableBuffer) -> None: ...
     value: Any  # Note: bytes if _CT == c_char, str if _CT == c_wchar, unavailable otherwise
     # TODO These methods cannot be annotated correctly at the moment.
     # All of these "Any"s stand for the array's element type, but it's not possible to use _CT

mypy/typeshed/stdlib/distutils/dist.pyi

@@ -1,10 +1,10 @@
-from _typeshed import StrOrBytesPath, SupportsWrite
+from _typeshed import FileDescriptorOrPath, SupportsWrite
 from collections.abc import Iterable, Mapping
 from distutils.cmd import Command
 from typing import IO, Any
 
 class DistributionMetadata:
-    def __init__(self, path: int | StrOrBytesPath | None = ...) -> None: ...
+    def __init__(self, path: FileDescriptorOrPath | None = ...) -> None: ...
     name: str | None
     version: str | None
     author: str | None