asyncio.Queue.task_done documentation is ambiguous

[enok71]

Documentation

When reading https://docs.python.org/3/library/asyncio-queue.html the reader gets no clue to the fact that this object is (primarily) meant to contain tasks. (Because it is, isn't it? The task_done() method seems to indicate that)

Linked PRs

• gh-124433: fix docs for asyncio.Queue.task_done #128669
• [3.13] gh-124433: fix docs for asyncio.Queue.task_done (GH-128669) #128671
• [3.12] gh-124433: fix docs for asyncio.Queue.task_done (GH-128669) #128672

[ZeroIntensity]

No, an asyncio.Queue is just the asynchronous analogue of queue.Queue. It can hold any object, not just tasks. In this case, task_done is just badly named -- it's not really related to asyncio.Task, it's the equivalent of Queue.task_done.

I think this is a good indicator that the excerpt under asyncio.Queue.task_done should get reworded, the term "task" in the context of asyncio refers to a future, not a thread doing something to a queue.

[enok71]

In here it looks like the asyncio.queue is intended to be a "high-level API" to "distribute tasks"

[ZeroIntensity]

You can do that, but that isn't their sole purpose.

[JelleZijlstra]

"Task" here generally means "a thing to do", not "asyncio.Task".

[ZeroIntensity]

Yeah, that's why it's confusing in the context of asyncio.Queue

[enok71]

Wouldn't hurt to say something on the subject in the docs then.

[ZeroIntensity]

Would you like to author the PR? (If not, I can deal with it.)

[enok71]

Feel free. I don't know the subject well enough.