Change fail_after&move_on_after to set deadline relative to entering. Add CancelScope.relative_deadline

newsfragments/2512.breaking.rst

@@ -0,0 +1,18 @@
+:func:`trio.move_on_after` and :func:`trio.fail_after` now sets the deadline upon entering the context manager, instead of at initialization. The vast majority of usage initialized them when entering and is therefore unaffected. But if you have code that looks like:
+
+.. code-block:: python3
+
+    cs = trio._move_on_after(5)
+    ...
+    with cs:
+        ...
+
+
+the deadline of the underlying :func:`trio.CancelScope` will now differ. If you want to fully preserve current behaviour you can rewrite it as
+
+.. code-block:: python3
+
+   cs = trio.move_on_at(trio.current_time() + 5)
+   ...
+   with cs:
+       ...

newsfragments/2512.feature.rst

@@ -0,0 +1,13 @@
+:func:`trio.CancelScope` now has an attribute ``relative_deadline`` that can be used together with, or instead of, ``deadline``. :ref:`trio.move_on_after` and :ref:`trio.fail_after` now use this functionality in order to resolve the absolute deadline upon entering the context manager.
+
+If setting both ``deadline`` and ``relative_deadline`` before entering the cm, the deadline will be set to ``min(deadline, trio.current_time() + relative_deadline)``.
+Accessing ``relative_deadline`` after entering will return remaining time until deadline (i.e. ``deadline - trio.current_time()``. Setting ``relative_deadline`` after entering will set ``deadline`` to ``trio.current_time() + relative_deadline``
+
+Example:
+
+.. code-block:: python3
+
+   my_cs = trio.CancelScope(relative_deadline = 5)
+   ...
+   with my_cs:  # my_cs.deadline will now be 5 seconds into the future
+       ...

src/trio/_core/_run.py

@@ -540,6 +540,11 @@ class CancelScope:
 
     # Constructor arguments:
     _deadline: float = attrs.field(default=inf, kw_only=True, alias="deadline")
+    # use float|None, or math.inf?
+    # or take it as an opportunity to also introduce deadline=None?
+    _relative_deadline: float | None = attrs.field(
+        default=None, kw_only=True, alias="relative_deadline"
+    )
     _shield: bool = attrs.field(default=False, kw_only=True, alias="shield")
 
     @enable_ki_protection
@@ -550,6 +555,13 @@ def __enter__(self) -> Self:
                 "Each CancelScope may only be used for a single 'with' block"
             )
         self._has_been_entered = True
+
+        if self._relative_deadline is not None:
+            if self._relative_deadline + current_time() < self._deadline:
+                self._deadline = self._relative_deadline + current_time()
+            else:
+                self._relative_deadline = self.deadline - current_time()
+
         if current_time() >= self._deadline:
             self.cancel()
         with self._might_change_registered_deadline():
@@ -744,6 +756,25 @@ def deadline(self, new_deadline: float) -> None:
         with self._might_change_registered_deadline():
             self._deadline = float(new_deadline)
 
