classification
Title: Clarify kwarg handing for subprocess convenience APIs
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, docs@python, martin.panter, ncoghlan
Priority: normal Keywords:

Created on 2017-05-21 03:29 by ncoghlan, last changed 2017-06-20 03:28 by Mariatta.

Pull Requests
URL Status Linked Edit
PR 1685 merged alex, 2017-05-21 03:32
PR 2253 merged Mariatta, 2017-06-17 01:33
Messages (6)
msg294070 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-05-21 03:29
As per the discussion in https://github.com/python/cpython/pull/1685, the current nominal signatures of the convenience APIs in subprocess is confusing, as they don't make it clear that all Popen keyword arguments are supported, with only the most common ones being listed in the signature.

Proposed fixes:

* add `cwd` to the list of frequently used arguments, and list it in the nominal signatures for `run()`, `call()`, `check_call()`, and `check_output()`
* append `**popenargs` to the nominal signatures of `run()`, `call()`, and `check_call()`
* append `**runargs` to the nominal signature of `check_output()`
* amend the prose descriptions for these functions accordingly

Background:

The status quo is that while this behaviour is documented, it's documented solely as text in the bodies of the API definitions, using paragraphs like the following:

`run()`: """The arguments shown above are merely the most common ones, described below in Frequently Used Arguments (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the Popen constructor - apart from timeout, input and check, all the arguments to this function are passed through to that interface."""

`call()`, `check_call()`: """The arguments shown above are merely the most common ones. The full function signature is largely the same as that of the Popen constructor - this function passes all supplied arguments other than timeout directly through to that interface."""

`check_output()`: """The arguments shown above are merely the most common ones. The full function signature is largely the same as that of run() - most arguments are passed directly through to that interface."""

While it's technically anecdotal, we still have pretty decent evidence that this isn't adequate as:

- I worked on the original patch splitting out the "Frequently Used Arguments" section, and initially missed not only that the run() docs had retained that paragraph, but also missed the revised paragraphs in the relocated docs for the older API
- as mentioned in the linked PR, Paul Kehrer had missed that `check_call()` and `check_output()` both supported the Popen `cwd` parameter

The working theory behind adding the appropriately named `**kwargs` parameters to the end of the nominal signatures is that it will give readers a clearer indication that we're *not* explicitly listing all the parameters, and a hint as to which API to go look at to find out more about the unlisted ones.
msg294073 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-05-21 05:31
For the curious, Nick added the “frequently used arguments” in Issue 13237. Before that the signatures were like <https://docs.python.org/release/3.2.2/library/subprocess.html#convenience-functions>:

subprocess.call(*popenargs, **kwargs)
msg294075 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-05-21 06:06
If you add “cwd” to Frequently Use Arguments, please try to keep the details in one place. Otherwise you encourage a fix for Issue 15533 (cwd platform specifics) to repeat the problem of Issue 20344 (args vs shell platform specifics), where some details are only found in one section and contradict the other section.
msg294523 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-05-26 02:28
New changeset 368cf1d20630498ca7939069a05d744fabb570aa by Nick Coghlan (Alex Gaynor) in branch 'master':
bpo-30420: List cwd parameter in subprocess convenience APIs (GH-1685)
https://github.com/python/cpython/commit/368cf1d20630498ca7939069a05d744fabb570aa
msg294526 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-05-26 02:34
The just merged PR covers the "list `cwd` in the nominal signatures for `run()`, `call()`, `check_call()`, and `check_output()`" part of the proposal.

The rest of the proposed fixes are still pending a patch (and keeping in mind Martin's caveat on minimising duplication between the "Frequently Used Arguments" section and the full Popen documentation)
msg296396 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-06-20 03:28
New changeset 0a4fe1d8578fa59004518f8deef137282be4d71a by Mariatta in branch '3.6':
[3.6] bpo-30420: List cwd parameter in subprocess convenience APIs (GH-1685) (GH-2253)
https://github.com/python/cpython/commit/0a4fe1d8578fa59004518f8deef137282be4d71a
History
Date User Action Args
2017-06-20 03:28:19Mariattasetnosy: + Mariatta
messages: + msg296396
2017-06-17 01:33:03Mariattasetpull_requests: + pull_request2303
2017-05-26 02:34:02ncoghlansetmessages: + msg294526
2017-05-26 02:28:20ncoghlansetmessages: + msg294523
2017-05-21 06:06:37martin.pantersetmessages: + msg294075
2017-05-21 05:31:04martin.pantersetnosy: + martin.panter
messages: + msg294073
2017-05-21 03:32:37alexsetpull_requests: + pull_request1781
2017-05-21 03:29:11ncoghlancreate