Skip to content

Add docstrings to asyncio.TaskGroup #102560

Closed

Description

@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

Activity

  1. AlexWaygood commented on Mar 9, 2023

    @AlexWaygood
    Member

    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 :)

  2. gvanrossum commented on Mar 9, 2023

    @gvanrossum
    Member

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

  3. changed the title [-]Add docstrings and type hinting to asyncio.TaskGroup[/-] [+]Add docstrings to asyncio.TaskGroup[/+] on Mar 9, 2023
  4. JosephSBoyle commented on Mar 9, 2023

    @JosephSBoyle
    ContributorAuthor

    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.
            """
  5. gvanrossum commented on Mar 9, 2023

    @gvanrossum
    Member

    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.

  6. SimpleArt commented on Mar 11, 2023

    @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().
            """
  7. JosephSBoyle commented on Mar 12, 2023

    @JosephSBoyle
    ContributorAuthor

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

  8. gvanrossum commented on Mar 12, 2023

    @gvanrossum
    Member
  9. AlexWaygood commented on Mar 12, 2023

    @AlexWaygood
    Member

    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 :)

  10. added a commit that references this issue on Mar 15, 2023
  11. AlexWaygood commented on Mar 15, 2023

    @AlexWaygood
    Member

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

  12. gvanrossum commented on Mar 15, 2023

    @gvanrossum
    Member

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

  13. gvanrossum commented on Mar 15, 2023

    @gvanrossum
    Member

    Huh, where's the bot?

  14. added a commit that references this issue on Mar 15, 2023
  15. hugovk commented on Mar 15, 2023

    @hugovk
    Member

    The backport labels work on PRs, not issues.

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

  16. added a commit that references this issue on Mar 15, 2023
  17. moved this from Todo to Done in asyncioon Mar 15, 2023
  18. gvanrossum commented on Mar 15, 2023

    @gvanrossum
    Member

    Thanks! I suspect oncoming dementia.

  19. added a commit that references this issue on Mar 27, 2023
  20. added a commit that references this issue on Apr 11, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    3.11only security fixes3.12only security fixestopic-asynciotype-featureA feature request or enhancement

    Projects

    • Status
      Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions