Use TypeVarTuple in our APIs

docs/source/conf.py

@@ -73,7 +73,6 @@
     # aliasing doesn't actually fix the warning for types.FrameType, but displaying
     # "types.FrameType" is more helpful than just "frame"
     "FrameType": "types.FrameType",
-    "Context": "OpenSSL.SSL.Context",
     # SSLListener.accept's return type is seen as trio._ssl.SSLStream
     "SSLStream": "trio.SSLStream",
 }
@@ -91,6 +90,8 @@ def autodoc_process_signature(
             # Strip the type from the union, make it look like = ...
             signature = signature.replace(" | type[trio._core._local._NoValue]", "")
             signature = signature.replace("<class 'trio._core._local._NoValue'>", "...")
+        if "DTLS" in name:
+            signature = signature.replace("SSL.Context", "OpenSSL.SSL.Context")
         # Don't specify PathLike[str] | PathLike[bytes], this is just for humans.
         signature = signature.replace("StrOrBytesPath", "str | bytes | os.PathLike")
 

pyproject.toml

@@ -127,6 +127,7 @@ extend-exclude = [
 'src/trio/lowlevel.py' = ['F401']
 'src/trio/socket.py' = ['F401']
 'src/trio/testing/__init__.py' = ['F401']
+'**/type_tests/*' = ['F841']  # Annotated local vars are used to specify return values.
 
 [tool.ruff.isort]
 combine-as-imports = true

src/trio/_core/_entry_queue.py

@@ -2,18 +2,21 @@
 
 import threading
 from collections import deque
-from typing import Callable, Iterable, NoReturn, Tuple
+from typing import TYPE_CHECKING, Callable, NoReturn, Tuple
 
 import attr
 
 from .. import _core
 from .._util import NoPublicConstructor, final
 from ._wakeup_socketpair import WakeupSocketpair
 
-# TODO: Type with TypeVarTuple, at least to an extent where it makes
-# the public interface safe.
+if TYPE_CHECKING:
+    from typing_extensions import TypeVarTuple, Unpack
+
+    PosArgsT = TypeVarTuple("PosArgsT")
+
 Function = Callable[..., object]
-Job = Tuple[Function, Iterable[object]]
+Job = Tuple[Function, Tuple[object, ...]]
 
 
 @attr.s(slots=True)
@@ -122,7 +125,10 @@ def size(self) -> int:
         return len(self.queue) + len(self.idempotent_queue)
 
     def run_sync_soon(
-        self, sync_fn: Function, *args: object, idempotent: bool = False
+        self,
+        sync_fn: Callable[[Unpack[PosArgsT]], object],
+        *args: Unpack[PosArgsT],
+        idempotent: bool = False,
     ) -> None:
         with self.lock:
             if self.done:
@@ -163,7 +169,10 @@ class TrioToken(metaclass=NoPublicConstructor):
     _reentry_queue: EntryQueue = attr.ib()
 
     def run_sync_soon(
-        self, sync_fn: Function, *args: object, idempotent: bool = False
+        self,
+        sync_fn: Callable[[Unpack[PosArgsT]], object],
+        *args: Unpack[PosArgsT],
+        idempotent: bool = False,
     ) -> None:
         """Schedule a call to ``sync_fn(*args)`` to occur in the context of a
         Trio task.

src/trio/_core/_generated_run.py

@@ -13,9 +13,11 @@
     from collections.abc import Awaitable, Callable
 
     from outcome import Outcome
+    from typing_extensions import Unpack
 
     from .._abc import Clock
     from ._entry_queue import TrioToken
+    from ._run import PosArgT
 
 
 def current_statistics() -> RunStatistics:
@@ -113,8 +115,8 @@ def reschedule(task: Task, next_send: Outcome[Any] = _NO_SEND) -> None:
 
 
 def spawn_system_task(
-    async_fn: Callable[..., Awaitable[object]],
-    *args: object,
+    async_fn: Callable[[Unpack[PosArgT]], Awaitable[object]],
+    *args: Unpack[PosArgT],
     name: object = None,
     context: (contextvars.Context | None) = None,
 ) -> Task:

src/trio/_core/_run.py

@@ -53,6 +53,12 @@
 if sys.version_info < (3, 11):
     from exceptiongroup import BaseExceptionGroup
 
+FnT = TypeVar("FnT", bound="Callable[..., Any]")
+StatusT = TypeVar("StatusT")
+StatusT_co = TypeVar("StatusT_co", covariant=True)
+StatusT_contra = TypeVar("StatusT_contra", contravariant=True)
+RetT = TypeVar("RetT")
+
 
 if TYPE_CHECKING:
     import contextvars
@@ -70,19 +76,25 @@
     # for some strange reason Sphinx works with outcome.Outcome, but not Outcome, in
     # start_guest_run. Same with types.FrameType in iter_await_frames
     import outcome
-    from typing_extensions import Self
+    from typing_extensions import Self, TypeVarTuple, Unpack
+
+    PosArgT = TypeVarTuple("PosArgT")
+
+    # Needs to be guarded, since Unpack[] would be evaluated at runtime.
+    class _NurseryStartFunc(Protocol[Unpack[PosArgT], StatusT_co]):
+        """Type of functions passed to `nursery.start() <trio.Nursery.start>`."""
+
+        def __call__(
+            self, *args: Unpack[PosArgT], task_status: TaskStatus[StatusT_co]
+        ) -> Awaitable[object]:
+            ...
+
 
 DEADLINE_HEAP_MIN_PRUNE_THRESHOLD: Final = 1000
 
 # Passed as a sentinel
 _NO_SEND: Final[Outcome[Any]] = cast("Outcome[Any]", object())
 
-FnT = TypeVar("FnT", bound="Callable[..., Any]")
-StatusT = TypeVar("StatusT")
-StatusT_co = TypeVar("StatusT_co", covariant=True)
-StatusT_contra = TypeVar("StatusT_contra", contravariant=True)
-RetT = TypeVar("RetT")
-
 
 @final
 class _NoStatus(metaclass=NoPublicConstructor):
@@ -1119,9 +1131,8 @@ def aborted(raise_cancel: _core.RaiseCancelT) -> Abort:
 
     def start_soon(
         self,
-        # TODO: TypeVarTuple
-        async_fn: Callable[..., Awaitable[object]],
-        *args: object,
+        async_fn: Callable[[Unpack[PosArgT]], Awaitable[object]],
+        *args: Unpack[PosArgT],
         name: object = None,
     ) -> None:
         """Creates a child task, scheduling ``await async_fn(*args)``.
@@ -1170,7 +1181,7 @@ async def start(
         async_fn: Callable[..., Awaitable[object]],
         *args: object,
         name: object = None,
-    ) -> StatusT:
+    ) -> Any:
         r"""Creates and initializes a child task.
 
         Like :meth:`start_soon`, but blocks until the new task has
@@ -1219,7 +1230,7 @@ async def async_fn(arg1, arg2, *, task_status=trio.TASK_STATUS_IGNORED):
             # `run` option, which would cause it to wrap a pre-started()
             # exception in an extra ExceptionGroup. See #2611.
             async with open_nursery(strict_exception_groups=False) as old_nursery:
-                task_status: _TaskStatus[StatusT] = _TaskStatus(old_nursery, self)
+                task_status: _TaskStatus[Any] = _TaskStatus(old_nursery, self)
                 thunk = functools.partial(async_fn, task_status=task_status)
                 task = GLOBAL_RUN_CONTEXT.runner.spawn_impl(
                     thunk, args, old_nursery, name
@@ -1232,7 +1243,7 @@ async def async_fn(arg1, arg2, *, task_status=trio.TASK_STATUS_IGNORED):
             # (Any exceptions propagate directly out of the above.)
             if task_status._value is _NoStatus:
                 raise RuntimeError("child exited without calling task_status.started()")
-            return task_status._value  # type: ignore[return-value]  # Mypy doesn't narrow yet.
+            return task_status._value
         finally:
             self._pending_starts -= 1
             self._check_nursery_closed()
@@ -1690,9 +1701,8 @@ def reschedule(  # type: ignore[misc]
 
     def spawn_impl(
         self,
-        # TODO: TypeVarTuple
-        async_fn: Callable[..., Awaitable[object]],
-        args: tuple[object, ...],
+        async_fn: Callable[[Unpack[PosArgT]], Awaitable[object]],
+        args: tuple[Unpack[PosArgT]],
         nursery: Nursery | None,
         name: object,
         *,
@@ -1721,7 +1731,7 @@ def spawn_impl(
         # Call the function and get the coroutine object, while giving helpful
         # errors for common mistakes.
         ######
-        # TODO: resolve the type: ignore when implementing TypeVarTuple
+        # TypeVarTuple passed into ParamSpec function confuses Mypy.
         coro = context.run(coroutine_or_error, async_fn, *args)  # type: ignore[arg-type]
 
         if name is None:
@@ -1809,12 +1819,11 @@ def task_exited(self, task: Task, outcome: Outcome[Any]) -> None:
     # System tasks and init
     ################
 
-    @_public  # Type-ignore due to use of Any here.
-    def spawn_system_task(  # type: ignore[misc]
+    @_public
+    def spawn_system_task(
         self,
-        # TODO: TypeVarTuple
-        async_fn: Callable[..., Awaitable[object]],
-        *args: object,
+        async_fn: Callable[[Unpack[PosArgT]], Awaitable[object]],
+        *args: Unpack[PosArgT],
         name: object = None,
         context: contextvars.Context | None = None,
     ) -> Task:
@@ -1879,10 +1888,9 @@ def spawn_system_task(  # type: ignore[misc]
         )
 
     async def init(
-        # TODO: TypeVarTuple
         self,
-        async_fn: Callable[..., Awaitable[object]],
-        args: tuple[object, ...],
+        async_fn: Callable[[Unpack[PosArgT]], Awaitable[object]],
+        args: tuple[Unpack[PosArgT]],
     ) -> None:
         # run_sync_soon task runs here:
         async with open_nursery() as run_sync_soon_nursery:
@@ -2408,8 +2416,8 @@ def my_done_callback(run_outcome):
 # straight through.
 def unrolled_run(
     runner: Runner,
-    async_fn: Callable[..., object],
-    args: tuple[object, ...],
+    async_fn: Callable[[Unpack[PosArgT]], Awaitable[object]],
+    args: tuple[Unpack[PosArgT]],
     host_uses_signal_set_wakeup_fd: bool = False,
 ) -> Generator[float, EventResult, None]:
     locals()[LOCALS_KEY_KI_PROTECTION_ENABLED] = True

src/trio/_core/_tests/test_guest_mode.py

@@ -658,9 +658,7 @@ async def trio_main() -> None:
     # Ensure we don't pollute the thread-level context if run under
     # an asyncio without contextvars support (3.6)
     context = contextvars.copy_context()
-    if TYPE_CHECKING:
-        aiotrio_run(trio_main, host_uses_signal_set_wakeup_fd=True)
-    # this type error is a bug in typeshed or mypy, as it's equivalent to the above line
+    # Will be fixed in mypy 1.8 (https://github.com/python/mypy/pull/15896)
     context.run(aiotrio_run, trio_main, host_uses_signal_set_wakeup_fd=True)  # type: ignore[arg-type]
 
     assert record == {("asyncio", "asyncio"), ("trio", "trio")}

src/trio/_core/_tests/test_local.py

@@ -77,8 +77,8 @@ async def task1() -> None:
             t1.set("plaice")
             assert t1.get() == "plaice"
 
-        async def task2(tok: str) -> None:
-            t1.reset(token)
+        async def task2(tok: RunVarToken[str]) -> None:
+            t1.reset(tok)
 
             with pytest.raises(LookupError):
                 t1.get()

src/trio/_core/_tests/test_run.py

@@ -1482,6 +1482,7 @@ async def child2() -> None:
         assert tasks["child2"].child_nurseries == []
 
     async def child1(
+        *,
         task_status: _core.TaskStatus[None] = _core.TASK_STATUS_IGNORED,
     ) -> None:
         me = tasks["child1"] = _core.current_task()
@@ -1704,6 +1705,7 @@ async def sleep_then_start(
 
     # calling started twice
     async def double_started(
+        *,
         task_status: _core.TaskStatus[None] = _core.TASK_STATUS_IGNORED,
     ) -> None:
         task_status.started()
@@ -1715,6 +1717,7 @@ async def double_started(
 
     # child crashes before calling started -> error comes out of .start()
     async def raise_keyerror(
+        *,
         task_status: _core.TaskStatus[None] = _core.TASK_STATUS_IGNORED,
     ) -> None:
         raise KeyError("oops")
@@ -1725,6 +1728,7 @@ async def raise_keyerror(
 
     # child exiting cleanly before calling started -> triggers a RuntimeError
     async def nothing(
+        *,
         task_status: _core.TaskStatus[None] = _core.TASK_STATUS_IGNORED,
     ) -> None:
         return
@@ -1738,6 +1742,7 @@ async def nothing(
     # nothing -- the child keeps executing under start(). The value it passed
     # is ignored; start() raises Cancelled.
     async def just_started(
+        *,
         task_status: _core.TaskStatus[str] = _core.TASK_STATUS_IGNORED,
     ) -> None:
         task_status.started("hi")
@@ -1920,7 +1925,7 @@ def __init__(self, *largs: it) -> None:
             self.nexts = [obj.__anext__ for obj in largs]
 
         async def _accumulate(
-            self, f: Callable[[], Awaitable[int]], items: list[int | None], i: int
+            self, f: Callable[[], Awaitable[int]], items: list[int], i: int
         ) -> None:
             items[i] = await f()
 

src/trio/_core/type_tests/nursery_start.py

@@ -0,0 +1,78 @@
+"""Test variadic generic typing for Nursery.start[_soon]()."""
+from trio import TASK_STATUS_IGNORED, Nursery, TaskStatus
+
+
+async def task_0() -> None:
+    ...
+
+
+async def task_1a(value: int) -> None:
+    ...
+
+
+async def task_1b(value: str) -> None:
+    ...
+
+
+async def task_2a(a: int, b: str) -> None:
+    ...
+
+
+async def task_2b(a: str, b: int) -> None:
+    ...
+
+
+async def task_2c(a: str, b: int, optional: bool = False) -> None:
+    ...
+
+
+async def task_requires_kw(a: int, *, b: bool) -> None:
+    ...
+
+
+async def task_startable_1(
+    a: str,
+    *,
+    task_status: TaskStatus[bool] = TASK_STATUS_IGNORED,
+) -> None:
+    ...
+
+
+async def task_startable_2(
+    a: str,
+    b: float,
+    *,
+    task_status: TaskStatus[bool] = TASK_STATUS_IGNORED,
+) -> None:
+    ...
+
+
+async def task_requires_start(*, task_status: TaskStatus[str]) -> None:
+    """Check a function requiring start() to be used."""
+
+
+async def task_pos_or_kw(value: str, task_status: TaskStatus[int]) -> None:
+    """Check a function which doesn't use the *-syntax works."""
+    ...
+
+
+def check_start_soon(nursery: Nursery) -> None:
+    """start_soon() functionality."""
+    nursery.start_soon(task_0)
+    nursery.start_soon(task_1a)  # type: ignore
+    nursery.start_soon(task_2b)  # type: ignore
+
+    nursery.start_soon(task_0, 45)  # type: ignore
+    nursery.start_soon(task_1a, 32)
+    nursery.start_soon(task_1b, 32)  # type: ignore
+    nursery.start_soon(task_1a, "abc")  # type: ignore
+    nursery.start_soon(task_1b, "abc")
+
+    nursery.start_soon(task_2b, "abc")  # type: ignore
+    nursery.start_soon(task_2a, 38, "46")
+    nursery.start_soon(task_2c, "abc", 12)
+    nursery.start_soon(task_2c, "abc", 12, True)
+
+    nursery.start_soon(task_requires_kw, 12, True)  # type: ignore
+    # Tasks following the start() API can be made to work.
+    nursery.start_soon(task_startable_1, "cdf")