I don't have much experience with what should and shouldn't be in the python docs, however I was recently bitten by a subtlety in signal/subprocess that might be worth documenting.

Anything written to stdout in a signal handler could end up in the stdout of a process returned by Popen, if stdout gets flushed in the signal handler during a critical part of the Popen call. Furthermore, any output buffered before calling Popen could also be flushed by the signal handler, showing up in the child process's stdout. The same goes for stderr.

On 2.7.7 at least, the window where this can happen is between lines 1268-1290 in subprocess.py, where the child process has duplicated stdout, but hasn't yet called execvp.

This is a result of signal inheritance that caught me off guard, and wasn't clear to me by reading the documentation.