[Python-checkins] cpython (3.1): Issue #11827: remove mention of list2cmdline in the doc of subprocess

[eli.bendersky]

http://hg.python.org/cpython/rev/e7a55e236b8b
changeset:   69351:e7a55e236b8b
branch:      3.1
parent:      69348:de0da2759c8c
user:        Eli Bendersky <eliben at gmail.com>
date:        Fri Apr 15 07:23:26 2011 +0300
summary:
  Issue #11827: remove mention of list2cmdline in the doc of subprocess

files:
  Doc/library/subprocess.rst |  43 ++++++++++++++++++++++---
  1 files changed, 37 insertions(+), 6 deletions(-)


diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -93,12 +93,10 @@
       *shell=False* does not suffer from this vulnerability; the above Note may be
       helpful in getting code using *shell=False* to work.
 
-   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
-   converted to a string using the :meth:`list2cmdline` method.  Please note that
-   not all MS Windows applications interpret the command line the same way:
-   :meth:`list2cmdline` is designed for applications using the same rules as the MS
-   C runtime.
+   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 converted to a string in a manner described in
+   :ref:`converting-argument-sequence`.
 
    *bufsize*, if given, has the same meaning as the corresponding argument to the
    built-in open() function: :const:`0` means unbuffered, :const:`1` means line
@@ -609,3 +607,36 @@
 
 * popen2 closes all file descriptors by default, but you have to specify
   ``close_fds=True`` with :class:`Popen`.
+
+Notes
+-----
+
+.. _converting-argument-sequence:
+
+Converting an argument sequence to a string on Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On Windows, an *args* sequence is converted to a string that can be parsed
+using the following rules (which correspond to the rules used by the MS C
+runtime):
+
+1. Arguments are delimited by white space, which is either a
+   space or a tab.
+
+2. A string surrounded by double quotation marks is
+   interpreted as a single argument, regardless of white space
+   contained within.  A quoted string can be embedded in an
+   argument.
+
+3. A double quotation mark preceded by a backslash is
+   interpreted as a literal double quotation mark.
+
+4. Backslashes are interpreted literally, unless they
+   immediately precede a double quotation mark.
+
+5. If backslashes immediately precede a double quotation mark,
+   every pair of backslashes is interpreted as a literal
+   backslash.  If the number of backslashes is odd, the last
+   backslash escapes the next double quotation mark as
+   described in rule 3.
+

-- 
Repository URL: http://hg.python.org/cpython