A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

This doesn't work in the case that the body of the task group throws an exception, as in this code:

    async def test_taskgroup_throw_inside(self):

        class MyError(RuntimeError):
            pass

        should_get_here = False
        try:
            async with asyncio.TaskGroup() as tg:
                tg.create_task(asyncio.sleep(0.1))
                tg.stop()
                self.assertEqual(asyncio.current_task().cancelling(), 1)
                raise MyError
            self.fail()  # <-- reaches here instead of raising ExceptionGroup([MyError()])
        except* MyError:
            self.assertEqual(asyncio.current_task().cancelling(), 0)
            should_get_here = True
        self.assertTrue(should_get_here)

The problem is that the new code in the _aexit() method, if not self._errors: return True, is essentially duplicating the if self._errors test later in the function, but in between self._errors is changed by these two lines:

        if et is not None and not issubclass(et, exceptions.CancelledError):
            self._errors.append(exc)

One option is move these lines earlier, before the if self._parent_cancel_requested statement. Then both tests are checking the same thing. This seems to work.

I'd still suggest my original proposal (see the issue) where you just add a single line return True to the very end of _exit() instead of these changes. This avoids duplicating the test in the first place and avoids changing the control flow and, personally, I find it easier to follow.

As a separate point, I'd suggest that the tests could do with a few more checks that asyncio.current_task().cancelling() is correct, like the ones in the test above in this comment.

@1st1

Why call it TaskGroup.stop() and not TaskGroup.cancel()? I'd be more in favor of the latter name.

I'd also prefer cancel(), but per Guido it would be confusing since such a method would be expected to raise CancelledError, and he suggested stop().

Short-circuiting of task groups is a very common, useful, and normal, so make it a first-class operation.

Any evidence of this statement? I'd like you to write up technical motivation + examples. That will be useful for the docs.

In trio the equivalent is nursery.cancel_scope.cancel(), which has > 1,000 hits on github, despite the unpopularity of trio.

I have years experience developing a non-trivial, production async app, which I've presented at PyCon JP. Anecdotally, I can't imagine how painful and unproductive it would be to not have short circuiting of task groups.

And speaking of the documentation, you should also show some recipies of how this would be used. Like are you supposed to use this API from within the task group async with clause? Or can you pass the task group to some remote task?

All is on the table: stop from within the TaskGroup body, from a child, from some other entity you've passed the bound stop() method to.

I'd also prefer cancel(), but per Guido it would be confusing since such a method would be expected to raise CancelledError,

Well, that's exactly what it does, isn't it? The fact that the cancelled taskgroup catches the CancelledErrors raised by itself doesn't change that. You don't get to wait on taskgroups the way you wait on tasks, thus the exception isn't visible like when you await on a cancelled task, but that's a minor detail IMHO.

Also, trio and anyio already call this operation cancel.

For email readers: Sorry; there is no PR by @smurfix -- he opened the issue. I think that with the feedback (mine and others') addressed (possibly by explaining why no change is needed!) and a decision on the name (stop or cancel) made we can merge this in time before the May 1st beta deadline (in ~10 days).

Also there are merge conflicts. :-(

[@1st1 / Yury -- on Nov 25, 2024]

Why call it TaskGroup.stop() and not TaskGroup.cancel()? I'd be more in favor of the latter name.

Hm. If Yury's intuition goes towards cancel(), I revoke my opposition to it. Decision made: it's cancel().

Short-circuiting of task groups is a very common, useful, and normal, so make it a first-class operation.

Any evidence of this statement? I'd like you to write up technical motivation + examples. That will be useful for the docs.

The main evidence is the huge paragraph that was added to the 3.12/3.13/3.14 docs about how to terminate a TaskGroup.

And speaking of the documentation, you should also show some recipes of how this would be used. Like are you supposed to use this API from within the task group async with clause? Or can you pass the task group to some remote task?

All of the above. Whoever has a reference to a TaskGroup can call its cancel() and the right thing will happen.

I haven't reviewed the actual implementation in detail yet.

I have and it's fine.

A failing test complains about deleting a label ("Terminating a Task Group"):

The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
library/asyncio-task.html: terminating-a-task-group

Alternatively, add them to Doc/tools/removed-ids.txt.

I think the latter is best -- though you could also bring the label back with only the body text (paraphrased):

Use the new cancel() method. Or refer to the 3.14 docs to do it in a backwards-compatible way.

@belm0 -- I take it you are not planning to add cancel messages and you are not planning to add more examples to the docs? Once you confirm that I will approve and merge.

@belm0 Thanks for your perseverance! This looks like a useful addition.

Additionally we probably need a "what's new" entry, and I have some nits on the docs (mostly that I find the term "short-circuit" confusing, I've not seen it in the context of asyncio or task groups).