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 `` 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 89759cc2c2..ba47e1d799 100644 --- a/src/trio/_core/_run.py +++ b/src/trio/_core/_run.py @@ -993,7 +993,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