python · JelleZijlstra · May 1, 2024 · May 1, 2024 · Sep 26, 2022 · Oct 29, 2022
diff --git a/mypy/typeshed/stdlib/_typeshed/__init__.pyi b/mypy/typeshed/stdlib/_typeshed/__init__.pyi
@@ -47,10 +47,15 @@ AnyStr_co = TypeVar("AnyStr_co", str, bytes, covariant=True)  # noqa: Y001
 # isn't possible or a type is already partially known. In cases like these,
 # use Incomplete instead of Any as a marker. For example, use
 # "Incomplete | None" instead of "Any | None".
-Incomplete: TypeAlias = Any
+Incomplete: TypeAlias = Any  # stable
 
 # To describe a function parameter that is unused and will work with anything.
-Unused: TypeAlias = object
+Unused: TypeAlias = object  # stable
+
+# Marker for return types that include None, but where forcing the user to
+# check for None can be detrimental. Sometimes called "the Any trick". See
+# CONTRIBUTING.md for more information.
+MaybeNone: TypeAlias = Any  # stable
 
 # Used to mark arguments that default to a sentinel value. This prevents
 # stubtest from complaining about the default value not matching.
@@ -146,13 +151,22 @@ class SupportsKeysAndGetItem(Protocol[_KT, _VT_co]):
     def keys(self) -> Iterable[_KT]: ...
     def __getitem__(self, key: _KT, /) -> _VT_co: ...
 
-# stable
+# This protocol is currently under discussion. Use SupportsContainsAndGetItem
+# instead, if you require the __contains__ method.
+# See https://github.com/python/typeshed/issues/11822.
 class SupportsGetItem(Protocol[_KT_contra, _VT_co]):
     def __contains__(self, x: Any, /) -> bool: ...
     def __getitem__(self, key: _KT_contra, /) -> _VT_co: ...
 
 # stable
-class SupportsItemAccess(SupportsGetItem[_KT_contra, _VT], Protocol[_KT_contra, _VT]):
+class SupportsContainsAndGetItem(Protocol[_KT_contra, _VT_co]):
+    def __contains__(self, x: Any, /) -> bool: ...
+    def __getitem__(self, key: _KT_contra, /) -> _VT_co: ...
+
+# stable
+class SupportsItemAccess(Protocol[_KT_contra, _VT]):
+    def __contains__(self, x: Any, /) -> bool: ...
+    def __getitem__(self, key: _KT_contra, /) -> _VT: ...
     def __setitem__(self, key: _KT_contra, value: _VT, /) -> None: ...
     def __delitem__(self, key: _KT_contra, /) -> None: ...
 

diff --git a/mypy/typeshed/stdlib/asyncio/constants.pyi b/mypy/typeshed/stdlib/asyncio/constants.pyi
@@ -15,6 +15,6 @@ if sys.version_info >= (3, 12):
     THREAD_JOIN_TIMEOUT: Literal[300]
 
 class _SendfileMode(enum.Enum):
-    UNSUPPORTED: int
-    TRY_NATIVE: int
-    FALLBACK: int
+    UNSUPPORTED = 1
+    TRY_NATIVE = 2
+    FALLBACK = 3
diff --git a/mypy/typeshed/stdlib/asyncio/coroutines.pyi b/mypy/typeshed/stdlib/asyncio/coroutines.pyi
@@ -1,7 +1,7 @@
 import sys
 from collections.abc import Awaitable, Callable, Coroutine
 from typing import Any, TypeVar, overload
-from typing_extensions import ParamSpec, TypeGuard
+from typing_extensions import ParamSpec, TypeGuard, TypeIs
 
 if sys.version_info >= (3, 11):
     __all__ = ("iscoroutinefunction", "iscoroutine")
@@ -23,4 +23,4 @@ def iscoroutinefunction(func: Callable[_P, Awaitable[_T]]) -> TypeGuard[Callable
 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) -> TypeGuard[Coroutine[Any, Any, Any]]: ...
