Cleanup docs, add a timeout, in exec_utils.py.

1 files changed, 31 insertions, 12 deletions

diff --git a/exec_utils.py b/exec_utils.py
index edbd21f..a52e206 100644
--- a/exec_utils.py
+++ b/exec_utils.py
@@ -12,7 +12,12 @@ from typing import List, Optional
 logger = logging.getLogger(__file__)
 
 
-def cmd_showing_output(command: str) -> None:
+def cmd_showing_output(command: str, ) -> int:
+    """Kick off a child process.  Capture and print all output that it
+    produces on stdout and stderr.  Wait for the subprocess to exit
+    and return the exit value as the return code of this function.
+
+    """
     line_enders = set([b'\n', b'\r'])
     p = subprocess.Popen(
         command,
@@ -25,12 +30,12 @@ def cmd_showing_output(command: str) -> None:
     sel = selectors.DefaultSelector()
     sel.register(p.stdout, selectors.EVENT_READ)
     sel.register(p.stderr, selectors.EVENT_READ)
-    while True:
+    should_exit = False
+    while not should_exit:
         for key, _ in sel.select():
             char = key.fileobj.read(1)
             if not char:
-                p.wait()
-                return
+                should_exit = True
             if key.fileobj is p.stdout:
                 sys.stdout.buffer.write(char)
                 if char in line_enders:
@@ -39,11 +44,15 @@ def cmd_showing_output(command: str) -> None:
                 sys.stderr.buffer.write(char)
                 if char in line_enders:
                     sys.stderr.flush()
+    p.wait()
+    return p.returncode
 
 
 def cmd_with_timeout(command: str, timeout_seconds: Optional[float]) -> int:
-    """
-    Run a command but do not let it run for more than timeout seconds.
+    """Run a command but do not let it run for more than timeout seconds.
+    Doesn't capture or rebroadcast command output.  Function returns
+    the exit value of the command or raises a TimeoutExpired exception
+    if the deadline is exceeded.
 
     >>> cmd_with_timeout('/bin/echo foo', 10.0)
     0
@@ -60,8 +69,9 @@ def cmd_with_timeout(command: str, timeout_seconds: Optional[float]) -> int:
 
 
 def cmd(command: str, timeout_seconds: Optional[float] = None) -> str:
-    """Run a command with everything encased in a string and return
-    the output text as a string.  Raises subprocess.CalledProcessError.
+    """Run a command and capture its output to stdout (only) in a string.
+    Return that string as this function's output.  Raises
+    subprocess.CalledProcessError or TimeoutExpired on error.
 
     >>> cmd('/bin/echo foo')[:-1]
     'foo'
@@ -73,12 +83,16 @@ def cmd(command: str, timeout_seconds: Optional[float] = None) -> str:
 
     """
     ret = subprocess.run(
-        command, shell=True, capture_output=True, check=True, timeout=timeout_seconds,
+        command,
+        shell=True,
+        capture_output=True,
+        check=True,
+        timeout=timeout_seconds,
     ).stdout
     return ret.decode("utf-8")
 
 
-def run_silently(command: str) -> None:
+def run_silently(command: str, timeout_seconds: Optional[float] = None) -> None:
     """Run a command silently but raise subprocess.CalledProcessError if
     it fails.
 
@@ -91,8 +105,13 @@ def run_silently(command: str) -> None:
 
     """
     subprocess.run(
-        command, shell=True, stderr=subprocess.DEVNULL,
-        stdout=subprocess.DEVNULL, capture_output=False, check=True
+        command,
+        shell=True,
+        stderr=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        capture_output=False,
+        check=True,
+        timeout=timeout_seconds,
     )