Merge branch 'main' into fpdf2-2.8.5

Author: srittau

CONTRIBUTING.md

@@ -344,20 +344,20 @@ the latest mypy (`pip install -r requirements-tests.txt`) before running the scr
 
 ### Supported type system features
 
-Since PEP 484 was accepted, there have been many other PEPs that added
-new features to the Python type system. In general, new features can
-be used in typeshed as soon as the PEP has been accepted and implemented
-and most type checkers support the new feature.
+Since [PEP 484](https://peps.python.org/pep-0484/) was accepted, there have been
+many other PEPs that added new features to the Python type system. In general,
+new features can be used in typeshed as soon as the PEP has been accepted and
+implemented and most type checkers support the new feature.
 
 Supported features include:
-- [PEP 544](https://peps.python.org/pep-0544/) (Protocol)
+- [PEP 544](https://peps.python.org/pep-0544/) (`Protocol`)
 - [PEP 585](https://peps.python.org/pep-0585/) (builtin generics)
-- [PEP 586](https://peps.python.org/pep-0586/) (Literal)
-- [PEP 591](https://peps.python.org/pep-0591/) (Final/@final)
-- [PEP 589](https://peps.python.org/pep-0589/) (TypedDict)
+- [PEP 586](https://peps.python.org/pep-0586/) (`Literal`)
+- [PEP 591](https://peps.python.org/pep-0591/) (`Final`/`@final`)
+- [PEP 589](https://peps.python.org/pep-0589/) (`TypedDict`)
 - [PEP 604](https://peps.python.org/pep-0604/) (`Foo | Bar` union syntax)
-- [PEP 612](https://peps.python.org/pep-0612/) (ParamSpec)
-- [PEP 647](https://peps.python.org/pep-0647/) (TypeGuard):
+- [PEP 612](https://peps.python.org/pep-0612/) (`ParamSpec`)
+- [PEP 647](https://peps.python.org/pep-0647/) (`TypeGuard`):
   see [#5406](https://github.com/python/typeshed/issues/5406)
 - [PEP 655](https://peps.python.org/pep-0655/) (`Required` and `NotRequired`)
 - [PEP 673](https://peps.python.org/pep-0673/) (`Self`)

lib/ts_utils/utils.py

@@ -35,6 +35,16 @@ def strip_comments(text: str) -> str:
     return text.split("#")[0].strip()
 
 
+def json5_to_json(text: str) -> str:
+    """Incomplete conversion from JSON5-like input to valid JSON."""
+    # Remove full-line // comments only
+    # (Can not remove inline comments)
+    text = re.sub(r"(?m)^\s*//.*\n?", "", text)
+    # Remove trailing commas before } or ]
+    text = re.sub(r",\s*([}\]])", r"\1", text)
+    return text
+
+
 # ====================================================================
 # Printing utilities
 # ====================================================================

pyrightconfig.stricter.json

@@ -9,16 +9,16 @@
         // test cases use a custom pyrightconfig file
         "**/@tests/test_cases",
         "stdlib/__main__.pyi",
+        "stdlib/_tkinter.pyi",
         "stdlib/distutils/cmd.pyi",
         "stdlib/distutils/command",
         "stdlib/distutils/dist.pyi",
         "stdlib/encodings/__init__.pyi",
         "stdlib/lib2to3/fixes/*.pyi",
         "stdlib/numbers.pyi",
-        "stdlib/_tkinter.pyi",
         "stdlib/tkinter/__init__.pyi",
-        "stdlib/tkinter/filedialog.pyi",
         "stdlib/tkinter/dialog.pyi",
+        "stdlib/tkinter/filedialog.pyi",
         "stdlib/tkinter/scrolledtext.pyi",
         "stdlib/tkinter/tix.pyi",
         "stdlib/tkinter/ttk.pyi",
@@ -74,6 +74,7 @@
         "stubs/protobuf",
         "stubs/psutil/psutil/__init__.pyi",
         "stubs/psycopg2",
+        "stubs/punq",
         "stubs/pyasn1",
         "stubs/pycurl",
         "stubs/Pygments",

stdlib/@tests/stubtest_allowlists/linux.txt

@@ -27,6 +27,15 @@ fcntl.I_[A-Z0-9_]+  # Platform differences that cannot be captured by the type s
 multiprocessing.popen_spawn_win32  # exists on Linux but fails to import
 select.poll  # Actually a function; we have a class so it can be used as a type
 
+# Bluetooth constants which aren't on the GitHub Actions runners, see #15207
+(_?socket\.AF_BLUETOOTH)?
+(_?socket\.BDADDR_ANY)?
+(_?socket\.BDADDR_LOCAL)?
+(_?socket\.BTPROTO_HCI)?
+(_?socket\.BTPROTO_L2CAP)?
+(_?socket\.BTPROTO_RFCOMM)?
+(_?socket\.BTPROTO_SCO)?
+
 # These seem like they should be available on Linux, but they're not
 # on GitHub Actions runners for some reason.
 _?socket.IPX_TYPE

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

@@ -0,0 +1,14 @@
+from typing_extensions import Literal, assert_type
+
+
+# Note: type checkers / linters are free to point out that the set difference
+#   below is redundant. But typeshed should allow it, as its job is to describe
+#   what is legal in Python, not what is sensible.
+#   For instance, set[Literal] - set[str] should be legal.
+def test_set_difference(x: set[Literal["foo", "bar"]], y: set[str], z: set[int]) -> None:
+    assert_type(x - y, set[Literal["foo", "bar"]])
+    assert_type(y - x, set[str])
+    assert_type(x - z, set[Literal["foo", "bar"]])
+    assert_type(z - x, set[int])
+    assert_type(y - z, set[str])
+    assert_type(z - y, set[int])

stdlib/@tests/test_cases/itertools/check_batched.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import sys
+from typing_extensions import assert_type
+
+if sys.version_info >= (3, 13):
+    from itertools import batched
+
+    assert_type(batched([0], 1, strict=True), batched[tuple[int]])
+    assert_type(batched([0, 0], 2, strict=True), batched[tuple[int, int]])
+    assert_type(batched([0, 0, 0], 3, strict=True), batched[tuple[int, int, int]])
+    assert_type(batched([0, 0, 0, 0], 4, strict=True), batched[tuple[int, int, int, int]])
+    assert_type(batched([0, 0, 0, 0, 0], 5, strict=True), batched[tuple[int, int, int, int, int]])
+
+    assert_type(batched([0], 2), batched[tuple[int, ...]])
+    assert_type(batched([0], 2, strict=False), batched[tuple[int, ...]])
+
+    def f() -> int:
+        return 3
+
+    assert_type(batched([0, 0, 0], f(), strict=True), batched[tuple[int, ...]])

stdlib/_socket.pyi

@@ -587,7 +587,7 @@ if sys.platform != "linux":
 
 has_ipv6: bool
 
-if sys.platform != "darwin" and sys.platform != "linux":
+if sys.platform != "darwin":
     BDADDR_ANY: Final = "00:00:00:00:00:00"
     BDADDR_LOCAL: Final = "00:00:00:FF:FF:FF"
 
@@ -660,16 +660,16 @@ if sys.platform == "darwin":
     PF_SYSTEM: Final[int]
     SYSPROTO_CONTROL: Final[int]
 
-if sys.platform != "darwin" and sys.platform != "linux":
+if sys.platform != "darwin":
     AF_BLUETOOTH: Final[int]
 
-if sys.platform != "win32" and sys.platform != "darwin" and sys.platform != "linux":
+if sys.platform != "win32" and sys.platform != "darwin":
     # Linux and some BSD support is explicit in the docs
     # Windows and macOS do not support in practice
     BTPROTO_HCI: Final[int]
     BTPROTO_L2CAP: Final[int]
     BTPROTO_SCO: Final[int]  # not in FreeBSD
-if sys.platform != "darwin" and sys.platform != "linux":
+if sys.platform != "darwin":
     BTPROTO_RFCOMM: Final[int]
 
 if sys.platform == "linux":

stdlib/_tkinter.pyi

@@ -1,6 +1,7 @@
 import sys
+from _typeshed import FileDescriptorLike, Incomplete
 from collections.abc import Callable
-from typing import Any, ClassVar, Final, final
+from typing import Any, ClassVar, Final, Literal, final, overload
 from typing_extensions import TypeAlias, deprecated
 
 # _tkinter is meant to be only used internally by tkinter, but some tkinter
@@ -54,22 +55,23 @@ _TkinterTraceFunc: TypeAlias = Callable[[tuple[str, ...]], object]
 @final
 class TkappType:
     # Please keep in sync with tkinter.Tk
-    def adderrorinfo(self, msg: str, /): ...
+    def adderrorinfo(self, msg: str, /) -> None: ...
     def call(self, command: Any, /, *args: Any) -> Any: ...
-    def createcommand(self, name: str, func, /): ...
+    # TODO: Figure out what arguments the following `func` callbacks should accept
+    def createcommand(self, name: str, func: Callable[..., object], /) -> None: ...
     if sys.platform != "win32":
-        def createfilehandler(self, file, mask: int, func, /): ...
-        def deletefilehandler(self, file, /) -> None: ...
+        def createfilehandler(self, file: FileDescriptorLike, mask: int, func: Callable[..., object], /) -> None: ...
+        def deletefilehandler(self, file: FileDescriptorLike, /) -> None: ...
 
-    def createtimerhandler(self, milliseconds: int, func, /): ...
-    def deletecommand(self, name: str, /): ...
-    def dooneevent(self, flags: int = 0, /): ...
+    def createtimerhandler(self, milliseconds: int, func: Callable[..., object], /): ...
+    def deletecommand(self, name: str, /) -> None: ...
+    def dooneevent(self, flags: int = 0, /) -> int: ...
     def eval(self, script: str, /) -> str: ...
-    def evalfile(self, fileName: str, /): ...
-    def exprboolean(self, s: str, /): ...
-    def exprdouble(self, s: str, /): ...
-    def exprlong(self, s: str, /): ...
-    def exprstring(self, s: str, /): ...
+    def evalfile(self, fileName: str, /) -> str: ...
+    def exprboolean(self, s: str, /) -> Literal[0, 1]: ...
+    def exprdouble(self, s: str, /) -> float: ...
+    def exprlong(self, s: str, /) -> int: ...
+    def exprstring(self, s: str, /) -> str: ...
     def getboolean(self, arg, /) -> bool: ...
     def getdouble(self, arg, /) -> float: ...
     def getint(self, arg, /) -> int: ...
@@ -81,15 +83,23 @@ class TkappType:
     def loadtk(self) -> None: ...
     def mainloop(self, threshold: int = 0, /) -> None: ...
     def quit(self) -> None: ...
-    def record(self, script: str, /): ...
+    def record(self, script: str, /) -> str: ...
     def setvar(self, *ags, **kwargs): ...
     if sys.version_info < (3, 11):
         @deprecated("Deprecated since Python 3.9; removed in Python 3.11. Use `splitlist()` instead.")
         def split(self, arg, /): ...
 
-    def splitlist(self, arg, /): ...
+    def splitlist(self, arg, /) -> tuple[Incomplete, ...]: ...
     def unsetvar(self, *args, **kwargs): ...
-    def wantobjects(self, *args, **kwargs): ...
+    if sys.version_info >= (3, 14):
+        @overload
+        def wantobjects(self) -> Literal[0, 1]: ...
+    else:
+        @overload
+        def wantobjects(self) -> bool: ...
+
+    @overload
+    def wantobjects(self, wantobjects: Literal[0, 1] | bool, /) -> None: ...
     def willdispatch(self) -> None: ...
     if sys.version_info >= (3, 12):
         def gettrace(self, /) -> _TkinterTraceFunc | None: ...
@@ -112,7 +122,7 @@ TK_VERSION: Final[str]
 
 @final
 class TkttType:
-    def deletetimerhandler(self): ...
+    def deletetimerhandler(self) -> None: ...
 
 if sys.version_info >= (3, 13):
     def create(
@@ -125,7 +135,7 @@ if sys.version_info >= (3, 13):
         sync: bool = False,
         use: str | None = None,
         /,
-    ): ...
+    ) -> TkappType: ...
 
 else:
     def create(
@@ -138,7 +148,7 @@ else:
         sync: bool = False,
         use: str | None = None,
         /,
-    ): ...
+    ) -> TkappType: ...
 
 def getbusywaitinterval() -> int: ...
 def setbusywaitinterval(new_val: int, /) -> None: ...

stdlib/builtins.pyi

@@ -1282,7 +1282,7 @@ class set(MutableSet[_T]):
     def __iand__(self, value: AbstractSet[object], /) -> Self: ...
     def __or__(self, value: AbstractSet[_S], /) -> set[_T | _S]: ...
     def __ior__(self, value: AbstractSet[_T], /) -> Self: ...  # type: ignore[override,misc]
-    def __sub__(self, value: AbstractSet[_T | None], /) -> set[_T]: ...
+    def __sub__(self, value: AbstractSet[object], /) -> set[_T]: ...
     def __isub__(self, value: AbstractSet[object], /) -> Self: ...
     def __xor__(self, value: AbstractSet[_S], /) -> set[_T | _S]: ...
     def __ixor__(self, value: AbstractSet[_T], /) -> Self: ...  # type: ignore[override,misc]
@@ -1313,7 +1313,7 @@ class frozenset(AbstractSet[_T_co]):
     def __iter__(self) -> Iterator[_T_co]: ...
     def __and__(self, value: AbstractSet[_T_co], /) -> frozenset[_T_co]: ...
     def __or__(self, value: AbstractSet[_S], /) -> frozenset[_T_co | _S]: ...
-    def __sub__(self, value: AbstractSet[_T_co], /) -> frozenset[_T_co]: ...
+    def __sub__(self, value: AbstractSet[object], /) -> frozenset[_T_co]: ...
     def __xor__(self, value: AbstractSet[_S], /) -> frozenset[_T_co | _S]: ...
     def __le__(self, value: AbstractSet[object], /) -> bool: ...
     def __lt__(self, value: AbstractSet[object], /) -> bool: ...

stdlib/cmath.pyi

@@ -9,6 +9,7 @@ nan: Final[float]
 nanj: Final[complex]
 tau: Final[float]
 
+_F: TypeAlias = SupportsFloat | SupportsIndex
 _C: TypeAlias = SupportsFloat | SupportsComplex | SupportsIndex | complex
 
 def acos(z: _C, /) -> complex: ...
@@ -27,7 +28,7 @@ def log(z: _C, base: _C = ..., /) -> complex: ...
 def log10(z: _C, /) -> complex: ...
 def phase(z: _C, /) -> float: ...
 def polar(z: _C, /) -> tuple[float, float]: ...
-def rect(r: float, phi: float, /) -> complex: ...
+def rect(r: _F, phi: _F, /) -> complex: ...
 def sin(z: _C, /) -> complex: ...
 def sinh(z: _C, /) -> complex: ...
 def sqrt(z: _C, /) -> complex: ...