Docs: asyncio.loop.subprocess_exec documentation is confusing, it's not clear how to inherit stdin, stdout or stderr in the subprocess

[sbstp]

BPO	36686
Nosy	@asvetlov, @1st1, @sbstp, @miss-islington
PRs	bpo-36686: Improve the documentation of the std* params in loop.subprocess_exec #13586

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-05-28.00:22:48.604>
created_at = <Date 2019-04-21.01:04:45.598>
labels = ['3.8', 'expert-asyncio']
title = "Docs: asyncio.loop.subprocess_exec documentation is confusing, it's not clear how to inherit stdin, stdout or stderr in the subprocess"
updated_at = <Date 2019-05-28.13:06:47.124>
user = 'https://github.com/sbstp'

bugs.python.org fields:

activity = <Date 2019-05-28.13:06:47.124>
actor = 'asvetlov'
assignee = 'none'
closed = True
closed_date = <Date 2019-05-28.00:22:48.604>
closer = 'sbstp'
components = ['asyncio']
creation = <Date 2019-04-21.01:04:45.598>
creator = 'sbstp'
dependencies = []
files = []
hgrepos = []
issue_num = 36686
keywords = ['patch']
message_count = 4.0
messages = ['340593', '340594', '343542', '343713']
nosy_count = 4.0
nosy_names = ['asvetlov', 'yselivanov', 'sbstp', 'miss-islington']
pr_nums = ['13586']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue36686'
versions = ['Python 3.8']

[sbstp]

I had trouble figuring out how to simply inherit stdin, stdout, or stderr in the asyncio.create_subprocess_exec / asyncio.subprocess_exec docs. My experiments show that passing either None or sys.std* works but the way the docs are written make it hard to figure that out in my opinion.

stdout: either a file-like object representing the pipe to be connected to the subprocess’s standard output stream using connect_read_pipe(), or the subprocess.PIPE constant (default). By default a new pipe will be created and connected.

I would add a mention that using None makes the subprocess inherit the file descriptor.

[sbstp]

Could be cool to also mention that encoding / errors does not work yet. https://bugs.python.org/issue31087

[asvetlov]

Pull Request is welcome!

[miss-islington]

New changeset f0d4c64 by Miss Islington (bot) (sbstp) in branch 'master':
bpo-36686: Improve the documentation of the std* params in loop.subprocess_exec (GH-13586)
f0d4c64