Update docstrings and add VOID support

subprocess2.py

 # coding=utf8
 # Copyright (c) 2011 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 """Collection of subprocess wrapper functions.
 
 In theory you shouldn't need anything else in subprocess, or this module failed.
 """
 
 from __future__ import with_statement
 import logging
 import os
 import subprocess
 import sys
 import tempfile
 import time
 import threading
 
 # Constants forwarded from subprocess.
 PIPE = subprocess.PIPE
 STDOUT = subprocess.STDOUT
+# Sends stdout or stderr to os.devnull.
+VOID = '/dev/null'
+
 
 # Globals.
 # Set to True if you somehow need to disable this hack.
 SUBPROCESS_CLEANUP_HACKED = False
 
 
 class CalledProcessError(subprocess.CalledProcessError):
   """Augment the standard exception with more data."""
   def __init__(self, returncode, cmd, cwd, stdout, stderr):
     super(CalledProcessError, self).__init__(returncode, cmd)
@@ skipping 84 matching lines @@
     if not is_english(name):
       env[name] = 'en_US.UTF-8'
   fix_lang('LANG')
   fix_lang('LANGUAGE')
   return env
 
 
 def Popen(args, **kwargs):
   """Wraps subprocess.Popen().
 
-  Forces English output since it's easier to parse the stdout if it is always in
-  English.
+  Returns a subprocess.Popen object.
 
-  Sets shell=True on windows by default. You can override this by forcing shell
-  parameter to a value.
+  - Forces English output since it's easier to parse the stdout if it is always
+    in English.
+  - Sets shell=True on windows by default. You can override this by forcing
+    shell parameter to a value.
+  - Adds support for VOID to not buffer when not needed.
 
-  Popen() can throw OSError when cwd or args[0] doesn't exist.
+  Note: Popen() can throw OSError when cwd or args[0] doesn't exist.
   """
   # Make sure we hack subprocess if necessary.
   hack_subprocess()
   add_kill()
 
   env = get_english_env(kwargs.get('env'))
   if env:
     kwargs['env'] = env
 
   if not kwargs.get('shell') is None:
     # *Sigh*:  Windows needs shell=True, or else it won't search %PATH% for the
     # executable, but shell=True makes subprocess on Linux fail when it's called
     # with a list because it only tries to execute the first item in the list.
     kwargs['shell'] = (sys.platform=='win32')
 
   tmp_str = ' '.join(args)
   if kwargs.get('cwd', None):
     tmp_str += ';  cwd=%s' % kwargs['cwd']
   logging.debug(tmp_str)
+
+  # Replaces VOID with handle to /dev/null.
+  if kwargs.get('stdout') in (VOID, os.devnull):
+    kwargs['stdout'] = open(os.devnull, 'w')
+  if kwargs.get('stderr') in (VOID, os.devnull):
+    kwargs['stderr'] = open(os.devnull, 'w')
   return subprocess.Popen(args, **kwargs)
 
 
 def call(args, timeout=None, **kwargs):
   """Wraps subprocess.Popen().communicate().
 
-  The process will be kill with error code -9 after |timeout| seconds if set.
+  Returns ((stdout, stderr), returncode).
 
-  Automatically passes stdin content as input so do not specify stdin=PIPE.
-
-  Returns both communicate() tuple and return code wrapped in a tuple.
+  - The process will be kill with error code -9 after |timeout| seconds if set.
+  - Automatically passes stdin content as input so do not specify stdin=PIPE.
   """
   stdin = kwargs.pop('stdin', None)
   if stdin is not None:
     assert stdin != PIPE
     # When stdin is passed as an argument, use it as the actual input data and
     # set the Popen() parameter accordingly.
     kwargs['stdin'] = PIPE
 
   if not timeout:
     # Normal workflow.
@@ skipping 24 matching lines @@
           # or look at call()[1] == -9.
           proc.returncode = -9
         time.sleep(0.001)
       # Now that the process died, reset the cursor and read the file.
       buff.seek(0)
       out = [buff.read(), None]
   return out, proc.returncode
 
 
 def check_call(args, **kwargs):
-  """Similar to subprocess.check_call() but use call() instead.
+  """Improved version of subprocess.check_call().
 
-  This permits to include more details in CalledProcessError().
-
-  Runs a command and throws an exception if the command failed.
-
-  Returns communicate() tuple.
+  Returns (stdout, stderr), unlike subprocess.check_call().
   """
   out, returncode = call(args, **kwargs)
   if returncode:
     raise CalledProcessError(
         returncode, args, kwargs.get('cwd'), out[0], out[1])
   return out
 
 
 def capture(args, **kwargs):
   """Captures stdout of a process call and returns it.
 
-  Similar to check_output() excepts that it discards return code.
+  Returns stdout.
 
-  Discards communicate()[1]. By default sets stderr=STDOUT.
+  - Discards returncode.
+  - Discards stderr. By default sets stderr=STDOUT.
   """
   if kwargs.get('stderr') is None:
     kwargs['stderr'] = STDOUT
   return call(args, stdout=PIPE, **kwargs)[0][0]
 
 
 def check_output(args, **kwargs):
   """Captures stdout of a process call and returns it.
 
-  Discards communicate()[1]. By default sets stderr=STDOUT.
+  Returns stdout.
 
-  Throws if return code is not 0.
-
-  Works even prior to python 2.7.
+  - Discards stderr. By default sets stderr=STDOUT.
+  - Throws if return code is not 0.
+  - Works even prior to python 2.7.
   """
   if kwargs.get('stderr') is None:
     kwargs['stderr'] = STDOUT
   return check_call(args, stdout=PIPE, **kwargs)[0]