Add message with debugging info to Cancelled

src/trio/_core/_exceptions.py

@@ -73,27 +73,30 @@ class Cancelled(BaseException, metaclass=NoPublicConstructor):
 
     """
 
-    source: Literal["deadline", "nursery", "explicit", "unknown", "KeyboardInterrupt"]
-    # TODO: this should probably be a Task?
+    source: Literal[
+        "KeyboardInterrupt", "deadline", "explicit", "nursery", "shutdown", "unknown"
+    ]
+    # repr(Task), so as to avoid gc troubles from holding a reference
     source_task: str | None = None
     reason: str | None = None
 
     def __str__(self) -> str:
-        def repr_if_not_none(lead: str, s: str | None, trail: str = "") -> str:
+        def repr_if_not_none(lead: str, s: str | None, do_repr: bool = False) -> str:
             if s is None:
                 return ""
-            return lead + s + trail
+            if do_repr:
+                return lead + repr(s)
+            return lead + s
 
         return (
             f"cancelled due to {self.source}"
-            + repr_if_not_none(" with reason '", self.reason, "'")
+            + repr_if_not_none(" with reason ", self.reason, True)
             + repr_if_not_none(" from task ", self.source_task)
         )
 
     def __reduce__(self) -> tuple[Callable[[], Cancelled], tuple[()]]:
         # the `__reduce__` tuple does not support kwargs, so we must use partial
         # for non-default args
-        # or switch to allow posarg (?)
         return (
             partial(
                 Cancelled._create,
@@ -111,7 +114,12 @@ def _create(
             cls,
             *,
             source: Literal[
-                "deadline", "nursery", "explicit", "unknown", "KeyboardInterrupt"
+                "KeyboardInterrupt",
+                "deadline",
+                "explicit",
+                "nursery",
+                "shutdown",
+                "unknown",
             ],
             source_task: str | None = None,
             reason: str | None = None,

src/trio/_core/_run.py

@@ -318,8 +318,14 @@ def expire(self, now: float) -> bool:
 
 @attrs.define
 class CancelReason:
-    # TODO: loren ipsum
-    source: Literal["deadline", "nursery", "explicit", "KeyboardInterrupt"]
+    """Attached to a :class:`CancelScope` upon cancellation with details of the source of the
+    cancellation, which is then used to construct the string in a :exc:`Cancelled`.
+    Users can pass a ``reason`` str to :meth:`CancelScope.cancel` to set it.
+    """
+
+    source: Literal[
+        "KeyboardInterrupt", "deadline", "explicit", "nursery", "shutdown", "unknown"
+    ]
     source_task: str | None = None
     reason: str | None = None
 
@@ -580,8 +586,6 @@ class CancelScope:
     _cancel_called: bool = attrs.field(default=False, init=False)
     cancelled_caught: bool = attrs.field(default=False, init=False)
 
-    # necessary as cancel_status might be None
-    # TODO: but maybe cancel_status doesn't need it?
     _cancel_reason: CancelReason | None = attrs.field(
         default=None, init=False, repr=True
     )
@@ -1230,9 +1234,10 @@ def parent_task(self) -> Task:
         "(`~trio.lowlevel.Task`):  The Task that opened this nursery."
         return self._parent_task
 
-    def _add_exc(self, exc: BaseException) -> None:
+    def _add_exc(self, exc: BaseException, reason: CancelReason | None) -> None:
         self._pending_excs.append(exc)
-        # TODO: source/reason?
+        if self.cancel_scope._cancel_reason is None:
+            self.cancel_scope._cancel_reason = reason
         self.cancel_scope.cancel()
 
     def _check_nursery_closed(self) -> None:
@@ -1249,11 +1254,14 @@ def _child_finished(
     ) -> None:
         self._children.remove(task)
         if isinstance(outcome, Error):
-            if self.cancel_scope._cancel_reason is None:
-                self.cancel_scope._cancel_reason = CancelReason(
-                    source="nursery", source_task=repr(task)
-                )
-            self._add_exc(outcome.error)
+            self._add_exc(
+                outcome.error,
+                CancelReason(
+                    source="nursery",
+                    source_task=repr(task),
+                    reason=f"child task raised exception {outcome.error!r}",
+                ),
+            )
         self._check_nursery_closed()
 
     async def _nested_child_finished(
@@ -1263,7 +1271,14 @@ async def _nested_child_finished(
         # Returns ExceptionGroup instance (or any exception if the nursery is in loose mode
         # and there is just one contained exception) if there are pending exceptions
         if nested_child_exc is not None:
-            self._add_exc(nested_child_exc)
+            self._add_exc(
+                nested_child_exc,
+                reason=CancelReason(
+                    source="nursery",
+                    source_task=repr(self._parent_task),
+                    reason=f"Code block inside nursery contextmanager raised exception {nested_child_exc!r}",
+                ),
+            )
         self._nested_child_running = False
         self._check_nursery_closed()
 
@@ -1274,7 +1289,13 @@ async def _nested_child_finished(
             def aborted(raise_cancel: _core.RaiseCancelT) -> Abort:
                 exn = capture(raise_cancel).error
                 if not isinstance(exn, Cancelled):
-                    self._add_exc(exn)
+                    self._add_exc(
+                        exn,
+                        CancelReason(
+                            source="KeyboardInterrupt",
+                            source_task=repr(self._parent_task),
+                        ),
+                    )
                 # see test_cancel_scope_exit_doesnt_create_cyclic_garbage
                 del exn  # prevent cyclic garbage creation
                 return Abort.FAILED
@@ -1288,7 +1309,8 @@ def aborted(raise_cancel: _core.RaiseCancelT) -> Abort:
             try:
                 await cancel_shielded_checkpoint()
             except BaseException as exc:
-                self._add_exc(exc)
+                # there's no children to cancel, so don't need to supply cancel reason
+                self._add_exc(exc, reason=None)
 
         popped = self._parent_task._child_nurseries.pop()
         assert popped is self
@@ -2134,6 +2156,12 @@ async def init(
 
                 # Main task is done; start shutting down system tasks
                 # TODO: source/reason?
+                self.system_nursery.cancel_scope._cancel_reason = CancelReason(
+                    source="shutdown",
+                    reason="main task done, shutting down system tasks",
+                    source_task=repr(self.init_task),
+                )
+
                 self.system_nursery.cancel_scope.cancel()
 
             # System nursery is closed; finalize remaining async generators

src/trio/_core/_tests/test_cancel.py

@@ -9,6 +9,8 @@
 from trio.lowlevel import current_task
 from trio.testing import RaisesGroup
 
+from .test_ki import ki_self
+
 
 async def test_cancel_reason() -> None:
     with trio.CancelScope() as cs:
@@ -42,7 +44,8 @@ async def cancelled_task(
     ) -> None:
         task_status.started()
         with pytest.raises(
-            Cancelled, match=rf"^cancelled due to nursery from task {fail_task!r}$"
+            Cancelled,
+            match=rf"^cancelled due to nursery with reason 'child task raised exception ValueError\(\)' from task {fail_task!r}$",
         ):
             await trio.sleep_forever()
         raise TypeError
@@ -66,7 +69,8 @@ async def cancelled_task(
     ) -> None:
         task_status.started()
         with pytest.raises(
-            Cancelled, match=rf"^cancelled due to nursery from task {fail_task!r}$"
+            Cancelled,
+            match=rf"^cancelled due to nursery with reason 'child task raised exception ValueError\(\)' from task {fail_task!r}$",
         ):
             await trio.sleep_forever()
         raise TypeError
@@ -103,3 +107,45 @@ async def test_cancel_reason_not_overwritten_2() -> None:
         cs.cancel()
         with pytest.raises(Cancelled, match=r"^cancelled due to deadline$"):
             await trio.lowlevel.checkpoint()
+
+
+async def test_nested_child_source() -> None:
+    ev = trio.Event()
+    parent_task = current_task()
+
+    async def child() -> None:
+        ev.set()
+        with pytest.raises(
+            Cancelled,
+            match=rf"^cancelled due to nursery with reason 'Code block inside nursery contextmanager raised exception ValueError\(\)' from task {parent_task!r}$",
+        ):
+            await trio.sleep_forever()
+
+    with RaisesGroup(ValueError):
+        async with trio.open_nursery() as nursery:
+            nursery.start_soon(child)
+            await ev.wait()
+            raise ValueError
+
+
+async def test_reason_delayed_ki() -> None:
+    # simplified version of test_ki.test_ki_protection_works check #2
+    parent_task = current_task()
+
+    async def sleeper(name: str) -> None:
+        with pytest.raises(
+            Cancelled,
+            match=rf"^cancelled due to KeyboardInterrupt from task {parent_task!r}$",
+        ):
+            while True:
+                await trio.lowlevel.checkpoint()
+
+    async def raiser(name: str) -> None:
+        ki_self()
+
+    with RaisesGroup(KeyboardInterrupt):
+        async with trio.open_nursery() as nursery:
+            nursery.start_soon(sleeper, "s1")
+            nursery.start_soon(sleeper, "s2")
+            nursery.start_soon(trio.lowlevel.enable_ki_protection(raiser), "r1")
+            # __aexit__ blocks, and then receives the KI

src/trio/_subprocess.py

@@ -766,8 +766,7 @@ async def killer() -> None:
 
                 nursery.start_soon(killer)
                 await proc.wait()
-                # TODO: source/reason?
-                killer_cscope.cancel()
+                killer_cscope.cancel(reason="trio internal implementation detail")
                 raise
 
     stdout = b"".join(stdout_chunks) if capture_stdout else None