Merge branch 'main' into callable_any_return

Author: randolf-scholz

.flake8

@@ -2,7 +2,9 @@
 # Y: Flake8 is only used to run flake8-pyi, everything else is in Ruff
 select = Y
 # Ignore rules normally excluded by default
-extend-ignore = Y090,Y091
+# Also ignore Y041 (redundant (complex |) float | int), see
+# https://github.com/python/typeshed/issues/16059
+extend-ignore = Y041,Y090,Y091
 per-file-ignores =
   # Generated protobuf files:
   # Y021: Include docstrings

CONTRIBUTING.md

@@ -320,6 +320,25 @@ documentation.  Whenever you find them disagreeing, model the type
 information after the actual implementation and file an issue on the
 project's tracker to fix their documentation.
 
+### Deprecations (using the `@deprecated` decorator)
+
+Generally deprecactions using the `@deprecated` decorator are added more
+liberally in typeshed than runtime deprecation warnings. Here are some
+guidelines that can be deviated from in special cases.
+
+Use `@deprecated` if and only if
+
+- a feature is deprecated at runtime (either using `@deprecated` or with a
+  runtime warning); or
+- a feature is documented to be deprecated (e.g. in API documention,
+  docstrings, or comments).
+
+For standard library features that are not deprecated in all Python versions
+currently supported by typeshed use `@deprecated` for
+
+- all versions starting with the "Deprecated since" version, plus
+- all versions for which an alternative is available.
+
 ### Docstrings
 
 Typeshed stubs should not include duplicated docstrings from the source code.

pyrightconfig.stricter.json

@@ -73,13 +73,17 @@
         "stubs/parsimonious/parsimonious/nodes.pyi",
         "stubs/peewee",
         "stubs/pexpect",
-        "stubs/pika",
+        "stubs/pika/pika/adapters/twisted_connection.pyi",
+        "stubs/pika/pika/adapters/utils/connection_workflow.pyi",
+        "stubs/pika/pika/callback.pyi",
+        "stubs/pika/pika/channel.pyi",
         "stubs/pony",
         "stubs/protobuf",
         "stubs/psutil/psutil/__init__.pyi",
         "stubs/psycopg2",
         "stubs/punq",
         "stubs/pyasn1",
+        "stubs/pycups",
         "stubs/Pygments",
         "stubs/PyMySQL",
         "stubs/pyogrio",

stdlib/@tests/test_cases/builtins/check_pow.py

@@ -15,7 +15,7 @@
 # that passing 0 for the third argument will lead to an exception being raised
 # (see discussion in #8566)
 #
-# assert_type(pow(2, 4, 0), NoReturn)
+# assert_type(pow(2, 4, 0), Never)
 
 assert_type(pow(2, 4), int)
 # pyright infers a literal type here, but mypy does not.

stdlib/@tests/test_cases/builtins/check_reversed.py

@@ -31,4 +31,18 @@ def __getitem__(self, item: int) -> _T:
 
 
 len_and_get_item: MyLenAndGetItem[int] = MyLenAndGetItem()
-assert_type(list(reversed(len_and_get_item)), "list[int]")
+assert_type(reversed(len_and_get_item), "reversed[int]")
+
+
+class UnTrue:
+    def __reversed__(self) -> UnFalse:
+        return UnFalse()
+
+
+class UnFalse:
+    def __reversed__(self) -> UnTrue:
+        return UnTrue()
+
+
+assert_type(reversed(UnTrue()), "UnFalse")
+assert_type(reversed(reversed(UnTrue())), "UnTrue")

stdlib/__main__.pyi

@@ -1 +1 @@
-def __getattr__(name: str): ...  # incomplete module
+def __getattr__(name: str, /): ...  # incomplete module

stdlib/_ctypes.pyi

@@ -249,7 +249,7 @@ class _UnionType(_CTypeBaseType):
     # At runtime, various attributes are created on a Union subclass based
     # on its _fields_. This method doesn't exist, but represents those
     # dynamically created attributes.
-    def __getattr__(self, name: str) -> _CField[Any, Any, Any]: ...
+    def __getattr__(self, name: str, /) -> _CField[Any, Any, Any]: ...
     if sys.version_info < (3, 13):
         # Inherited from CType_Type starting on 3.13
         def __mul__(cls: type[_CT], other: int) -> type[Array[_CT]]: ...  # type: ignore[misc] # pyright: ignore[reportGeneralTypeIssues]
