subprocess-tee

0.4.2 · active · verified Thu Apr 09

This package provides a Pythonic alternative to `subprocess.run` that captures the output of a child process while simultaneously printing it to the console in real-time, mimicking the behavior of the `tee` command. It is designed for long-running processes where instant feedback is desirable. The current version is 0.4.2 and it maintains a stable release cadence.

Warnings

gotcha The `subprocess-tee.run` function implies `text=True` (or `universal_newlines=True`) by default. This means output is treated as text (decoded using default encoding, usually UTF-8), which differs from `subprocess.run` where `text=False` (binary output) is the default unless specified.
Fix: Be aware that `stdout` and `stderr` attributes of the `CompletedProcess` object will contain strings, not bytes. If binary output is strictly required, `subprocess-tee` might not be the most suitable tool or may require careful handling of encoding.
gotcha There are known open issues on Windows related to incorrect argument list conversion and lack of support for multiple arguments when not using `shell=True`. This can lead to commands not executing as expected.
Fix: On Windows, consider using `shell=True` with caution (see next warning) or ensure commands are simple strings. Test extensively for complex argument scenarios on Windows environments.
gotcha The library may not correctly handle non-UTF-8 characters in the output of child processes due to an open bug. This could lead to `UnicodeDecodeError` or garbled output.
Fix: If child processes are expected to produce non-UTF-8 output, ensure they are configured to use UTF-8 or be prepared to handle potential encoding issues programmatically. There is currently no direct `encoding` parameter in `subprocess-tee.run` to override the default text handling.
gotcha Using `shell=True` with user-provided input in commands can introduce security vulnerabilities (e.g., command injection). While this is a general `subprocess` module concern, it applies equally to `subprocess-tee`.
Fix: Avoid `shell=True` when executing commands with external or untrusted input. Prefer passing commands as a list of arguments (`['command', 'arg1', 'arg2']`) to bypass the shell.

Install

pip install subprocess-tee Install stable version

Imports

run
```
from subprocess_tee import run
```
The primary function `run` replaces `subprocess.run`.

Quickstart

The `run` function is designed to be a drop-in replacement for `subprocess.run`. By default, it prints output to `sys.stdout` and `sys.stderr` while also capturing it. Use `tee=False` to disable real-time printing if only output capture is needed. The `check=True` argument will raise a `CalledProcessError` on non-zero exit codes, similar to `subprocess.run`.

from subprocess_tee import run

# Basic usage: Command output is printed to console and captured
result = run(["echo", "Hello, subprocess-tee!"])
print(f"Captured stdout: {result.stdout.strip()}")
print(f"Return code: {result.returncode}")

# To explicitly disable tee functionality (e.g., just capture output):
result_no_tee = run(["python", "-c", "import time; print('start'); time.sleep(0.1); print('end')"], tee=False, capture_output=True, text=True)
print(f"Captured stdout without tee: {result_no_tee.stdout.strip()}")

# Example with error and checking return code:
try:
    run(["false"], check=True, capture_output=True, text=True)
except Exception as e:
    print(f"Command failed as expected: {e}")

view raw JSON →