Documentation

Please add the following text (or some equivalent) to the documentation of asyncio.Queue:

The construct asyncio.wait_for(queue.get(), timeout) is guaranteed to be free of race conditions. It will not lose queue items.

Explanation: According to the public documentation, this construct is allowed to lose queue items: The documentation states that wait_for uses cancellation which is implemented by raising a CancelledError exception. Depending on the implementation, this may happen in the call queue.get() after an item has been removed from the queue. This would cause the extracted queue item to be lost.

According to the current documentation, this race condition is allowed: Such a race condition would be surprising for most programmers --- but it would not violate the letter of the documentation. Hence, judging only the documented features, a responsible programmer will hesitate to use this construct in production settings where losing queue items is not acceptable.

This issue has been reported and addressed at least twice:

• wait()/wait_for() losing items on Queue.get() asyncio#201
• asyncio.Queue.put_nowait(), followed get() task cancellation leads to item being lost #68000

Based on the comments in these two bug reports it seems to me that the current implementation avoids this race condition. However, this is not clearly spelled out as a commitment for future versions.

Conclusion
At the current state of affairs, a responsible programmer will find no assurance in the documentation of whether the construct asyncio.wait_for(queue.get(), timeout) can safely be used in production environments. He will need to spend much time (I spend more than two hours) to search for bug reports such as listed above and still be left with doubts about whether he can safely use the simple construct or still needs to implement a safe queue-with-timeout-in-get.

If the python implementation promises to avoid this race condition --- please state it clearly in the documentation.