[docs] [issue34476] asyncio.sleep(0) not documented

[Hrvoje Nikšić]

Hrvoje Nikšić <hniksic at gmail.com> added the comment:

The issue is because the current documentation *doesn't* say that "`asyncio.sleep()` always pauses the current task and switches execution to another one", it just says that it "blocks for _delay_ seconds".

With that description a perfectly valid implementation could be further optimized with:

    async def sleep(delay):
        if delay <= 0:
            return
        ...

In which case `await sleep(0)` would *not* cause a task switch. And this is not an unreasonable thing to expect because there are many other potentially-switching situations in asyncio that sometimes don't cause a switch, such as await `queue.get()` from a non-empty queue or await `await stream.readline()` from a socket stream that has a line to provide.

The user who wants to implement a "yield control to event loop" has to look at the source to find out how delay==0 is handled, and then they have to wonder if it's an implementation detail. https://github.com/python/asyncio/issues/284 states that the behavior is explicit and here to stay, but that promise has never made it into the actual documentation.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue34476>
_______________________________________