subprocess.run parameters not fully documented

[CitrusWire]

https://docs.python.org/3/library/subprocess.html#subprocess.run

So I want to capture STDERR, but it doesn't actually say how to do that anywhere that I can see. Note that I don't want to capture STDOUT.

My IDE is telling me that stderr accepts None and Int types. What are the int values? I'm guessing a PIPE:

subprocess.PIPE
Special value that can be used as the stdin, stdout or stderr argument to Popen and indicates that a pipe to the standard stream should be opened.

Now the user also needs to understand the inner workings of Popen? Why on earth does a user need to join so many dots just to use an arguement? Is not explicit is better than implicit part of the python ethos?

I'm sorry to be blunt, but none of this is well documented. There should be a comprehensive, itemised list of all parameters. Each one should explicitly list what they do and what their possible values are. As it is, it's a confused mess of "if x, then y in module q, but not z in module p".

[JamesParrott]

Call it with capture_output=True and read .stderr on the returned CompletedProcess.

[vadmium]

The documentation for run used to say “To [capture output], pass PIPE for the stdout and/or stderr arguments”, but this was removed when the capture_output mode was added for Python 3.7 in commit ce0f33d.

[CitrusWire]

Thanks for the suggestsions.

• capture_output=True - captures stdout too. What if a user only wants stderr?

• stderr=subprocess.PIPE - puts it into CalledProcessError.stderr at least, so the docs have regressed with the removal of this.

• stderr=subprocess.STDOUT - prints stderr to screen as stdout, but doesn't catch it anywhere that I can see, despite what https://stackoverflow.com/a/16198668 says, which suggests behaviour has changed.

[JamesParrott]

capture_output=True - captures stdout too. What if a user only wants stderr?

They may simply ignore .stdout on the returned CompletedProcess.

[CitrusWire]

capture_output=True - captures stdout too. What if a user only wants stderr?

They may simply ignore .stdout on the returned CompletedProcess.

Sure, except then you're potentially capturing GB of stdout into cache just to throw it away.

[JamesParrott]

That's possible with the Popen back end. Pass stderr=PIPE only, and call https://docs.python.org/3/library/subprocess.html#subprocess.Popen.communicate

If this issue is still about further improvements to the subprocess documentation, then fair enough you've convinced me! It is a beast, and I remember back when I first used subprocess, much of it felt like Deep Magic.

Rather than messing around with it, as someone's put a lot of careful thought into it, I think it would be a really valuable project for someone, to write a logging/enum/re style Tutorial/Cookbook/HOWTO . I found these for all 3 modules incredibly helpful.