+    @property
+    def relative_deadline(self) -> float | None:
+        """TODO: write docstring"""
+        if self._has_been_entered:
+            if self.deadline == inf:
+                return None
+            return self._deadline - current_time()
+        return self._relative_deadline
+
+    @relative_deadline.setter
+    def relative_deadline(self, relative_deadline: float | None) -> None:
+        self._relative_deadline = relative_deadline
+        if self._has_been_entered:
+            with self._might_change_registered_deadline():
+                if relative_deadline is None:
+                    self._deadline = inf
+                else:
+                    self._deadline = current_time() + relative_deadline
+
     @property
     def shield(self) -> bool:
         """Read-write, :class:`bool`, default :data:`False`. So long as

src/trio/_core/_tests/test_run.py

@@ -601,6 +601,49 @@ async def test_basic_timeout(mock_clock: _core.MockClock) -> None:
             await _core.checkpoint()
 
 
+async def test_relative_timeout(mock_clock: _core.MockClock) -> None:
+    # test defaults
+    scope = _core.CancelScope()
+    assert scope.deadline == inf
+    assert scope.relative_deadline is None
+
+    # setting relative_deadline before entering does not modify deadline
+    scope.relative_deadline = 1
+    assert scope.deadline == inf
+    assert scope.relative_deadline == 1
+
+    # check that setting either deadline updates the other (after entering)
+    start = _core.current_time()
+    with scope:
+        assert scope.deadline == start + 1
+        scope.relative_deadline = 2
+        assert scope.deadline == start + 2
+        scope.deadline = start + 3
+        assert scope.relative_deadline == 3
+
+    # relative_deadline < deadline, deadline is updated
+    with _core.CancelScope(relative_deadline=1, deadline=start + 2) as scope:
+        assert scope.deadline == start + 1
+        assert scope.relative_deadline == 1
+
+    # deadline < relative_deadline, relative_deadline is updated
+    with _core.CancelScope(relative_deadline=2, deadline=start + 1):
+        assert scope.deadline == start + 1
+        assert scope.relative_deadline == 1
+
+    # once entered, accessing relative_deadline returns deadline-now()
+    # and setting it calculates it relative to now()
+    start = _core.current_time()
+    with _core.CancelScope(relative_deadline=3) as scope:
+        mock_clock.jump(1)
+        assert scope.relative_deadline == 2
+        mock_clock.jump(1)
+        assert scope.relative_deadline == 1
+        scope.relative_deadline = 3
+        mock_clock.jump(1)
+        assert scope.relative_deadline == 2
+
+
 async def test_cancel_scope_nesting() -> None:
     # Nested scopes: if two triggering at once, the outer one wins
     with _core.CancelScope() as scope1:

src/trio/_tests/test_timeouts.py

@@ -129,3 +129,23 @@ async def test_timeouts_raise_value_error() -> None:
         ):
             with cm(val):
                 pass  # pragma: no cover
+
+
+async def test_timeout_deadline_on_entry(mock_clock: _core.MockClock) -> None:
+    cs = move_on_after(5)
+    assert cs.relative_deadline == 5
+    mock_clock.jump(3)
+    start = _core.current_time()
+    with cs:
+        # This would previously be start+2
+        assert cs.deadline == start + 5
+        assert cs.relative_deadline == 5
+
+    # because fail_after is a wrapping contextmanager we cannot directly inspect
+    # cs_gen.relative_deadline before entering
+    cs_gen = fail_after(5)
+    mock_clock.jump(3)
+    start = _core.current_time()
+    with cs_gen as cs:
+        assert cs.deadline == start + 5
+        assert cs.relative_deadline == 5

src/trio/_timeouts.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 import math
-from contextlib import AbstractContextManager, contextmanager
+from contextlib import contextmanager
 from typing import TYPE_CHECKING
 
 import trio
 
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
 
 def move_on_at(deadline: float) -> trio.CancelScope:
     """Use as a context manager to create a cancel scope with the given
@@ -36,7 +39,9 @@ def move_on_after(seconds: float) -> trio.CancelScope:
     """
     if seconds < 0:
         raise ValueError("timeout must be non-negative")
-    return move_on_at(trio.current_time() + seconds)
+    if math.isnan(seconds):
+        raise ValueError("timeout must not be NaN")
+    return trio.CancelScope(relative_deadline=seconds)
 
 
 async def sleep_forever() -> None:
@@ -94,9 +99,8 @@ class TooSlowError(Exception):
     """
 
 
-# workaround for PyCharm not being able to infer return type from @contextmanager
-# see https://youtrack.jetbrains.com/issue/PY-36444/PyCharm-doesnt-infer-types-when-using-contextlib.contextmanager-decorator
-def fail_at(deadline: float) -> AbstractContextManager[trio.CancelScope]:  # type: ignore[misc]
+@contextmanager
+def fail_at(deadline: float) -> Generator[trio.CancelScope, None, None]:
     """Creates a cancel scope with the given deadline, and raises an error if it
     is actually cancelled.
 
@@ -123,11 +127,8 @@ def fail_at(deadline: float) -> AbstractContextManager[trio.CancelScope]:  # typ
         raise TooSlowError
 
 
-if not TYPE_CHECKING:
-    fail_at = contextmanager(fail_at)
-
-
-def fail_after(seconds: float) -> AbstractContextManager[trio.CancelScope]:
+@contextmanager
+def fail_after(seconds: float) -> Generator[trio.CancelScope, None, None]:
     """Creates a cancel scope with the given timeout, and raises an error if
     it is actually cancelled.
 
@@ -150,6 +151,7 @@ def fail_after(seconds: float) -> AbstractContextManager[trio.CancelScope]:
       ValueError: if *seconds* is less than zero or NaN.
 
     """
-    if seconds < 0:
-        raise ValueError("timeout must be non-negative")
-    return fail_at(trio.current_time() + seconds)
+    with move_on_after(seconds) as scope:
+        yield scope
+    if scope.cancelled_caught:
+        raise TooSlowError