subprocess-tee

library0.4.2pypypi✓ verified 24d ago

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.

devops

pip install subprocess-tee

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · SUBPROCESS-TEE

subprocess-tee

devopspythonv0.4.2

Install

1.6s avg

Import

263ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.280s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.246s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ from subprocess_tee import run

The primary function `run` replaces `subprocess.run`.

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}")

Debug

Known issues

gotchaThe `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.

affects: All versions

gotchaThere 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.

affects: All versions

gotchaThe 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.

affects: All versions

gotchaUsing `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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'subprocess_tee'

The package is installed as `subprocess-tee` using a hyphen, but the Python module name uses an underscore (`subprocess_tee`).

fix

Use `import subprocess_tee` in your Python code.

subprocess_tee.CalledProcessError: Command '['ls', 'nonexistent_file']' returned non-zero exit status 1.

The executed command returned a non-zero exit status, and the `check=True` parameter (which is the default in `subprocess_tee.run()`) caused an exception to be raised.

fix

Handle the exception using a `try...except subprocess_tee.CalledProcessError` block, or explicitly pass `check=False` to `subprocess_tee.run()` if you intend to ignore non-zero exit codes.

TypeError: a bytes-like object is required, not 'str'

The output (`stdout` or `stderr`) from the child process is in a different type (bytes or string) than expected, often due to the `text` or `universal_newlines` argument in `subprocess_tee.run()`.

fix

Ensure consistency: if `text=True` (default for `subprocess_tee`), `result.stdout` is a string. If `text=False`, `result.stdout` is bytes and needs decoding (e.g., `result.stdout.decode('utf-8')`) before string operations, or ensure you are passing bytes where expected.

subprocess-tee stdin input

The user wants to provide input to the child process via its standard input, but is unsure how to pass it using `subprocess_tee.run()`.

fix

Use the `input` keyword argument, passing the input as a string (if `text=True`) or bytes (if `text=False`): `subprocess_tee.run(command, input='my input data', text=True)`.

Upgrade

Version history

0.4.2latest on PyPI · released Jun 17, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/pycontribs/subprocess-tee ↗

packagehttps://pypi.org/project/subprocess-tee/ ↗

docshttps://subprocess-tee.readthedocs.io ↗

changeloghttps://github.com/pycontribs/subprocess-tee/releases ↗