gh-102560 Add docstrings to asyncio.TaskGroup

[JosephSBoyle]

Adds docstrings to the public methods of asyncio.TaskGroup.

• Issue: Add docstrings to asyncio.TaskGroup #102560

[AlexWaygood]

Please fix the trailing whitespace issues that the Azure Pipelines CI check is complaining about

[bedevere-bot]

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.

[gvanrossum]

I desperate wish for something half the size.

[gvanrossum]

Why not just

Suggested change

	Matches the call signature of asyncio.create_task.
	Similar to `asyncio.create_task`.

[olijeffers0n]

The part about Exceptions seems a bit long winded. Maybe just:

Any exceptions other than asyncio.CancelledError's raised within tasks will cancel all remaining tasks and exit the context. These exceptions will be combined into an ExceptionGroup and re-raised.

As a replacement?

[gvanrossum]

@JosephSBoyle Can you please respond to the review comments? (PS. There's no need to merge main, even if GitHub recommends it, unless it says there's also a merge conflict.)

[JosephSBoyle]

Thanks for the comments!

@AlexWaygood I believe I've fixed the whitespace issue.
@gvanrossum and @olijeffers0n I've adopted your suggestions.

Thanks for the tip on merging! 🙇‍♂️

---

A thought of my own, maybe we could remove the 'Similar to `asyncio.create_task' line entirely and just have:

    def create_task(self, coro, *, name=None, context=None):
        """Create a new task in this group and return it."""

I think people intuitively would expect asyncio.create_task and asyncio.TaskGroup().create_task to be similar from name alone which makes the statement redundant.

Requested changes were made

[kumaraditya303]

I defer to Alex and Guido on this.

[AlexWaygood]

It reads okay to me now, but I'm neither an asyncio maintainer nor an asyncio expert, so I'll defer to @gvanrossum and Kumar on whether the technical accuracy is okay and whether the style of the docstring is desirable.

Thanks for working on this!

[JosephSBoyle]

Thanks for your help Alex:)
🙇‍♂️

[gvanrossum]

I have a slight rephrasing and some whitespace/markup nits, then LGTM.

I can commit those and land this unless you object.

[JosephSBoyle]

Hi @gvanrossum, feel free to commit the changes you proposed:)

[gvanrossum]

Thanks! It's a real improvement to have this.

[miss-islington]

Thanks @JosephSBoyle for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-102715 is a backport of this pull request to the 3.11 branch.

[JosephSBoyle]

Happy to help!:)
🙇‍♂️

[gvanrossum]

If you want another project like this, timeouts.py also needs docstrings.

[JosephSBoyle]

If you want another project like this, timeouts.py also needs docstrings.

Nice, I've opened a PR to add docstrings here: #102811.