From 451393acec35c3a01cba0c19de6bf8f6f23dbc7b Mon Sep 17 00:00:00 2001
From: John Litborn <11260241+jakkdl@users.noreply.github.com>
Date: Fri, 14 Jun 2024 16:59:13 +0200
Subject: [PATCH] [docs] clarify checkpoint semantics for trio.open_nursery
 (#3011)

* clarify checkpoint semantics for trio.open_nursery

* clarify what schedule-but-no-cancellation-point means for nurseries
---
 docs/source/reference-core.rst | 2 ++
 src/trio/_core/_run.py         | 6 +++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/source/reference-core.rst b/docs/source/reference-core.rst
index ae0e3bdcec..6808f930c6 100644
--- a/docs/source/reference-core.rst
+++ b/docs/source/reference-core.rst
@@ -102,6 +102,8 @@ them. Here are the rules:
     only that one will act as a checkpoint. This is documented
     on a case-by-case basis.
 
+    * :func:`trio.open_nursery` is a further exception to this rule.
+
 * Third-party async functions / iterators / context managers can act
   as checkpoints; if you see ``await <something>`` or one of its
   friends, then that *might* be a checkpoint. So to be safe, you
diff --git a/src/trio/_core/_run.py b/src/trio/_core/_run.py
index df01519589..1eddaad431 100644
--- a/src/trio/_core/_run.py
+++ b/src/trio/_core/_run.py
@@ -986,7 +986,11 @@ def open_nursery(
     new `Nursery`.
 
     It does not block on entry; on exit it blocks until all child tasks
-    have exited.
+    have exited. If no child tasks are running on exit, it will insert a
+    schedule point (but no cancellation point) - equivalent to
+    :func:`trio.lowlevel.cancel_shielded_checkpoint`. This means a nursery
+    is never the source of a cancellation exception, it only propagates it
+    from sub-tasks.
 
     Args:
       strict_exception_groups (bool): Unless set to False, even a single raised exception