update from Peter Astrand

pep-0000.txt

@@ -119,7 +119,7 @@ Index by Category
  S   319  Python Synchronize/Asynchronize Block        Pelletier
  S   321  Date/Time Parsing and Formatting             Kuchling
  S   323  Copyable Iterators                           Martelli
- S   324  popen5 - New POSIX process module            Astrand
+ S   324  process - New POSIX process module           Astrand
  S   325  Resource-Release Support for Generators      Pedroni
  S   330  Python Bytecode Verification                 Pelletier
  S   331  Locale-Independent Float/String conversions  Reis
@@ -347,7 +347,7 @@ Numerical Index
  S   321  Date/Time Parsing and Formatting             Kuchling
  SF  322  Reverse Iteration                            Hettinger
  S   323  Copyable Iterators                           Martelli
- S   324  popen5 - New POSIX process module            Astrand
+ S   324  process - New POSIX process module           Astrand
  S   325  Resource-Release Support for Generators      Pedroni
  SR  326  A Case for Top and Bottom Values             Carlson, Reedy
  SF  327  Decimal Data Type                            Batista

pep-0324.txt

@@ -1,5 +1,5 @@
 PEP: 324
-Title: popen5 - New POSIX process module
+Title: process - New POSIX process module
 Version: $Revision$
 Last-Modified: $Date$
 Author: Peter Astrand <astrand@lysator.liu.se>
@@ -33,7 +33,7 @@ Motivation
     Currently, Python has a large number of different functions for
     process creation. This makes it hard for developers to choose.
 
-    The popen5 modules provides the following enhancements over
+    The process module provides the following enhancements over
     previous functions:
 
     - One "unified" module provides all functionality from previous
@@ -56,8 +56,8 @@ Motivation
       and redirect stderr, but not stdout.  This is not possible with
       current functions, without using temporary files.
 
-    - With popen5, it's possible to control if all open file
+    - With the process module, it's possible to control if all open
-      descriptors should be closed before the new program is
+      file descriptors should be closed before the new program is
       executed.
 
     - Support for connecting several subprocesses (shell "pipe").
@@ -78,23 +78,23 @@ Rationale
 
     The following points summarizes the design:
 
-    - popen5 was based on popen2, which is tried-and-tested.
+    - process was based on popen2, which is tried-and-tested.
 
     - The factory functions in popen2 have been removed, because I
       consider the class constructor equally easy to work with.
 
     - popen2 contains several factory functions and classes for
-      different combinations of redirection.  popen5, however,
+      different combinations of redirection.  process, however,
-      contains one single class.  Since popen5 supports 12 different
+      contains one single class.  Since the process module supports 12
-      combinations of redirection, providing a class or function for
+      different combinations of redirection, providing a class or
-      each of them would be cumbersome and not very intuitive.  Even
+      function for each of them would be cumbersome and not very
-      with popen2, this is a readability problem.  For example, many
+      intuitive.  Even with popen2, this is a readability problem.
-      people cannot tell the difference between popen2.popen2 and
+      For example, many people cannot tell the difference between
-      popen2.popen4 without using the documentation.
+      popen2.popen2 and popen2.popen4 without using the documentation.
 
-    - One small utility function is provided: popen5.run().  It aims
+    - Two small utility functions are provided: process.call() and
-      to be an enhancement over os.system(), while still very easy to
+      process.callv().  These aims to be an enhancement over
-      use:
+      os.system(), while still very easy to use:
 
         - It does not use the Standard C function system(), which has
           limitations.
@@ -105,6 +105,43 @@ Rationale
 
         - The return value is easier to work with.
 
