In to_thread_run_sync(), add abandon_on_cancel= as an alias for the cancellable= flag

trio/_tests/test_threads.py

@@ -29,6 +29,7 @@
     CancelScope,
     CapacityLimiter,
     Event,
+    TrioDeprecationWarning,
     _core,
     fail_after,
     move_on_after,
@@ -556,7 +557,7 @@ def release_on_behalf_of(self, borrower: Task) -> None:
 
     # TODO: should CapacityLimiter have an abc or protocol so users can modify it?
     # because currently it's `final` so writing code like this is not allowed.
-    await to_thread_run_sync(lambda: None, limiter=CustomLimiter())  # type: ignore[arg-type]
+    await to_thread_run_sync(lambda: None, limiter=CustomLimiter())  # type: ignore[call-overload]
     assert record == ["acquire", "release"]
 
 
@@ -574,7 +575,7 @@ def release_on_behalf_of(self, borrower: Task) -> NoReturn:
     bs = BadCapacityLimiter()
 
     with pytest.raises(ValueError) as excinfo:
-        await to_thread_run_sync(lambda: None, limiter=bs)  # type: ignore[arg-type]
+        await to_thread_run_sync(lambda: None, limiter=bs)  # type: ignore[call-overload]
     assert excinfo.value.__context__ is None
     assert record == ["acquire", "release"]
     record = []
@@ -583,7 +584,7 @@ def release_on_behalf_of(self, borrower: Task) -> NoReturn:
     # chains with it
     d: dict[str, object] = {}
     with pytest.raises(ValueError) as excinfo:
-        await to_thread_run_sync(lambda: d["x"], limiter=bs)  # type: ignore[arg-type]
+        await to_thread_run_sync(lambda: d["x"], limiter=bs)  # type: ignore[call-overload]
     assert isinstance(excinfo.value.__context__, KeyError)
     assert record == ["acquire", "release"]
 
@@ -892,7 +893,7 @@ def __bool__(self) -> bool:
             raise NotImplementedError
 
     with pytest.raises(NotImplementedError):
-        await to_thread_run_sync(int, abandon_on_cancel=BadBool())  # type: ignore[arg-type]
+        await to_thread_run_sync(int, abandon_on_cancel=BadBool())  # type: ignore[call-overload]
 
 
 async def test_from_thread_reuses_task() -> None:
@@ -1081,15 +1082,15 @@ async def child() -> None:
 
 async def test_cancellable_and_abandon_raises() -> None:
     with pytest.raises(ValueError):
-        await to_thread_run_sync(bool, cancellable=True, abandon_on_cancel=False)
+        await to_thread_run_sync(bool, cancellable=True, abandon_on_cancel=False)  # type: ignore[call-overload]
 
     with pytest.raises(ValueError):
-        await to_thread_run_sync(bool, cancellable=True, abandon_on_cancel=True)
+        await to_thread_run_sync(bool, cancellable=True, abandon_on_cancel=True)  # type: ignore[call-overload]
 
 
 async def test_cancellable_warns() -> None:
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(TrioDeprecationWarning):
         await to_thread_run_sync(bool, cancellable=False)
 
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(TrioDeprecationWarning):
         await to_thread_run_sync(bool, cancellable=True)

trio/_threads.py

@@ -6,7 +6,6 @@
 import inspect
 import queue as stdlib_queue
 import threading
-import warnings
 from collections.abc import Awaitable, Callable
 from itertools import count
 from typing import Generic, TypeVar, overload
@@ -16,7 +15,6 @@
 from sniffio import current_async_library_cvar
 
 import trio
-from trio._core._traps import RaiseCancelT
 
 from ._core import (
     RunVar,
@@ -25,6 +23,8 @@
     enable_ki_protection,
     start_thread_soon,
 )
+from ._core._traps import RaiseCancelT
+from ._deprecate import warn_deprecated
 from ._sync import CapacityLimiter
 from ._util import coroutine_or_error
 
@@ -172,8 +172,8 @@ def run_in_system_nursery(self, token: TrioToken) -> None:
         token.run_sync_soon(self.run_sync)
 
 
-@overload
-async def to_thread_run_sync(
+@overload  # Decorator used on function with Coroutine[Any, Any, RetT]
+async def to_thread_run_sync(  # type: ignore[misc]
     sync_fn: Callable[..., RetT],
     *args: object,
     thread_name: str | None = None,
@@ -183,8 +183,8 @@ async def to_thread_run_sync(
     ...
 
 
-@overload
-async def to_thread_run_sync(
+@overload  # Decorator used on function with Coroutine[Any, Any, RetT]
+async def to_thread_run_sync(  # type: ignore[misc]
     sync_fn: Callable[..., RetT],
     *args: object,
     thread_name: str | None = None,
@@ -292,11 +292,11 @@ async def to_thread_run_sync(  # type: ignore[misc]
             raise ValueError(
                 "Cannot set `cancellable` and `abandon_on_cancel` simultaneously."
             )
-        warnings.warn(
-            DeprecationWarning(
-                "`cancellable` keyword argument is deprecated, "
-                "use `abandon on cancel` instead."
-            )
+        warn_deprecated(
+            "`cancellable=` keyword argument",
+            "0.23.0",
+            issue=2841,
+            instead="`abandon_on_cancel=` keyword argument",
         )
         abandon_on_cancel = cancellable
     # raise early if abandon_on_cancel.__bool__ raises