Heh.  Maybe what we ought to do is drop the shell argument and make everyone build their own shell invocations :)

Actually, an API refactor where a shell call looks like this might be kind of cool:

  Popen(shell_cmd('echo magic'))

where shell would return a list.

As for the ValueError, yeah, it's vague, but I think that the only information that sentence is trying to convey is that ValueError is one of the exceptions you might get when calling Popen.  Exactly what you get it for is pretty much an implementation detail.  If someone wants to grovel through the code and figure out all the things that can raise ValueError, we could see if there's any sensible way to turn that into a sentence, but it might not be easy.  Short of that, perhaps we could  drop the existing qualifier and just say "Popen may also raise ValueError."