classification
Title: subprocess.run documentation does not have **kwargs
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, docs@python, oprypin, xdegaye
Priority: normal Keywords: easy

Created on 2017-12-20 20:47 by oprypin, last changed 2018-05-16 21:09 by xdegaye.

Messages (5)
msg308810 - (view) Author: Oleh Prypin (oprypin) Date: 2017-12-20 20:47
I was just looking at documentation of https://docs.python.org/3.6/library/subprocess.html#subprocess.run
and thought that it doesn't support passing `env` because the list of supported keyword arguments is exhaustive (no **kwargs). But it does support passing **kwargs to Popen, so that should be specified in the docs.
msg308823 - (view) Author: Xavier de Gaye (xdegaye) * Date: 2017-12-20 21:26
But the documentation does say "The arguments shown above are merely the most common ones...The full function signature is largely the same as that of the Popen constructor...", no ?
msg308824 - (view) Author: Oleh Prypin (oprypin) Date: 2017-12-20 21:28
Yes, but the most prominent thing to indicate that is **kwargs in the actual function signature. And, as far as I'm concerned, lack of **kwargs means the function signature is exhaustive and there's no point in looking for fine print somewhere in the middle of the textual description.
msg316776 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-05-16 07:53
I agree with Xavier's comment, but I've bitten by this before so I think it would be better if we add more common arguments to the subprocess.run() signature.

Adding **kwargs wouldn't be entirely correct since subprocess.run() doesn't pass all its arguments to subprocess.Popen().

Let's add 'env=None' to the signature of subprocess.run():

.. function:: run(args, *, stdin=None, input=None, stdout=None, stderr=None,\
                  shell=False, cwd=None, timeout=None, check=False, \
                  encoding=None, errors=None, text=None)

https://github.com/python/cpython/blob/3055c947f98a078bd10d6a8cc352048a1b771d60/Doc/library/subprocess.rst#using-the-modsubprocess-module
msg316869 - (view) Author: Xavier de Gaye (xdegaye) * Date: 2018-05-16 21:09
> Let's add 'env=None' to the signature of subprocess.run():

+1
History
Date User Action Args
2018-05-16 21:09:04xdegayesetmessages: + msg316869
2018-05-16 07:53:58berker.peksagsettype: enhancement
versions: + Python 3.6, Python 3.8
keywords: + easy
nosy: + berker.peksag

messages: + msg316776
stage: needs patch
2017-12-20 21:28:14oprypinsetmessages: + msg308824
2017-12-20 21:26:36xdegayesetnosy: + xdegaye
messages: + msg308823
2017-12-20 20:47:11oprypincreate