+      The call() utility function accepts an 'args' argument, just
+      like the Popen class constructor. It waits for the command to
+      complete, then returns the returncode attribute. The
+      implementation is very simple:
+
+      def call(*args, **kwargs):
+          return Popen(*args, **kwargs).wait()
+
+      The motivation behind the call() function is simple: Starting a
+      process and wait for it to finish is a common task.
+
+      The callv() function is identical to call(), except that each
+      non-keyword argument is treated as a program argument. This
+      gives a slightly nicer syntax. The drawback is that callv() does
+      not allow specifying the program and it's arguments as a
+      whitespace-separated string: The entire (first) string would be
+      intepreted as the executable. The implementation of callv() is
+      also very simple:
+
+      def callv(*args, **kwargs):
+          return Popen(args, **kwargs).wait()
+
+      While Popen supports a wide range of options, many users have
+      simple needs. Many people are using os.system() today, mainly
+      because it provides a simple interface. Consider this example:
+
+          os.system("stty sane -F " + device)
+
+      With process.call(), this would look like:
+
+          process.call(["stty", "sane", "-F", device])
+
+      Some people feel that the list brackets are clumsy. With
+      callv(), they are not needed:
+
+          process.callv("stty", "sane", "-F", device)
+
     - The "preexec" functionality makes it possible to run arbitrary
       code between fork and exec.  One might ask why there are special
       arguments for setting the environment and current directory, but
@@ -119,26 +156,38 @@ Rationale
         - env and cwd are considered quite cross-platform: They make
           sense even on Windows.
 
-     - No MS Windows support is available, currently.  To be able to
-       provide more functionality than what is already available from
-       the popen2 module, help from C modules is required.
-
 
 Specification
 
     This module defines one class called Popen:
 
-        class Popen(args, bufsize=0, argv0=None,
+        class Popen(args, bufsize=0, executable=None,
                     stdin=None, stdout=None, stderr=None,
-                    preexec_fn=None, preexec_args=(), close_fds=0,
+                    preexec_fn=None, close_fds=False,
-                    cwd=None, env=None, universal_newlines=0)
+                    cwd=None, env=None, universal_newlines=False,
+                    startupinfo=None, creationflags=0):
+        
       
       Arguments are:
       
     - args should be a sequence of program arguments.  The program to
       execute is normally the first item in the args sequence, but can
-      be explicitly set by using the argv0 argument.  The Popen class
+      be explicitly set by using the executable argument.
-      uses os.execvp() to execute the child program.
+      
+    - On UNIX: the Popen class uses os.execvp() to execute the child
+      program, which operates on sequences.  If args is a string, it
+      will be converted to a sequence using the cmdline2list method.
+      Please note that syntax for quoting arguments is different from
+      a typical UNIX shell.  See the documentation of the cmdline2list
+      method for more information.
+      
+    - 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: The
+      list2cmdline is designed for applications using the same rules
+      as the MS C runtime.
       
     - bufsize, if given, has the same meaning as the corresponding
       argument to the built-in open() function: 0 means unbuffered, 1
@@ -159,8 +208,7 @@ Specification
       stdout.
 
     - If preexec_fn is set to a callable object, this object will be
-      called in the child process just before the child is executed,
+      called in the child process just before the child is executed.
-      with arguments preexec_args.
 
     - If close_fds is true, all file descriptors except 0, 1 and 2
       will be closed before the child process is executed.
@@ -171,46 +219,67 @@ Specification
     - If env is not None, it defines the environment variables for the
       new process.
 
-    - If universal_newlines is true, the file objects fromchild and
+    - If universal_newlines is true, the file objects stdout and
-      childerr are opened as a text files, but lines may be terminated
+      stderr are opened as a text files, but lines may be terminated
       by any of '\n', the Unix end-of-line convention, '\r', the
       Macintosh convention or '\r\n', the Windows convention.  All of
       these external representations are seen as '\n' by the Python
       program.  Note: This feature is only available if Python is
       built with universal newline support (the default).  Also, the
-      newlines attribute of the file objects fromchild, tochild and
+      newlines attribute of the file objects stdout, stdin and stderr
-      childerr are not updated by the communicate() method.
+      are not updated by the communicate() method.
 
-    The module also defines one shortcut function:
+    - The startupinfo and creationflags, if given, will be passed to
+      the underlying CreateProcess() function.  They can specify
+      things such as appearance of the main window and priority for
+      the new process.  (Windows only)
       
