[Python-checkins] r77963 - in python/branches/release31-maint: Doc/library/email.util.rst Doc/library/subprocess.rst Misc/ACKS

[r.david.murray]

Author: r.david.murray
Date: Thu Feb  4 17:44:31 2010
New Revision: 77963

Log:
Merged revisions 77962 via svnmerge from 
svn+ssh://pythondev@svn.python.org/python/branches/py3k

................
  r77962 | r.david.murray | 2010-02-04 11:41:57 -0500 (Thu, 04 Feb 2010) | 17 lines
  
  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.
  ........
................


Modified:
   python/branches/release31-maint/   (props changed)
   python/branches/release31-maint/Doc/library/email.util.rst
   python/branches/release31-maint/Doc/library/subprocess.rst
   python/branches/release31-maint/Misc/ACKS

Modified: python/branches/release31-maint/Doc/library/email.util.rst
==============================================================================
--- python/branches/release31-maint/Doc/library/email.util.rst	(original)
+++ python/branches/release31-maint/Doc/library/email.util.rst	Thu Feb  4 17:44:31 2010
@@ -102,7 +102,7 @@
    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)

Modified: python/branches/release31-maint/Doc/library/subprocess.rst
==============================================================================
--- python/branches/release31-maint/Doc/library/subprocess.rst	(original)
+++ python/branches/release31-maint/Doc/library/subprocess.rst	Thu Feb  4 17:44:31 2010
@@ -42,13 +42,38 @@
 
    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

Modified: python/branches/release31-maint/Misc/ACKS
==============================================================================
--- python/branches/release31-maint/Misc/ACKS	(original)
+++ python/branches/release31-maint/Misc/ACKS	Thu Feb  4 17:44:31 2010
@@ -603,6 +603,7 @@
 Antti Rasinen
 Eric Raymond
 Edward K. Ream
+Chris Rebert
 Marc Recht
 John Redford
 Terry Reedy