classification
Title: mention of list2cmdline() in docs of subprocess.Popen
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 3.1, Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, eric.araujo, ezio.melotti, python-dev, r.david.murray, rosslagerwall
Priority: normal Keywords: patch

Created on 2011-04-11 08:38 by eli.bendersky, last changed 2011-07-29 13:54 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
issue11827.1.patch eli.bendersky, 2011-04-12 20:18
Messages (13)
msg133507 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-04-11 08:38
The documentation of subprocess.Popen mentions a function named list2cmdline():

----
  On Windows: the Popen class uses CreateProcess() to execute the child program, which operates on strings. If args is a sequence, it will be converted to a string using the list2cmdline() method. Please note that not all MS Windows applications interpret the command line the same way: list2cmdline() is designed for applications using the same rules as the MS C runtime.
----

I find this rather opaque and useless. list2cmdline() in subprocess is publicly accessible (doesn't begin with underscores) but it isn't documented.

The solution can be one of the following:

1. Document list2cmdline in the docs of subprocess, making the reference to is useful
2. Don't mention list2cmdline and instead mention what it does with the command-line list
msg133510 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-04-11 10:31
I vote for (2) (I presume 'it' in that sentence is 'subprocess').  list2cmdline shouldn't be a "real" public method, at least not without the issues surrounding being given careful design attention.
msg133511 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-04-11 10:37
I also prefer (2) since I see no reason for the user to use list2cmdline() directly, let alone from subprocess (had there been rationale for such a public function it should probably be in another module).

As for 'it', I guess you can say it means 'subprocess' or 'list2cmdline', doesn't matter which.
msg133514 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-04-11 12:21
Ah, right.  I guess I was advocating that the docs be written from the perspective that list2cmdline doesn't exist as an identifiable entity.  From the POV of the updated docs, it is just subprocess's behavior, and list2cmdline is an implementation detail.  Which is what you were saying.
msg133563 - (view) Author: Ross Lagerwall (rosslagerwall) (Python committer) Date: 2011-04-12 04:27
#10838 has a bit of discussion about list2cmdline and being part of the public api (generally agreeing that it should be made private, I think).
msg133566 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-04-12 05:50
Thanks for the pointer, Ross. 

So I propose to remove the mention of list2cmdline from the documentation of subprocess, explaining instead what it does to the path (since I think this should be publicly known, otherwise it's just black magic). 

I will prepare a patch for this and post it for review here before committing.

Do you folks think we should also prepend an underscore to list2cmdline, thus settling the doubt about its "public-ness" once and for all? Other private functions in subprocess do have underscores prepended.
msg133568 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-04-12 06:26
If a _ is added to list2cmdline the old name should be kept and deprecated.
The function is also on 2.x and it's not deprecated there (and it's probably too late to deprecate it now), so we might have to wait a few versions before it will be possible to remove list2cmdline from 3.x.
msg133599 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-04-12 20:18
Attaching a proposed patch for 3.2, focusing only on the documentation for the time being (I realize that deprecation is a loaded issue and should be probably handled in a centralized manner).

The patch removes mention of list2cmdline, instead explaining its intention (using the docstring of list2cmdline quite literally). I realize this isn't an ideal approach, but IMHO it's much better than what we have now. Suggestions are most welcome.
msg133673 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-04-13 15:42
LGTM.
msg133780 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-04-15 04:29
New changeset e7a55e236b8b by Eli Bendersky in branch '3.1':
Issue #11827: remove mention of list2cmdline in the doc of subprocess
http://hg.python.org/cpython/rev/e7a55e236b8b
msg133782 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-04-15 04:35
New changeset f38489a3394f by Eli Bendersky in branch '2.7':
Issue #11827: remove mention of list2cmdline in the doc of subprocess
http://hg.python.org/cpython/rev/f38489a3394f
msg133783 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-04-15 04:38
Patch committed to 3.3, 3.2, 3.1, 2.7

In case no objections arise, I will close this issue in a couple of days
msg141382 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-29 13:54
The module docstring (which duplicates the reST docs) still mentions list2cmdline.  I’d vote for removal there too.
History
Date User Action Args
2011-07-29 13:54:53eric.araujosetmessages: + msg141382
2011-04-30 05:56:06eli.benderskysetstatus: open -> closed
2011-04-15 04:38:14eli.benderskysetstatus: pending -> open

messages: + msg133783
2011-04-15 04:36:54eli.benderskysetstatus: open -> pending
2011-04-15 04:35:03python-devsetmessages: + msg133782
2011-04-15 04:29:41python-devsetnosy: + python-dev
messages: + msg133780
2011-04-13 15:42:17eric.araujosetmessages: + msg133673
versions: + Python 3.1, Python 2.7, Python 3.3
2011-04-12 20:18:52eli.benderskysetfiles: + issue11827.1.patch
keywords: + patch
messages: + msg133599
2011-04-12 15:54:15eric.araujosetnosy: + eric.araujo
2011-04-12 06:26:53ezio.melottisetnosy: + ezio.melotti
messages: + msg133568
2011-04-12 05:50:30eli.benderskysetmessages: + msg133566
2011-04-12 04:27:58rosslagerwallsetnosy: + rosslagerwall
messages: + msg133563
2011-04-11 12:21:01r.david.murraysetmessages: + msg133514
2011-04-11 10:37:51eli.benderskysetmessages: + msg133511
2011-04-11 10:31:11r.david.murraysetnosy: + r.david.murray
messages: + msg133510
2011-04-11 08:38:15eli.benderskycreate