-        run(*args):
-            Run command with arguments.  Wait for command to complete,
-            then return the returncode attribute.  Example:
       
-                retcode = popen5.run("stty", "sane")
+      This module also defines two shortcut functions:
+      
+    - call(*args, **kwargs):
+          Run command with arguments.  Wait for command to complete, then
+          return the returncode attribute.
+      
+          The arguments are the same as for the Popen constructor.  Example:
+      
+          retcode = call(["ls", "-l"])
+      
+      
+    - callv(*args, **kwargs):
+          Run command with arguments.  Wait for command to complete, then
+          return the returncode attribute.
+      
+          This function is identical to call(), except that each non-keyword
+          argument is treated as a program argument.  Example:
+      
+          retcode = callv("ls", "-l")
+      
+          This is equivalent to:
+      
+          retcode = call(["ls", "-l"])
           
       
     Exceptions
     ----------
     Exceptions raised in the child process, before the new program has
-    started to execute, will be re-raised in the parent.  Additionally,
+    started to execute, will be re-raised in the parent.
-    the exception object will have one extra attribute called
+    Additionally, the exception object will have one extra attribute
-    'child_traceback', which is a string containing traceback
+    called 'child_traceback', which is a string containing traceback
-    information from the child's point of view.
+    information from the childs point of view.
     
     The most common exception raised is OSError.  This occurs, for
     example, when trying to execute a non-existent file.  Applications
     should prepare for OSErrors.
     
-    A PopenException will also be raised if Popen is called with
+    A ValueError will be raised if Popen is called with invalid arguments.
-    invalid arguments.
     
     
     Security
     --------
-    popen5 will never call /bin/sh implicitly.  This means that all
+    Unlike some other popen functions, this implementation will never call
-    characters, including shell metacharacters, can safely be passed
+    /bin/sh implicitly.  This means that all characters, including shell
-    to child processes.
+    metacharacters, can safely be passed to child processes.
     
     
     Popen objects
@@ -218,17 +287,11 @@ Specification
     Instances of the Popen class have the following methods:
 
     poll()
-        Returns -1 if child process hasn't completed yet, or its exit
+        Check if child process has terminated.  Returns returncode
-        status otherwise.  See below for a description of how the exit
+        attribute.
-        status is encoded.
     
     wait()
-        Waits for and returns the exit status of the child process.
+        Wait for child process to terminate.  Returns returncode attribute.
-        The exit status encodes both the return code of the process
-        and information about whether it exited using the exit()
-        system call or died due to a signal.  Functions to help
-        interpret the status code are defined in the os module (the
-        W*() family of functions).
     
     communicate(input=None)
         Interact with process: Send data to stdin.  Read data from
@@ -244,30 +307,35 @@ Specification
 
     The following attributes are also available:
     
-    fromchild
+    stdin
-        A file object that provides output from the child process.
+        If the stdin argument is PIPE, this attribute is a file object
+        that provides input to the child process.  Otherwise, it is None.
     
-    tochild
+    stdout
-        A file object that provides input to the child process.
+        If the stdout argument is PIPE, this attribute is a file object
+        that provides output from the child process.  Otherwise, it is
+        None.
     
-    childerr
+    stderr
-        A file object that provides error output from the child
+        If the stderr argument is PIPE, this attribute is file object that
-        process.
+        provides error output from the child process.  Otherwise, it is
+        None.
     
     pid
         The process ID of the child process.
 
     returncode
         The child return code.  A None value indicates that the
-        process hasn't terminated yet.  A negative value means that
+        process hasn't terminated yet.  A negative value -N indicates
-        the process was terminated by a signal with number
+        that the child was terminated by signal N (UNIX only).
-        -returncode.
           
       
 Open Issues
 
-    Perhaps the module should be called something like "process",
+    Currently, the reference implementation requires the "win32all"
-    instead of "popen5".
+    extensions when running on the Windows platform. This dependency
+    could probably be eliminated by providing a small "glue" module
+    written in C, just like the _winreg module. 
 
 
 Reference Implementation