From 5973e4d0a3a4afd70694de76ea871c32f863c9e8 Mon Sep 17 00:00:00 2001 From: "R. David Murray" Date: Thu, 4 Feb 2010 16:41:57 +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 b02f4cd9113..a1ce3017f42 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``. .. function:: make_msgid(idstring=None) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 93c1ed0c1d8..5680b389cb1 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -42,13 +42,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 b991960738f..f349b1e3d1a 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -616,6 +616,7 @@ Brodie Rao Antti Rasinen Eric Raymond Edward K. Ream +Chris Rebert Marc Recht John Redford Terry Reedy