[3.14] gh-75279: Document that asyncio StreamWriter.drain() may not yield to the event loop (GH-155132) (#155135)

https://github.com/python/cpython/commit/f5af792f3accfed54e7693f550cecb5267c6f485
commit: f5af792f3accfed54e7693f550cecb5267c6f485
branch: 3.14
author: Miss Islington (bot) <[email protected]>
committer: kumaraditya303 <[email protected]>
date: 2026-08-04T11:56:48+05:30
summary:

[3.14] gh-75279: Document that asyncio StreamWriter.drain() may not yield to the event loop (GH-155132) (#155135)

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 <[email protected]>

files:
M Doc/library/asyncio-stream.rst

diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 05445219510ca5..dd23b223e1492e 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:

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]