How do you run external commands with subprocess safely?

# subprocess.run the safe way: a list, check=True, captured text, a timeout.
# (The page runtime cannot start processes, so this runs on CPython 3.12.)
import os
import subprocess
import sys

PY = sys.executable          # use the current Python as a portable "external program"

# 1. The everyday call.
r = subprocess.run(
    [PY, "-c", "import sys; print('hello', sys.argv[1:])", "a b", "c"],
    capture_output=True, text=True, check=True, timeout=10,
)
print(type(r).__name__, r.returncode, repr(r.stdout))

# 2. Non-zero exit: without check=True it is silently ignored.
quiet = subprocess.run([PY, "-c", "import sys; sys.exit(3)"])
print("returncode without check:", quiet.returncode)
try:
    subprocess.run([PY, "-c", "import sys; print('boom', file=sys.stderr); sys.exit(3)"],
                   capture_output=True, text=True, check=True)
except subprocess.CalledProcessError as e:
    print("CalledProcessError:", e.returncode, repr(e.stderr))

# 3. A hung child: timeout kills it and raises.
try:
    subprocess.run([PY, "-c", "import time; time.sleep(30)"], timeout=0.5)
except subprocess.TimeoutExpired as e:
    print("TimeoutExpired: child killed, timeout about", round(e.timeout, 1), "s")

# 4. A program that does not exist raises before anything runs.
try:
    subprocess.run(["no-such-program-xyz", "--help"])
except FileNotFoundError as e:
    print("FileNotFoundError:", e.filename)

# 5. Send input on stdin; control the environment and working directory.
r = subprocess.run(
    [PY, "-c", "import os, sys; print(sys.stdin.read().upper(), os.environ['MODE'], os.getcwd() == os.path.realpath('/'))"],
    input="data from python", capture_output=True, text=True, check=True,
    env={**os.environ, "MODE": "batch"}, cwd="/",
)
print(r.stdout.strip())

# 6. Bytes unless you ask for text.
r = subprocess.run([PY, "-c", "print('caf\\u00e9')"], capture_output=True, check=True,
                   env={**os.environ, "PYTHONIOENCODING": "utf-8"})
print(type(r.stdout).__name__, r.stdout, r.stdout.decode("utf-8").strip())

# shell=True injection, a pipeline without a shell, and streaming with Popen.
# (Needs real processes, so it runs on CPython 3.12, not in the page.)
import shlex
import shutil
import subprocess
import sys

print("echo found on PATH:", shutil.which("echo") is not None)

# A "file name" an attacker typed into a form:
name = "report.txt; echo INJECTED"

# UNSAFE: the whole string goes to /bin/sh, which runs two commands.
unsafe = subprocess.run("echo processing " + name, shell=True,
                        capture_output=True, text=True)
print("shell=True :", unsafe.stdout.splitlines())

# SAFE: a list. The name is one argv element; no shell ever parses it.
safe = subprocess.run(["echo", "processing", name], capture_output=True, text=True)
print("list argv  :", safe.stdout.splitlines())

# If a shell is unavoidable, quote every untrusted piece.
quoted = subprocess.run("echo processing " + shlex.quote(name), shell=True,
                        capture_output=True, text=True)
print("quoted     :", quoted.stdout.splitlines())

# A pipeline (like  printf ... | sort  ) built from two processes, no shell.
p1 = subprocess.Popen(["printf", "pear\\napple\\nfig\\n"], stdout=subprocess.PIPE)
p2 = subprocess.Popen(["sort"], stdin=p1.stdout, stdout=subprocess.PIPE, text=True)
p1.stdout.close()            # so p1 gets SIGPIPE if sort exits early
out, _ = p2.communicate(timeout=10)
p1.wait(timeout=10)
print("pipeline   :", out.split(), "exit codes", p1.returncode, p2.returncode)

# Streaming: read a long-running child line by line as it prints.
code = "import time\nfor i in range(3):\n    print('step', i, flush=True)\n    time.sleep(0.05)"
with subprocess.Popen([sys.executable, "-c", code], stdout=subprocess.PIPE, text=True) as proc:
    for line in proc.stdout:
        print("got:", line.rstrip())
print("streamed child exit code:", proc.returncode)