You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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 :)
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.
classTaskGroup:
"""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. """
...
defcreate_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. """
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:
defcreate_task(self, coro, *, name=None, context=None):
"""Create a task in this task group and return it. This method matches asyncio.create_task(). """
Activity
AlexWaygood commentedon Mar 9, 2023
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.TaskGroupover 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 commentedon Mar 9, 2023
That leaves docstrings. @JosephSBoyle do you want to contribute?
[-]Add docstrings and type hinting to asyncio.TaskGroup[/-][+]Add docstrings to asyncio.TaskGroup[/+]JosephSBoyle commentedon Mar 9, 2023
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.
gvanrossum commentedon Mar 9, 2023
Could you turn that into a PR? I think it would be okay if it was a little shorter. And we don't use
:raisesor:returns:in the stdlib, really.SimpleArt commentedon Mar 11, 2023
I don't believe mentioning that it can raise a
RuntimeErroris 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:
JosephSBoyle commentedon Mar 12, 2023
Hi @SimpleArt, good points - I've changed the docstring accordingly.
gvanrossum commentedon Mar 12, 2023
AlexWaygood commentedon Mar 12, 2023
@gvanrossum, Joseph has already made a PR — #102565. It's linked to this issue :)
gh-102560 Add docstrings to asyncio.TaskGroup (#102565)
AlexWaygood commentedon Mar 15, 2023
@gvanrossum, are you interested in backporting #102565, or can this be closed now?
gvanrossum commentedon Mar 15, 2023
Oh, yes, let's backport to 3.11, where this was first introduced.
gvanrossum commentedon Mar 15, 2023
Huh, where's the bot?
pythongh-102560 Add docstrings to asyncio.TaskGroup (pythonGH-102565)
hugovk commentedon Mar 15, 2023
The backport labels work on PRs, not issues.
I added it to #102565 and the bot backported it as #102715.
gh-102560 Add docstrings to asyncio.TaskGroup (GH-102565)
gvanrossum commentedon Mar 15, 2023
Thanks! I suspect oncoming dementia.
pythongh-102560 Add docstrings to asyncio.TaskGroup (python#102565)
pythongh-102560 Add docstrings to asyncio.TaskGroup (python#102565)