@@ -263,8 +263,8 @@ class Union(_CData, metaclass=_UnionType):
         _align_: ClassVar[int]
 
     def __init__(self, *args: Any, **kw: Any) -> None: ...
-    def __getattr__(self, name: str) -> Any: ...
-    def __setattr__(self, name: str, value: Any) -> None: ...
+    def __getattr__(self, name: str, /) -> Any: ...
+    def __setattr__(self, name: str, value: Any, /) -> None: ...
 
 # This class is not exposed. It calls itself _ctypes.PyCStructType.
 @type_check_only
@@ -277,7 +277,7 @@ class _PyCStructType(_CTypeBaseType):
     # At runtime, various attributes are created on a Structure subclass based
     # on its _fields_. This method doesn't exist, but represents those
     # dynamically created attributes.
-    def __getattr__(self, name: str) -> _CField[Any, Any, Any]: ...
+    def __getattr__(self, name: str, /) -> _CField[Any, Any, Any]: ...
     if sys.version_info < (3, 13):
         # Inherited from CType_Type starting on 3.13
         def __mul__(cls: type[_CT], other: int) -> type[Array[_CT]]: ...  # type: ignore[misc] # pyright: ignore[reportGeneralTypeIssues]
@@ -295,7 +295,7 @@ class Structure(_CData, metaclass=_PyCStructType):
         _layout_: ClassVar[Literal["ms", "gcc-sysv"]]
 
     def __init__(self, *args: Any, **kw: Any) -> None: ...
-    def __getattr__(self, name: str) -> Any: ...
+    def __getattr__(self, name: str, /) -> Any: ...
     def __setattr__(self, name: str, value: Any) -> None: ...
 
 # This class is not exposed. It calls itself _ctypes.PyCArrayType.

stdlib/_sitebuiltins.pyi

@@ -1,12 +1,13 @@
 import sys
 from collections.abc import Iterable
-from typing import ClassVar, Literal, NoReturn
+from typing import ClassVar, Literal
+from typing_extensions import Never
 
 class Quitter:
     name: str
     eof: str
     def __init__(self, name: str, eof: str) -> None: ...
-    def __call__(self, code: sys._ExitCode = None) -> NoReturn: ...
+    def __call__(self, code: sys._ExitCode = None) -> Never: ...
 
 class _Printer:
     MAXLINES: ClassVar[Literal[23]]

stdlib/_thread.pyi

@@ -4,8 +4,8 @@ from _typeshed import structseq
 from collections.abc import Callable
 from threading import Thread
 from types import TracebackType
-from typing import Any, Final, NoReturn, final, overload
-from typing_extensions import TypeVarTuple, Unpack, deprecated, disjoint_base
+from typing import Any, Final, final, overload
+from typing_extensions import Never, TypeVarTuple, Unpack, deprecated, disjoint_base
 
 _Ts = TypeVarTuple("_Ts")
 
@@ -82,9 +82,9 @@ def start_new(function: Callable[[Unpack[_Ts]], object], args: tuple[Unpack[_Ts]
 def start_new(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any], /) -> int: ...  # undocumented
 
 def interrupt_main(signum: signal.Signals = signal.SIGINT, /) -> None: ...
-def exit() -> NoReturn: ...
+def exit() -> Never: ...
 @deprecated("Obsolete synonym. Use `exit()` instead.")
-def exit_thread() -> NoReturn: ...  # undocumented
+def exit_thread() -> Never: ...  # undocumented
 def allocate_lock() -> LockType: ...
 @deprecated("Obsolete synonym. Use `allocate_lock()` instead.")
 def allocate() -> LockType: ...  # undocumented

stdlib/_typeshed/__init__.pyi

@@ -58,6 +58,14 @@ Unused: TypeAlias = object  # stable
 # for more information.
 MaybeNone: TypeAlias = Any  # stable
 
+# typeshed-internal type aliases to facilitate transition from
+# `float` to either `float | int` or `float` (and similar for `complex`).
+# When you encounter one of these type aliases, you are encouraged to
+# replace them with the correct type. Please don't use them outside typeshed.
+# See https://github.com/python/typeshed/issues/16059 for details.
+FloatInt: TypeAlias = float | int
+ComplexInt: TypeAlias = complex | float | int
+
 # Used to mark arguments that default to a sentinel value. This prevents
 # stubtest from complaining about the default value not matching.
 #