Fix docs for Queue.shutdown

[rhettinger]

Fix errors. Clarify ambiguities. Improve presentation. Add cautionary note.

• Removed incorrect note in the task_done docs. That method is not called by shutdown.
• Separate the discussions of the normal case (the default) and the immediate case.
• For the normal case, note that blocked callers of put will be unblocked but will also immediately raise 'ShutDown' in the formerly blocked thread.
• For the normal case, note that get and task_done continue to operate normally except that a get on an empty queue will now raise ShutDown instead of Empty.
• For the immediate case, present the actions in the order that they actually occur (drain the queue, reduce the unfinished tasks by the number drained, notify Queue.join waiters, notify get and put waiters.
• For the immediate case, note that unfinished tasks is updated without calling task_done.
• For the immediate case, note the Queue.join is unblocked even if the unfinished tasks are more than zero.
• Add cautionary note about using Queue.join with immediate=True.

---

📚 Documentation preview 📚: https://cpython-previews--137028.org.readthedocs.build/

[serhiy-storchaka]

Please update also the asyncio.queue documentation and the docstrings.

[rhettinger]

Please update also the asyncio.queue documentation and the docstrings.

I don't feel comfortable editing those docs (I don't use asyncio anymore). Someone else who knows the territory better can model an edit on this one.

[serhiy-storchaka]

It is mostly just a copy of the queue.Queue documentation. It would be better to keep them in sync.

At least update the docstrings.

[rhettinger]

Okay, I updated the asyncio docs to match. You were right, they were almost identical.

[serhiy-storchaka]

Please update also the task_done docstrings, for both classes.

[serhiy-storchaka]

LGTM. 👍

[kumaraditya303]

Suggested change

	and will raise :exc:`QueueShutDown` in the formerly blocked thread.
	and will raise :exc:`QueueShutDown` in the formerly blocked tasks.

asyncio queues are not thread safe, they can only be used with tasks.

[miss-islington-app]

Thanks @rhettinger for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-137080 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-137081 is a backport of this pull request to the 3.13 branch.