+def iscoroutine(obj: object) -> TypeIs[Coroutine[Any, Any, Any]]: ...
diff --git a/mypy/typeshed/stdlib/asyncio/futures.pyi b/mypy/typeshed/stdlib/asyncio/futures.pyi
@@ -3,7 +3,7 @@ from collections.abc import Awaitable, Callable, Generator, Iterable
 from concurrent.futures._base import Future as _ConcurrentFuture
 from contextvars import Context
 from typing import Any, Literal, TypeVar
-from typing_extensions import Self, TypeGuard
+from typing_extensions import Self, TypeIs
 
 from .events import AbstractEventLoop
 
@@ -17,7 +17,7 @@ _T = TypeVar("_T")
 # asyncio defines 'isfuture()' in base_futures.py and re-imports it in futures.py
 # but it leads to circular import error in pytype tool.
 # That's why the import order is reversed.
-def isfuture(obj: object) -> TypeGuard[Future[Any]]: ...
+def isfuture(obj: object) -> TypeIs[Future[Any]]: ...
 
 class Future(Awaitable[_T], Iterable[_T]):
     _state: str

diff --git a/mypy/typeshed/stdlib/asyncio/locks.pyi b/mypy/typeshed/stdlib/asyncio/locks.pyi
@@ -101,10 +101,10 @@ class BoundedSemaphore(Semaphore): ...
 
 if sys.version_info >= (3, 11):
     class _BarrierState(enum.Enum):  # undocumented
-        FILLING: str
-        DRAINING: str
-        RESETTING: str
-        BROKEN: str
+        FILLING = "filling"
+        DRAINING = "draining"
+        RESETTING = "resetting"
+        BROKEN = "broken"
 
     class Barrier(_LoopBoundMixin):
         def __init__(self, parties: int) -> None: ...

diff --git a/mypy/typeshed/stdlib/asyncio/sslproto.pyi b/mypy/typeshed/stdlib/asyncio/sslproto.pyi
@@ -14,17 +14,17 @@ if sys.version_info >= (3, 11):
     SSLAgainErrors: tuple[type[ssl.SSLWantReadError], type[ssl.SSLSyscallError]]
 
     class SSLProtocolState(Enum):
-        UNWRAPPED: str
-        DO_HANDSHAKE: str
-        WRAPPED: str
-        FLUSHING: str
-        SHUTDOWN: str
+        UNWRAPPED = "UNWRAPPED"
+        DO_HANDSHAKE = "DO_HANDSHAKE"
+        WRAPPED = "WRAPPED"
+        FLUSHING = "FLUSHING"
+        SHUTDOWN = "SHUTDOWN"
 
     class AppProtocolState(Enum):
-        STATE_INIT: str
-        STATE_CON_MADE: str
-        STATE_EOF: str
-        STATE_CON_LOST: str
+        STATE_INIT = "STATE_INIT"
+        STATE_CON_MADE = "STATE_CON_MADE"
+        STATE_EOF = "STATE_EOF"
+        STATE_CON_LOST = "STATE_CON_LOST"
 
     def add_flowcontrol_defaults(high: int | None, low: int | None, kb: int) -> tuple[int, int]: ...
 

diff --git a/mypy/typeshed/stdlib/audioop.pyi b/mypy/typeshed/stdlib/audioop.pyi
@@ -1,32 +1,32 @@
-from typing_extensions import TypeAlias
+from typing_extensions import Buffer, TypeAlias
 
 _AdpcmState: TypeAlias = tuple[int, int]
 _RatecvState: TypeAlias = tuple[int, tuple[tuple[int, int], ...]]
 
 class error(Exception): ...
 
