From f4630db87ca3b5e0973d8aa979ed507bc04de57b Mon Sep 17 00:00:00 2001 From: Kumar Aditya Date: Mon, 3 Aug 2026 23:37:01 +0530 Subject: [PATCH] gh-75279: Document that asyncio StreamWriter.drain() may not yield to the event loop (GH-155132) (cherry picked from commit ab8c7372fdf9997ed5562a7506bd34af9e17f8c5) Co-authored-by: Kumar Aditya --- Doc/library/asyncio-stream.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 05445219510ca54..dd23b223e1492e4 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -382,6 +382,16 @@ StreamWriter be resumed. When there is nothing to wait for, the :meth:`drain` returns immediately. + .. note:: + + When the write buffer is below the high watermark, + :meth:`drain` returns immediately without yielding to + the event loop. As a result, code which repeatedly calls + ``write()`` followed by ``await drain()`` may prevent other + tasks from running. To prevent blocking behavior, yield + to the event loop explicitly with ``await asyncio.sleep(0)`` + (see :func:`asyncio.sleep`). + .. method:: start_tls(sslcontext, *, server_hostname=None, \ ssl_handshake_timeout=None, ssl_shutdown_timeout=None) :async: