[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Alex Waygood]

Alex Waygood  added the comment:

The modern docs for these functions seem to:

* Document the cwd argument for these functions, following PR 1685 & PR 2253.
* Include an **other_popen_kwargs parameter for all these functions.

Nick, is there anything left to do here, or can this issue be closed now?

--
nosy: +AlexWaygood

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Mariatta Wijaya]

Mariatta Wijaya added the comment:


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


--
nosy: +Mariatta

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Mariatta Wijaya]

Changes by Mariatta Wijaya :


--
pull_requests: +2303

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Nick Coghlan]

Nick Coghlan added the comment:

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)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Nick Coghlan]

Nick Coghlan added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Martin Panter]

Martin Panter added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Martin Panter]

Martin Panter added the comment:

For the curious, Nick added the “frequently used arguments” in Issue 13237. 
Before that the signatures were like 
:

subprocess.call(*popenargs, **kwargs)

--
nosy: +martin.panter

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Alex Gaynor]

Changes by Alex Gaynor :


--
pull_requests: +1781

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue30420] Clarify kwarg handing for subprocess convenience APIs

[Nick Coghlan]

New submission from Nick Coghlan:

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.

--
assignee: docs@python
components: Documentation
messages: 294070
nosy: docs@python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Clarify kwarg handing for subprocess convenience APIs
type: enhancement
versions: Python 3.5, Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com