#!/usr/bin/env python3
+# © Copyright 2021-2022, Scott Gasch
+
+"""Helper methods concerned with executing subprocesses."""
+
import atexit
import logging
import os
import sys
from typing import List, Optional
-
logger = logging.getLogger(__file__)
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.
+ """Kick off a child process. Capture and emit all output that it
+ produces on stdout and stderr in a character by character manner
+ so that we don't have to wait on newlines. This was done to
+ capture the output of a subprocess that created dots to show
+ incremental progress on a task and render it correctly.
+
+ Args:
+ command: the command to execute
+ Returns:
+ the exit status of the subprocess once the subprocess has
+ exited
+
+ Side effects:
+ prints all output of the child process (stdout or stderr)
"""
+
line_enders = set([b'\n', b'\r'])
sel = selectors.DefaultSelector()
with subprocess.Popen(
stderr=subprocess.PIPE,
universal_newlines=False,
) as p:
- sel.register(p.stdout, selectors.EVENT_READ)
- sel.register(p.stderr, selectors.EVENT_READ)
+ sel.register(p.stdout, selectors.EVENT_READ) # type: ignore
+ sel.register(p.stderr, selectors.EVENT_READ) # type: ignore
done = False
while not done:
for key, _ in sel.select():
- char = key.fileobj.read(1)
+ char = key.fileobj.read(1) # type: ignore
if not char:
sel.unregister(key.fileobj)
if len(sel.get_map()) == 0:
sel.close()
done = True
if key.fileobj is p.stdout:
- # sys.stdout.buffer.write(char)
os.write(sys.stdout.fileno(), char)
if char in line_enders:
sys.stdout.flush()
else:
- # sys.stderr.buffer.write(char)
os.write(sys.stderr.fileno(), char)
if char in line_enders:
sys.stderr.flush()
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.
- 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.
+def cmd_with_timeout(command: str, timeout_seconds: Optional[float] = None) -> int:
+ """Run a command but do not let it run for more than timeout_seconds.
+ This code doesn't capture or rebroadcast the command's output. It
+ returns the exit value of the command or raises a TimeoutExpired
+ exception if the deadline is exceeded.
+
+ Args:
+ command: the command to run
+ timeout_seconds: the max number of seconds to allow the subprocess
+ to execute or None to indicate no timeout
+
+ Returns:
+ the exit status of the subprocess once the subprocess has
+ exited
>>> cmd_with_timeout('/bin/echo foo', 10.0)
0
- >>> cmd_with_timeout('/bin/sleep 2', 0.1)
+ >>> cmd_with_timeout('/bin/sleep 2', 0.01)
Traceback (most recent call last):
...
- subprocess.TimeoutExpired: Command '['/bin/bash', '-c', '/bin/sleep 2']' timed out after 0.1 seconds
+ subprocess.TimeoutExpired: Command '['/bin/bash', '-c', '/bin/sleep 2']' timed out after 0.01 seconds
"""
return subprocess.check_call(["/bin/bash", "-c", command], timeout=timeout_seconds)
def cmd(command: str, timeout_seconds: Optional[float] = None) -> str:
- """Run a command and capture its output to stdout (only) in a string.
- Return that string as this function's output. Raises
+ """Run a command and capture its output to stdout (only) into a string
+ buffer. Return that string as this function's output. Raises
subprocess.CalledProcessError or TimeoutExpired on error.
+ Args:
+ command: the command to run
+ timeout_seconds: the max number of seconds to allow the subprocess
+ to execute or None to indicate no timeout
+
+ Returns:
+ The captured output of the subprocess' stdout as a string buffer
+
>>> cmd('/bin/echo foo')[:-1]
'foo'
- >>> cmd('/bin/sleep 2', 0.1)
+ >>> cmd('/bin/sleep 2', 0.01)
Traceback (most recent call last):
...
- subprocess.TimeoutExpired: Command '/bin/sleep 2' timed out after 0.1 seconds
+ subprocess.TimeoutExpired: Command '/bin/sleep 2' timed out after 0.01 seconds
"""
ret = subprocess.run(
command,
shell=True,
- capture_output=True,
+ # capture_output=True,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
check=True,
timeout=timeout_seconds,
).stdout
"""Run a command silently but raise subprocess.CalledProcessError if
it fails.
+ Args:
+ command: the command to run
+ timeout_seconds: the max number of seconds to allow the subprocess
+ to execute or None to indicate no timeout
+
+ Returns:
+ No return value; error conditions (including non-zero child process
+ exits) produce exceptions.
+
>>> run_silently("/usr/bin/true")
>>> run_silently("/usr/bin/false")
def cmd_in_background(command: str, *, silent: bool = False) -> subprocess.Popen:
+ """Spawns a child process in the background and registers an exit
+ handler to make sure we kill it if the parent process (us) is
+ terminated.
+
+ Args:
+ command: the command to run
+ silent: do not allow any output from the child process to be displayed
+ in the parent process' window
+
+ Returns:
+ the :class:`Popen` object that can be used to communicate
+ with the background process.
+ """
args = shlex.split(command)
if silent:
subproc = subprocess.Popen(
def kill_subproc() -> None:
try:
if subproc.poll() is None:
- logger.info(f'At exit handler: killing {subproc} ({command})')
+ logger.info('At exit handler: killing %s (%s)', subproc, command)
subproc.terminate()
subproc.wait(timeout=10.0)
except BaseException as be:
projects / python_utils.git / blobdiff