Merge branch 'master' into 585

Author: AlexWaygood

.flake8

@@ -18,7 +18,6 @@
 #       F405 defined from star imports
 
 # Rules that we'd like to enable in the future:
-#       Y026 Use typing_extensions.TypeAlias for type aliases (blocked by #4913)
 #       Y027 Disallow importing typing.ContextManager, typing.OrderedDict &
 #            typing_extensions.OrderedDict (cannot be globally enabled while typeshed
 #            still contains stubs supporting Python 2).
@@ -32,12 +31,12 @@
 [flake8]
 per-file-ignores =
   *.py: E203, E501
-  *.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F822, Y026, Y037
+  *.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F822, Y037
   # Since typing.pyi defines "overload" this is not recognized by flake8 as typing.overload.
   # Unfortunately, flake8 does not allow to "noqa" just a specific error inside the file itself.
   # https://github.com/PyCQA/flake8/issues/1079
   #     F811 redefinition of unused '...'
-  stubs/*.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F822, Y026, Y027, Y037
-  stdlib/typing.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F811, F822, Y026, Y034, Y037
+  stubs/*.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F822, Y027, Y037
+  stdlib/typing.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F811, F822, Y034, Y037
 
 exclude = .venv*,.git,*_pb2.pyi,stdlib/@python2/*

requirements-tests.txt

@@ -4,7 +4,7 @@ pytype==2022.03.29; platform_system != "Windows" and python_version < "3.10"
 black==22.3.0
 flake8==4.0.1
 flake8-bugbear==21.11.29
-flake8-pyi==22.3.0
+flake8-pyi==22.4.0
 # must match .pre-commit-config.yaml
 isort==5.10.1
 tomli==1.2.2

stdlib/_ast.pyi

@@ -172,6 +172,14 @@ class Try(stmt):
     orelse: list[stmt]
     finalbody: list[stmt]
 
+if sys.version_info >= (3, 11):
+    class TryStar(stmt):
+        __match_args__ = ("body", "handlers", "orelse", "finalbody")
+        body: list[stmt]
+        handlers: list[ExceptHandler]
+        orelse: list[stmt]
+        finalbody: list[stmt]
+
 class Assert(stmt):
     if sys.version_info >= (3, 10):
         __match_args__ = ("test", "msg")

stdlib/_weakref.pyi

@@ -29,10 +29,10 @@ class ReferenceType(Generic[_T]):
 ref = ReferenceType
 
 def getweakrefcount(__object: Any) -> int: ...
-def getweakrefs(object: Any) -> list[Any]: ...
-@overload
-def proxy(object: _C, callback: Callable[[_C], Any] | None = ...) -> CallableProxyType[_C]: ...
+def getweakrefs(__object: Any) -> list[Any]: ...
 
 # Return CallableProxyType if object is callable, ProxyType otherwise
 @overload
-def proxy(object: _T, callback: Callable[[_T], Any] | None = ...) -> Any: ...
+def proxy(__object: _C, __callback: Callable[[_C], Any] | None = ...) -> CallableProxyType[_C]: ...
+@overload
+def proxy(__object: _T, __callback: Callable[[_T], Any] | None = ...) -> Any: ...

stdlib/builtins.pyi

@@ -218,15 +218,29 @@ class int:
     if sys.version_info >= (3, 10):
         def bit_count(self) -> int: ...
 
-    def to_bytes(self, length: SupportsIndex, byteorder: Literal["little", "big"], *, signed: bool = ...) -> bytes: ...
-    @classmethod
-    def from_bytes(
-        cls: type[Self],
-        bytes: Iterable[SupportsIndex] | SupportsBytes | ReadableBuffer,
-        byteorder: Literal["little", "big"],
-        *,
-        signed: bool = ...,
-    ) -> Self: ...
+    if sys.version_info >= (3, 11):
+        def to_bytes(
+            self, length: SupportsIndex = ..., byteorder: Literal["little", "big"] = ..., *, signed: bool = ...
+        ) -> bytes: ...
+        @classmethod
+        def from_bytes(
+            cls: type[Self],
+            bytes: Iterable[SupportsIndex] | SupportsBytes | ReadableBuffer,
+            byteorder: Literal["little", "big"] = ...,
+            *,
+            signed: bool = ...,
+        ) -> Self: ...
+    else:
+        def to_bytes(self, length: SupportsIndex, byteorder: Literal["little", "big"], *, signed: bool = ...) -> bytes: ...
+        @classmethod
+        def from_bytes(
+            cls: type[Self],
+            bytes: Iterable[SupportsIndex] | SupportsBytes | ReadableBuffer,
+            byteorder: Literal["little", "big"],
+            *,
+            signed: bool = ...,
+        ) -> Self: ...
+
     def __add__(self, __x: int) -> int: ...
     def __sub__(self, __x: int) -> int: ...
     def __mul__(self, __x: int) -> int: ...
@@ -1275,7 +1289,7 @@ def next(__i: SupportsNext[_T]) -> _T: ...
 def next(__i: SupportsNext[_T], __default: _VT) -> _T | _VT: ...
 def oct(__number: int | SupportsIndex) -> str: ...
 
-_OpenFile = StrOrBytesPath | int
+_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
@@ -1394,7 +1408,9 @@ class _SupportsPow3NoneOnly(Protocol[_E, _T_co]):
 class _SupportsPow3(Protocol[_E, _M, _T_co]):
     def __pow__(self, __other: _E, __modulo: _M) -> _T_co: ...
 
-_SupportsSomeKindOfPow = _SupportsPow2[Any, Any] | _SupportsPow3NoneOnly[Any, Any] | _SupportsPow3[Any, Any, Any]
+_SupportsSomeKindOfPow = (  # noqa: Y026  # TODO: Use TypeAlias once mypy bugs are fixed
+    _SupportsPow2[Any, Any] | _SupportsPow3NoneOnly[Any, Any] | _SupportsPow3[Any, Any, Any]
+)
 
 if sys.version_info >= (3, 8):
     @overload
@@ -1783,6 +1799,7 @@ if sys.version_info >= (3, 11):
         @overload
         def split(self: Self, __condition: Callable[[_BaseExceptionT_co], bool]) -> tuple[Self | None, Self | None]: ...
         def derive(self: Self, __excs: Sequence[_BaseExceptionT_co]) -> Self: ...
+        def __class_getitem__(cls, __item: Any) -> GenericAlias: ...
 
     class ExceptionGroup(BaseExceptionGroup[_ExceptionT_co], Exception):
         def __new__(cls: type[Self], __message: str, __exceptions: Sequence[_ExceptionT_co]) -> Self: ...

stdlib/dis.pyi

@@ -39,25 +39,60 @@ __all__ = [
 _HaveCodeType: TypeAlias = types.MethodType | types.FunctionType | types.CodeType | type | Callable[..., Any]
 _HaveCodeOrStringType: TypeAlias = _HaveCodeType | str | bytes
 
-class Instruction(NamedTuple):
-    opname: str
-    opcode: int
-    arg: int | None
-    argval: Any
-    argrepr: str
-    offset: int
-    starts_line: int | None
-    is_jump_target: bool
+if sys.version_info >= (3, 11):
+    class Positions(NamedTuple):
+        lineno: int | None = ...
+        end_lineno: int | None = ...
+        col_offset: int | None = ...
+        end_col_offset: int | None = ...
+
+if sys.version_info >= (3, 11):
+    class Instruction(NamedTuple):
+        opname: str
+        opcode: int
+        arg: int | None
+        argval: Any
+        argrepr: str
+        offset: int
+        starts_line: int | None
+        is_jump_target: bool
+        positions: Positions | None = ...
+
+else:
+    class Instruction(NamedTuple):
+        opname: str
+        opcode: int
+        arg: int | None
+        argval: Any
+        argrepr: str
+        offset: int
+        starts_line: int | None
+        is_jump_target: bool
 
 class Bytecode:
     codeobj: types.CodeType
     first_line: int
-    def __init__(self, x: _HaveCodeOrStringType, *, first_line: int | None = ..., current_offset: int | None = ...) -> None: ...
+    if sys.version_info >= (3, 11):
+        def __init__(
+            self,
+            x: _HaveCodeOrStringType,
+            *,
+            first_line: int | None = ...,
+            current_offset: int | None = ...,
+            show_caches: bool = ...,
+        ) -> None: ...
+        @classmethod
+        def from_traceback(cls: type[Self], tb: types.TracebackType, *, show_caches: bool = ...) -> Self: ...
+    else:
+        def __init__(
+            self, x: _HaveCodeOrStringType, *, first_line: int | None = ..., current_offset: int | None = ...
+        ) -> None: ...
+        @classmethod
+        def from_traceback(cls: type[Self], tb: types.TracebackType) -> Self: ...
+
     def __iter__(self) -> Iterator[Instruction]: ...
     def info(self) -> str: ...
     def dis(self) -> str: ...
-    @classmethod
-    def from_traceback(cls: type[Self], tb: types.TracebackType) -> Self: ...
 
 COMPILER_FLAG_NAMES: dict[int, str]
 
@@ -66,14 +101,27 @@ def findlinestarts(code: _HaveCodeType) -> Iterator[tuple[int, int]]: ...
 def pretty_flags(flags: int) -> str: ...
 def code_info(x: _HaveCodeOrStringType) -> str: ...
 
-if sys.version_info >= (3, 7):
+if sys.version_info >= (3, 11):
+    def dis(
+        x: _HaveCodeOrStringType | None = ..., *, file: IO[str] | None = ..., depth: int | None = ..., show_caches: bool = ...
+    ) -> None: ...
+
+elif sys.version_info >= (3, 7):
     def dis(x: _HaveCodeOrStringType | None = ..., *, file: IO[str] | None = ..., depth: int | None = ...) -> None: ...
 
 else:
     def dis(x: _HaveCodeOrStringType | None = ..., *, file: IO[str] | None = ...) -> None: ...
 
-def distb(tb: types.TracebackType | None = ..., *, file: IO[str] | None = ...) -> None: ...
-def disassemble(co: _HaveCodeType, lasti: int = ..., *, file: IO[str] | None = ...) -> None: ...
-def disco(co: _HaveCodeType, lasti: int = ..., *, file: IO[str] | None = ...) -> None: ...
+if sys.version_info >= (3, 11):
+    def disassemble(co: _HaveCodeType, lasti: int = ..., *, file: IO[str] | None = ..., show_caches: bool = ...) -> None: ...
+    def disco(co: _HaveCodeType, lasti: int = ..., *, file: IO[str] | None = ..., show_caches: bool = ...) -> None: ...
+    def distb(tb: types.TracebackType | None = ..., *, file: IO[str] | None = ..., show_caches: bool = ...) -> None: ...
+    def get_instructions(x: _HaveCodeType, *, first_line: int | None = ..., show_caches: bool = ...) -> Iterator[Instruction]: ...
+
+else:
+    def disassemble(co: _HaveCodeType, lasti: int = ..., *, file: IO[str] | None = ...) -> None: ...
+    def disco(co: _HaveCodeType, lasti: int = ..., *, file: IO[str] | None = ...) -> None: ...
+    def distb(tb: types.TracebackType | None = ..., *, file: IO[str] | None = ...) -> None: ...
+    def get_instructions(x: _HaveCodeType, *, first_line: int | None = ...) -> Iterator[Instruction]: ...
+
 def show_code(co: _HaveCodeType, *, file: IO[str] | None = ...) -> None: ...
-def get_instructions(x: _HaveCodeType, *, first_line: int | None = ...) -> Iterator[Instruction]: ...

stdlib/itertools.pyi

@@ -1,5 +1,5 @@
 import sys
-from _typeshed import Self, _T_co
+from _typeshed import Self
 from collections.abc import Callable, Iterable, Iterator
 from typing import Any, Generic, SupportsComplex, SupportsFloat, SupportsInt, TypeVar, overload
 from typing_extensions import Literal, SupportsIndex, TypeAlias
@@ -10,6 +10,14 @@ if sys.version_info >= (3, 9):
 _T = TypeVar("_T")
 _S = TypeVar("_S")
 _N = TypeVar("_N", int, float, SupportsFloat, SupportsInt, SupportsIndex, SupportsComplex)
+_T_co = TypeVar("_T_co", covariant=True)
+_T1 = TypeVar("_T1")
+_T2 = TypeVar("_T2")
+_T3 = TypeVar("_T3")
+_T4 = TypeVar("_T4")
+_T5 = TypeVar("_T5")
+_T6 = TypeVar("_T6")
+
 _Step: TypeAlias = int | float | SupportsFloat | SupportsInt | SupportsIndex | SupportsComplex
 
 Predicate: TypeAlias = Callable[[_T], object]
@@ -77,9 +85,6 @@ class filterfalse(Iterator[_T], Generic[_T]):
     def __iter__(self: Self) -> Self: ...
     def __next__(self) -> _T: ...
 
-_T1 = TypeVar("_T1")
-_T2 = TypeVar("_T2")
-
 class groupby(Iterator[tuple[_T, Iterator[_S]]], Generic[_T, _S]):
     @overload
     def __new__(cls, iterable: Iterable[_T1], key: None = ...) -> groupby[_T1, _T1]: ...
@@ -108,15 +113,85 @@ class takewhile(Iterator[_T], Generic[_T]):
 
 def tee(__iterable: Iterable[_T], __n: int = ...) -> tuple[Iterator[_T], ...]: ...
 
-class zip_longest(Iterator[Any]):
-    def __init__(self, *p: Iterable[Any], fillvalue: Any = ...) -> None: ...
+class zip_longest(Iterator[_T_co], Generic[_T_co]):
+    # one iterable (fillvalue doesn't matter)
+    @overload
+    def __new__(cls, __iter1: Iterable[_T1], *, fillvalue: object = ...) -> zip_longest[tuple[_T1]]: ...
+    # two iterables
+    @overload
+    # In the overloads without fillvalue, all of the tuple members could theoretically be None,
+    # but we return Any instead to avoid false positives for code where we know one of the iterables
+    # is longer.
+    def __new__(cls, __iter1: Iterable[_T1], __iter2: Iterable[_T2]) -> zip_longest[tuple[_T1 | Any, _T2 | Any]]: ...
+    @overload
+    def __new__(
+        cls, __iter1: Iterable[_T1], __iter2: Iterable[_T2], *, fillvalue: _T
+    ) -> zip_longest[tuple[_T1 | _T, _T2 | _T]]: ...
+    # three iterables
+    @overload
+    def __new__(
+        cls, __iter1: Iterable[_T1], __iter2: Iterable[_T2], __iter3: Iterable[_T3]
+    ) -> zip_longest[tuple[_T1 | Any, _T2 | Any, _T3 | Any]]: ...
+    @overload
+    def __new__(
+        cls, __iter1: Iterable[_T1], __iter2: Iterable[_T2], __iter3: Iterable[_T3], *, fillvalue: _T
+    ) -> zip_longest[tuple[_T1 | _T, _T2 | _T, _T3 | _T]]: ...
+    # four iterables
+    @overload
+    def __new__(
+        cls, __iter1: Iterable[_T1], __iter2: Iterable[_T2], __iter3: Iterable[_T3], __iter4: Iterable[_T4]
+    ) -> zip_longest[tuple[_T1 | Any, _T2 | Any, _T3 | Any, _T4 | Any]]: ...
+    @overload
+    def __new__(
+        cls, __iter1: Iterable[_T1], __iter2: Iterable[_T2], __iter3: Iterable[_T3], __iter4: Iterable[_T4], *, fillvalue: _T
+    ) -> zip_longest[tuple[_T1 | _T, _T2 | _T, _T3 | _T, _T4 | _T]]: ...
+    # five iterables
+    @overload
+    def __new__(
+        cls,
+        __iter1: Iterable[_T1],
+        __iter2: Iterable[_T2],
+        __iter3: Iterable[_T3],
+        __iter4: Iterable[_T4],
+        __iter5: Iterable[_T5],
+    ) -> zip_longest[tuple[_T1 | Any, _T2 | Any, _T3 | Any, _T4 | Any, _T5 | Any]]: ...
+    @overload
+    def __new__(
+        cls,
+        __iter1: Iterable[_T1],
+        __iter2: Iterable[_T2],
+        __iter3: Iterable[_T3],
+        __iter4: Iterable[_T4],
+        __iter5: Iterable[_T5],
+        *,
+        fillvalue: _T,
+    ) -> zip_longest[tuple[_T1 | _T, _T2 | _T, _T3 | _T, _T4 | _T, _T5 | _T]]: ...
+    # six or more iterables
+    @overload
+    def __new__(
+        cls,
+        __iter1: Iterable[_T],
+        __iter2: Iterable[_T],
+        __iter3: Iterable[_T],
+        __iter4: Iterable[_T],
+        __iter5: Iterable[_T],
+        __iter6: Iterable[_T],
+        *iterables: Iterable[_T],
+    ) -> zip_longest[tuple[_T | Any, ...]]: ...
+    @overload
+    def __new__(
+        cls,
+        __iter1: Iterable[_T],
+        __iter2: Iterable[_T],
+        __iter3: Iterable[_T],
+        __iter4: Iterable[_T],
+        __iter5: Iterable[_T],
+        __iter6: Iterable[_T],
+        *iterables: Iterable[_T],
+        fillvalue: _T,
+    ) -> zip_longest[tuple[_T, ...]]: ...
     def __iter__(self: Self) -> Self: ...
-    def __next__(self) -> Any: ...
-
-_T3 = TypeVar("_T3")
-_T4 = TypeVar("_T4")
-_T5 = TypeVar("_T5")
-_T6 = TypeVar("_T6")
+    def __next__(self) -> _T_co: ...
 
 class product(Iterator[_T_co], Generic[_T_co]):
     @overload

stdlib/random.pyi

@@ -89,7 +89,10 @@ class Random(_random.Random):
         cum_weights: Sequence[float | Fraction] | None = ...,
         k: int = ...,
     ) -> list[_T]: ...
-    def shuffle(self, x: MutableSequence[Any], random: Callable[[], float] | None = ...) -> None: ...
+    if sys.version_info >= (3, 11):
+        def shuffle(self, x: MutableSequence[Any]) -> None: ...
+    else:
+        def shuffle(self, x: MutableSequence[Any], random: Callable[[], float] | None = ...) -> None: ...
     if sys.version_info >= (3, 11):
         def sample(self, population: Sequence[_T], k: int, *, counts: Iterable[int] | None = ...) -> list[_T]: ...
     elif sys.version_info >= (3, 9):