From 2d95c3a7d8d8485d7bc2ee6db627564997816f37 Mon Sep 17 00:00:00 2001 From: "R. David Murray" Date: Thu, 4 Feb 2010 16:35:33 +0000 Subject: [PATCH] Merged revisions 77943,77959-77960 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r77943 | r.david.murray | 2010-02-03 08:36:23 -0500 (Wed, 03 Feb 2010) | 2 lines Explicitly mention the default value for formatdate's usegmt parameter. ........ r77959 | nick.coghlan | 2010-02-04 07:43:58 -0500 (Thu, 04 Feb 2010) | 1 line Issue 6760: Clarify args handling for subprocess.Popen. Patch by Chris Rebert ........ r77960 | r.david.murray | 2010-02-04 11:33:31 -0500 (Thu, 04 Feb 2010) | 2 lines Add Chris Rebert to ACKS for issue 6760 Popen doc improvements. ........ --- Doc/library/email.util.rst | 2 +- Doc/library/subprocess.rst | 37 +++++++++++++++++++++++++++++++------ Misc/ACKS | 1 + 3 files changed, 33 insertions(+), 7 deletions(-) diff --git a/Doc/library/email.util.rst b/Doc/library/email.util.rst index aa6788549fb..153ba78004c 100644 --- a/Doc/library/email.util.rst +++ b/Doc/library/email.util.rst @@ -102,7 +102,7 @@ There are several useful utilities provided in the :mod:`email.utils` module: Optional *usegmt* is a flag that when ``True``, outputs a date string with the timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is needed for some protocols (such as HTTP). This only applies when *localtime* is - ``False``. + ``False``. The default is ``False``. .. versionadded:: 2.4 diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index a7ef3ffd124..86bb1ea254f 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -48,13 +48,38 @@ This module defines one class called :class:`Popen`: On Unix, with *shell=False* (default): In this case, the Popen class uses :meth:`os.execvp` to execute the child program. *args* should normally be a - sequence. A string will be treated as a sequence with the string as the only - item (the program to execute). + sequence. If a string is specified for *args*, it will be used as the name + or path of the program to execute; this will only work if the program is + being given no arguments. - On Unix, with *shell=True*: If args is a string, it specifies the command string - to execute through the shell. If *args* is a sequence, the first item specifies - the command string, and any additional items will be treated as additional shell - arguments. + .. note:: + + :meth:`shlex.split` can be useful when determining the correct + tokenization for *args*, especially in complex cases:: + + >>> import shlex, subprocess + >>> command_line = raw_input() + /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'" + >>> args = shlex.split(command_line) + >>> print args + ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"] + >>> p = subprocess.Popen(args) # Success! + + Note in particular that options (such as *-input*) and arguments (such + as *eggs.txt*) that are separated by whitespace in the shell go in separate + list elements, while arguments that need quoting or backslash escaping when + used in the shell (such as filenames containing spaces or the *echo* command + shown above) are single list elements. + + On Unix, with *shell=True*: If args is a string, it specifies the command + string to execute through the shell. This means that the string must be + formatted exactly as it would be when typed at the shell prompt. This + includes, for example, quoting or backslash escaping filenames with spaces in + them. If *args* is a sequence, the first item specifies the command string, and + any additional items will be treated as additional arguments to the shell + itself. That is to say, *Popen* does the equivalent of:: + + Popen(['/bin/sh', '-c', args[0], args[1], ...]) On Windows: the :class:`Popen` class uses CreateProcess() to execute the child program, which operates on strings. If *args* is a sequence, it will be diff --git a/Misc/ACKS b/Misc/ACKS index 9239daa2be6..528281d3a5c 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -580,6 +580,7 @@ Burton Radons Antti Rasinen Eric Raymond Edward K. Ream +Chris Rebert Marc Recht John Redford Terry Reedy