The asyncio documentation is missing a landing page

[jedreky]

Documentation

Hi, I have just spent about 2 days figuring out how to use asyncio in my project. I realised that the asyncio documentation is missing a landing page where a developer who's not familiar with async programming can get some basic understanding of the library and more importantly can find out which tools will be appropriate for their specific situation.

For instance in my situation the main problem was that I wanted an event loop to which I can dynamically on-the-fly add new tasks. This seems pretty standard, but nevertheless it took some browsing and I finally I found an answer here: https://stackoverflow.com/questions/34499400/how-to-add-a-coroutine-to-a-running-asyncio-loop. I think an example like this should be somewhere in the official documentation.

Also, my process is started by the multiprocessing module, so I couldn't just use asyncio.run() (I think), I had to dig a bit deeper. The explanation of how to deal with the event loop is not always that detailed.

Anyway, I think this is a great library and it would be great to get more people to use it. I would be happy to contribute to the docs, but I would need support from someone who's an active developer of asyncio.

Linked PRs

• gh-124668: Update asyncio doc landing page with examples #125594

[AA-Turner]

cc @kumaraditya303 @graingert

[kumaraditya303]

I agree, the docs does need improvement of asyncio overall, PR welcome!

[xuantengh]

Hi, I'm wondering if I can assgin this to myself? Currently I think we should put the mostly used APIs in the landing page (https://docs.python.org/3/library/asyncio.html), including run, create_task, TaskGroup and the event loop. Besides, I think the asyncio REPL is not an key point needs to be put in the landing page.

Looking forward to your feedback.

[graingert]

Hi, I'm wondering if I can assgin this to myself? Currently I think we should put the mostly used APIs in the landing page (https://docs.python.org/3/library/asyncio.html), including run, create_task, TaskGroup and the event loop. Besides, I think the asyncio REPL is not an key point needs to be put in the landing page.

Looking forward to your feedback.

I don't think asyncio.create_task should be documented on the landing page as it's very difficult to use correctly and so we should stear most users away from it. Instead the landing page should document creating tasks with TaskGroup only

[xuantengh]

I don't think asyncio.create_task should be documented on the landing page as it's very difficult to use correctly and so we should stear most users away from it. Instead the landing page should document creating tasks with TaskGroup only

Sure, I can create a PR later.

[willingc]

Hi folks,

The structure of the current asyncio landing page includes the following contents:

• High level API (end users)
• Low level API (targeted at library maintainers)
• Guides and Tutorials

Examples of how to use asyncio would be best placed under the "Guides and Tutorials" section. Thanks!
cc/ @1st1

[willingc]

Thanks @jedreky for the feedback and @xuantengh for creating a PR.

#79012 covers a broader need for more tutorial content. I recommend that we move the discussion to this duplicate issue, and close this issue.