#10739: document that on Windows, socket.makefile() does not make a file that has a true file descriptor usable where such a thing is expected.

1 files changed, 14 insertions, 8 deletions

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index b90c0d8..0a0f764 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -634,18 +634,24 @@ correspond to Unix system calls applicable to sockets.
    is system-dependent (usually 5).
 
 
-.. method:: socket.makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)
+.. method:: socket.makefile(mode='r', buffering=None, *, encoding=None, \
+                            errors=None, newline=None)
 
    .. index:: single: I/O control; buffering
 
-   Return a :term:`file object` associated with the socket.  The exact
-   returned type depends on the arguments given to :meth:`makefile`.  These
-   arguments are interpreted the same way as by the built-in :func:`open`
-   function.
+   Return a :term:`file object` associated with the socket.  The exact returned
+   type depends on the arguments given to :meth:`makefile`.  These arguments are
+   interpreted the same way as by the built-in :func:`open` function.
 
-   Closing the file object won't close the socket unless there are no
-   remaining references to the socket.  The socket must be in blocking mode
-   (it can not have a timeout).
+   Closing the file object won't close the socket unless there are no remaining
+   references to the socket.  The socket must be in blocking mode (it can not
+   have a timeout).
+
+   .. note::
+
+      On Windows, the file-like object created by :meth:`makefile` cannot be
+      used where a file object with a file descriptor is expected, such as the
+      stream arguments of :meth:`subprocess.Popen`.
 
 
 .. method:: socket.recv(bufsize[, flags])