Add docstrings to asyncio.TaskGroup

[JosephSBoyle]

Python 3.11 added asyncio.TaskGroup[0]. We should encourage users of the language to use this class by adding docstrings and type-hinting, particularly since it has wide applications for users wishing to refactor their existing async code.

I'm happy to work on this but any suggestions for what the docstrings should include is welcome.

[0] https://docs.python.org/3/library/asyncio-task.html

Linked PRs

• gh-102560 Add docstrings to asyncio.TaskGroup #102565
• [3.11] gh-102560 Add docstrings to asyncio.TaskGroup (GH-102565) #102715

[AlexWaygood]

Type hints for stdlib classes are generally added over at the typeshed repository (where contributions are very welcome!) rather than integrating them into the CPython source code directly. This is for a bunch of reasons -- some historical, but some that are still quite relevant. This doesn't mean that you won't find the occasional type hint in the CPython source code, but it isn't generally a goal to add type hints everywhere, nor to increase the level of "type annotation coverage" in the CPython repo.

Our annotations for asyncio.TaskGroup over at typeshed look pretty complete, so I think type checkers and IDEs should have everything they need for this class already in terms of type annotations :)

[gvanrossum]

That leaves docstrings. @JosephSBoyle do you want to contribute?

[JosephSBoyle]

Ah, okay @AlexWaygood, thanks again for the explanation 🙇

---

Certainly, @gvanrossum. Here's a draft, largely adapted from the docs, with the main addition being the section about how once the context is exited the group's tasks are all either finished or cancelled.

class TaskGroup:
    """An asynchronous context manager for managing groups of tasks.

    Example use:

        async with asyncio.TaskGroup() as group:
            task1 = group.create_task(some_coroutine(...))
            task2 = group.create_task(other_coroutine(...))
        
        print("Both tasks have completed now.")

    All tasks are awaited when the context manager exits.

    Once the context has been exited it's guaranteed that no tasks
    from the group remain alive. That is, all tasks are guaranteed
    to have either finished successfully or have been cancelled.

    Any exceptions other than asyncio.CancelledError's raised within
    tasks cause each of the remaining tasks to be cancelled and the
    context to be exited.

    Once all tasks have finished, if any tasks have failed with an
    exception other than asyncio.CancelledError, those exceptions are
    combined in an ExceptionGroup or BaseExceptionGroup and re-raised.
    """
   
    ...
   
    def create_task(self, coro, *, name=None, context=None):
        """Schedule a coroutine and return a task representing it.
        
        :raises RuntimeError: if the task cannot be created.
        :returns: the newly created Task instance.
        """

[gvanrossum]

Could you turn that into a PR? I think it would be okay if it was a little shorter. And we don't use :raises or :returns: in the stdlib, really.

[SimpleArt]

I don't believe mentioning that it can raise a RuntimeError is very helpful for most users. If it should be added, then it should be added to the official documentation instead, which is where I would expect more thorough documentation to live. In contrast, I would prefer to keep doc-strings more concise. This makes it easier for it to fit in a pop-up window when hovering in an IDE and works more as a quick reminder of how something works when you're already familiar with it.

I would also suggest mentioning that the method matches asyncio.create_task, which is already how it's documented.

Something like this for instance:

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

[JosephSBoyle]

Hi @SimpleArt, good points - I've changed the docstring accordingly.

[gvanrossum]

No please make it into a PR.

…

On Sun, Mar 12, 2023 at 5:45 AM JosephSBoyle ***@***.***> wrote: Hi @SimpleArt <https://github.com/SimpleArt>, good points - I've changed the docstring accordingly. — Reply to this email directly, view it on GitHub <#102560 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAWCWMQ3KYLXAC777VI34WTW3XAPDANCNFSM6AAAAAAVVJQWV4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- --Guido van Rossum (python.org/~guido)

[AlexWaygood]

No please make it into a PR.
…
On Sun, Mar 12, 2023 at 5:45 AM JosephSBoyle @.> wrote: Hi @SimpleArt https://github.com/SimpleArt, good points - I've changed the docstring accordingly. — Reply to this email directly, view it on GitHub <#102560 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAWCWMQ3KYLXAC777VI34WTW3XAPDANCNFSM6AAAAAAVVJQWV4 . You are receiving this because you were mentioned.Message ID: @.>
-- --Guido van Rossum (python.org/~guido)

@gvanrossum, Joseph has already made a PR — #102565. It's linked to this issue :)

[AlexWaygood]

@gvanrossum, are you interested in backporting #102565, or can this be closed now?

[gvanrossum]

Oh, yes, let's backport to 3.11, where this was first introduced.

[gvanrossum]

Huh, where's the bot?

[hugovk]

The backport labels work on PRs, not issues.

I added it to #102565 and the bot backported it as #102715.

[gvanrossum]

Thanks! I suspect oncoming dementia.