issue1606: Add warnings to the subprocess documentation about common pitfalls

of using pipes that cause deadlocks.

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 5ae6eb03f01f8724608a4bf9faf6d56968e10fb3..3458003fe582d4a48dbaee209b6ce1a07cf6406b 100644 (file)
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -193,6 +193,10 @@ Instances of the :class:`Popen` class have the following methods:
    Wait for child process to terminate.  Set and return :attr:`returncode`
    attribute.
 
+   warning:: This will deadlock if the child process generates enough output
+   to a stdout or stderr pipe causing it to block waiting for the OS's pipe
+   buffer to accept more data.
+
 
 .. method:: Popen.communicate(input=None)
 
@@ -250,18 +254,30 @@ The following attributes are also available:
    If the *stdin* argument is ``PIPE``, this attribute is a file object that
    provides input to the child process.  Otherwise, it is ``None``.
 
+   warning:: Use :meth:`communicate` rather than .stdin.write() to avoid
+   deadlocks due to any of the other pipe buffers filling up and blocking the
+   child process.
+
 
 .. attribute:: Popen.stdout
 
    If the *stdout* argument is ``PIPE``, this attribute is a file object that
    provides output from the child process.  Otherwise, it is ``None``.
 
+   warning:: Use :meth:`communicate` rather than .stdout.read() to avoid
+   deadlocks due to any of the other pipe buffers filling up and blocking the
+   child process.
+
 
 .. attribute:: Popen.stderr
 
    If the *stderr* argument is ``PIPE``, this attribute is file object that
    provides error output from the child process.  Otherwise, it is ``None``.
 
+   warning:: Use :meth:`communicate` rather than .stderr.read() to avoid
+   deadlocks due to any of the other pipe buffers filling up and blocking the
+   child process.
+
 
 .. attribute:: Popen.pid