-def add(fragment1: bytes, fragment2: bytes, width: int, /) -> bytes: ...
-def adpcm2lin(fragment: bytes, width: int, state: _AdpcmState | None, /) -> tuple[bytes, _AdpcmState]: ...
-def alaw2lin(fragment: bytes, width: int, /) -> bytes: ...
-def avg(fragment: bytes, width: int, /) -> int: ...
-def avgpp(fragment: bytes, width: int, /) -> int: ...
-def bias(fragment: bytes, width: int, bias: int, /) -> bytes: ...
-def byteswap(fragment: bytes, width: int, /) -> bytes: ...
-def cross(fragment: bytes, width: int, /) -> int: ...
-def findfactor(fragment: bytes, reference: bytes, /) -> float: ...
-def findfit(fragment: bytes, reference: bytes, /) -> tuple[int, float]: ...
-def findmax(fragment: bytes, length: int, /) -> int: ...
-def getsample(fragment: bytes, width: int, index: int, /) -> int: ...
-def lin2adpcm(fragment: bytes, width: int, state: _AdpcmState | None, /) -> tuple[bytes, _AdpcmState]: ...
-def lin2alaw(fragment: bytes, width: int, /) -> bytes: ...
-def lin2lin(fragment: bytes, width: int, newwidth: int, /) -> bytes: ...
-def lin2ulaw(fragment: bytes, width: int, /) -> bytes: ...
-def max(fragment: bytes, width: int, /) -> int: ...
-def maxpp(fragment: bytes, width: int, /) -> int: ...
-def minmax(fragment: bytes, width: int, /) -> tuple[int, int]: ...
-def mul(fragment: bytes, width: int, factor: float, /) -> bytes: ...
+def add(fragment1: Buffer, fragment2: Buffer, width: int, /) -> bytes: ...
+def adpcm2lin(fragment: Buffer, width: int, state: _AdpcmState | None, /) -> tuple[bytes, _AdpcmState]: ...
+def alaw2lin(fragment: Buffer, width: int, /) -> bytes: ...
+def avg(fragment: Buffer, width: int, /) -> int: ...
+def avgpp(fragment: Buffer, width: int, /) -> int: ...
+def bias(fragment: Buffer, width: int, bias: int, /) -> bytes: ...
+def byteswap(fragment: Buffer, width: int, /) -> bytes: ...
+def cross(fragment: Buffer, width: int, /) -> int: ...
+def findfactor(fragment: Buffer, reference: Buffer, /) -> float: ...
+def findfit(fragment: Buffer, reference: Buffer, /) -> tuple[int, float]: ...
+def findmax(fragment: Buffer, length: int, /) -> int: ...
+def getsample(fragment: Buffer, width: int, index: int, /) -> int: ...
+def lin2adpcm(fragment: Buffer, width: int, state: _AdpcmState | None, /) -> tuple[bytes, _AdpcmState]: ...
+def lin2alaw(fragment: Buffer, width: int, /) -> bytes: ...
+def lin2lin(fragment: Buffer, width: int, newwidth: int, /) -> bytes: ...
+def lin2ulaw(fragment: Buffer, width: int, /) -> bytes: ...
+def max(fragment: Buffer, width: int, /) -> int: ...
+def maxpp(fragment: Buffer, width: int, /) -> int: ...
+def minmax(fragment: Buffer, width: int, /) -> tuple[int, int]: ...
+def mul(fragment: Buffer, width: int, factor: float, /) -> bytes: ...
 def ratecv(
-    fragment: bytes,
+    fragment: Buffer,
     width: int,
     nchannels: int,
     inrate: int,
@@ -36,8 +36,8 @@ def ratecv(
     weightB: int = 0,
     /,
 ) -> tuple[bytes, _RatecvState]: ...
-def reverse(fragment: bytes, width: int, /) -> bytes: ...
-def rms(fragment: bytes, width: int, /) -> int: ...
-def tomono(fragment: bytes, width: int, lfactor: float, rfactor: float, /) -> bytes: ...
-def tostereo(fragment: bytes, width: int, lfactor: float, rfactor: float, /) -> bytes: ...
-def ulaw2lin(fragment: bytes, width: int, /) -> bytes: ...
+def reverse(fragment: Buffer, width: int, /) -> bytes: ...
+def rms(fragment: Buffer, width: int, /) -> int: ...
+def tomono(fragment: Buffer, width: int, lfactor: float, rfactor: float, /) -> bytes: ...
+def tostereo(fragment: Buffer, width: int, lfactor: float, rfactor: float, /) -> bytes: ...
+def ulaw2lin(fragment: Buffer, width: int, /) -> bytes: ...
diff --git a/mypy/typeshed/stdlib/builtins.pyi b/mypy/typeshed/stdlib/builtins.pyi
@@ -65,6 +65,7 @@ from typing_extensions import (  # noqa: Y023
     Self,
     TypeAlias,
     TypeGuard,
+    TypeIs,
     TypeVarTuple,
     deprecated,
 )
@@ -943,15 +944,25 @@ class dict(MutableMapping[_KT, _VT]):
     @overload
     def __init__(self) -> None: ...
     @overload
-    def __init__(self: dict[str, _VT], **kwargs: _VT) -> None: ...
+    def __init__(self: dict[str, _VT], **kwargs: _VT) -> None: ...  # pyright: ignore[reportInvalidTypeVarUse]  #11780
     @overload
     def __init__(self, map: SupportsKeysAndGetItem[_KT, _VT], /) -> None: ...
     @overload
-    def __init__(self: dict[str, _VT], map: SupportsKeysAndGetItem[str, _VT], /, **kwargs: _VT) -> None: ...
+    def __init__(
+        self: dict[str, _VT],  # pyright: ignore[reportInvalidTypeVarUse]  #11780
+        map: SupportsKeysAndGetItem[str, _VT],
+        /,
+        **kwargs: _VT,
+    ) -> None: ...
     @overload
     def __init__(self, iterable: Iterable[tuple[_KT, _VT]], /) -> None: ...
     @overload
-    def __init__(self: dict[str, _VT], iterable: Iterable[tuple[str, _VT]], /, **kwargs: _VT) -> None: ...
+    def __init__(
+        self: dict[str, _VT],  # pyright: ignore[reportInvalidTypeVarUse]  #11780
+        iterable: Iterable[tuple[str, _VT]],
+        /,
+        **kwargs: _VT,
+    ) -> None: ...
     # Next two overloads are for dict(string.split(sep) for string in iterable)
     # Cannot be Iterable[Sequence[_T]] or otherwise dict(["foo", "bar", "baz"]) is not an error
     @overload
@@ -1143,7 +1154,7 @@ def any(iterable: Iterable[object], /) -> bool: ...
 def ascii(obj: object, /) -> str: ...
 def bin(number: int | SupportsIndex, /) -> str: ...
 def breakpoint(*args: Any, **kws: Any) -> None: ...
-def callable(obj: object, /) -> TypeGuard[Callable[..., object]]: ...
+def callable(obj: object, /) -> TypeIs[Callable[..., object]]: ...
 def chr(i: int, /) -> str: ...
 
 # We define this here instead of using os.PathLike to avoid import cycle issues.
@@ -1253,6 +1264,8 @@ class filter(Iterator[_T]):
     @overload
     def __new__(cls, function: Callable[[_S], TypeGuard[_T]], iterable: Iterable[_S], /) -> Self: ...
     @overload
+    def __new__(cls, function: Callable[[_S], TypeIs[_T]], iterable: Iterable[_S], /) -> Self: ...
+    @overload
     def __new__(cls, function: Callable[[_T], Any], iterable: Iterable[_T], /) -> Self: ...
     def __iter__(self) -> Self: ...
     def __next__(self) -> _T: ...

diff --git a/mypy/typeshed/stdlib/cgi.pyi b/mypy/typeshed/stdlib/cgi.pyi
@@ -1,4 +1,4 @@
-from _typeshed import SupportsGetItem, SupportsItemAccess, Unused
+from _typeshed import SupportsContainsAndGetItem, SupportsGetItem, SupportsItemAccess, Unused
 from builtins import list as _list, type as _type
 from collections.abc import Iterable, Iterator, Mapping
 from email.message import Message
@@ -85,7 +85,7 @@ class FieldStorage:
         fp: IO[Any] | None = None,
         headers: Mapping[str, str] | Message | None = None,
         outerboundary: bytes = b"",
-        environ: SupportsGetItem[str, str] = ...,
+        environ: SupportsContainsAndGetItem[str, str] = ...,
         keep_blank_values: int = 0,
         strict_parsing: int = 0,
         limit: int | None = None,

diff --git a/mypy/typeshed/stdlib/collections/__init__.pyi b/mypy/typeshed/stdlib/collections/__init__.pyi
@@ -51,15 +51,27 @@ class UserDict(MutableMapping[_KT, _VT]):
     @overload
     def __init__(self, dict: None = None, /) -> None: ...
     @overload
-    def __init__(self: UserDict[str, _VT], dict: None = None, /, **kwargs: _VT) -> None: ...
+    def __init__(
+        self: UserDict[str, _VT], dict: None = None, /, **kwargs: _VT  # pyright: ignore[reportInvalidTypeVarUse]  #11780
+    ) -> None: ...
     @overload
     def __init__(self, dict: SupportsKeysAndGetItem[_KT, _VT], /) -> None: ...
     @overload
-    def __init__(self: UserDict[str, _VT], dict: SupportsKeysAndGetItem[str, _VT], /, **kwargs: _VT) -> None: ...
+    def __init__(
+        self: UserDict[str, _VT],  # pyright: ignore[reportInvalidTypeVarUse]  #11780
+        dict: SupportsKeysAndGetItem[str, _VT],
+        /,
+        **kwargs: _VT,
+    ) -> None: ...
     @overload
     def __init__(self, iterable: Iterable[tuple[_KT, _VT]], /) -> None: ...
     @overload
-    def __init__(self: UserDict[str, _VT], iterable: Iterable[tuple[str, _VT]], /, **kwargs: _VT) -> None: ...
+    def __init__(
+        self: UserDict[str, _VT],  # pyright: ignore[reportInvalidTypeVarUse]  #11780
+        iterable: Iterable[tuple[str, _VT]],
+        /,
+        **kwargs: _VT,
+    ) -> None: ...
     @overload
     def __init__(self: UserDict[str, str], iterable: Iterable[list[str]], /) -> None: ...
     @overload
@@ -389,16 +401,21 @@ class defaultdict(dict[_KT, _VT]):
     @overload
     def __init__(self) -> None: ...
     @overload
-    def __init__(self: defaultdict[str, _VT], **kwargs: _VT) -> None: ...
+    def __init__(self: defaultdict[str, _VT], **kwargs: _VT) -> None: ...  # pyright: ignore[reportInvalidTypeVarUse]  #11780
     @overload
     def __init__(self, default_factory: Callable[[], _VT] | None, /) -> None: ...
     @overload
-    def __init__(self: defaultdict[str, _VT], default_factory: Callable[[], _VT] | None, /, **kwargs: _VT) -> None: ...
+    def __init__(
+        self: defaultdict[str, _VT],  # pyright: ignore[reportInvalidTypeVarUse]  #11780
+        default_factory: Callable[[], _VT] | None,
+        /,
+        **kwargs: _VT,
+    ) -> None: ...
     @overload
     def __init__(self, default_factory: Callable[[], _VT] | None, map: SupportsKeysAndGetItem[_KT, _VT], /) -> None: ...
     @overload
     def __init__(
-        self: defaultdict[str, _VT],
+        self: defaultdict[str, _VT],  # pyright: ignore[reportInvalidTypeVarUse]  #11780
         default_factory: Callable[[], _VT] | None,
         map: SupportsKeysAndGetItem[str, _VT],
         /,
@@ -408,7 +425,7 @@ class defaultdict(dict[_KT, _VT]):
     def __init__(self, default_factory: Callable[[], _VT] | None, iterable: Iterable[tuple[_KT, _VT]], /) -> None: ...
     @overload
     def __init__(
-        self: defaultdict[str, _VT],
+        self: defaultdict[str, _VT],  # pyright: ignore[reportInvalidTypeVarUse]  #11780
         default_factory: Callable[[], _VT] | None,
         iterable: Iterable[tuple[str, _VT]],
         /,