Subprocess Run

0.0.8 · maintenance · verified Fri Apr 17

subprocess-run is a Python library that extends the standard `subprocess` module, offering a simplified `run` function with opinionated defaults like `check=True` and stripped output. It provides a more convenient way to execute external commands compared to the standard library's `subprocess.Popen`. The current version is 0.0.8, with the last release approximately two years ago, indicating a maintenance-focused project rather than active development.

Common errors

```
ModuleNotFoundError: No module named 'subprocess_run'
```
cause The `subprocess-run` package is not installed or the import statement uses the incorrect module name.

fix Ensure the package is installed using `pip install subprocess-run`. Verify your import statement is `from subprocess_run import run` or `from subprocess_run import popen`.
```
TypeError: run() got an unexpected keyword argument 'input'
```
cause You are attempting to use the `input` keyword argument, which is present in the standard library `subprocess.run()`, but `subprocess_run.run()` uses `input_data` for providing data to stdin.

fix Change `input=b'your data'` to `input_data=b'your data'` when calling `subprocess_run.run()`.
```
subprocess.CalledProcessError: Command '['false']' returned non-zero exit status 1.
```
cause The command executed returned a non-zero exit status, and `subprocess_run.run()` has `check=True` by default, which raises a `CalledProcessError` in such cases.

fix Handle the `subprocess.CalledProcessError` exception if you expect the command to fail gracefully, or pass `check=False` to `run()` if you intend to process non-zero exit codes manually without raising an exception.

Warnings

gotcha The default behavior of `subprocess_run.run()` differs significantly from the standard library `subprocess.run()`. Key differences include: `check=True` by default (raises `CalledProcessError` on non-zero exit), `strip_result=True` by default (strips whitespace from stdout/stderr), `return_tuple=True` by default (returns `(exit_code, stdout, stderr)`), and it uses `input_data` for stdin instead of `input`.
Fix: Always consult the `subprocess-run` documentation for specific parameter usage. Be aware of the default `check=True` and `strip_result=True` and explicitly set them to `False` if standard library behavior is desired.
gotcha The `subprocess-run` library appears to be in maintenance mode, with the last release (0.0.8) and significant activity occurring over two years ago. This means it may not receive updates for new Python versions, security patches, or feature enhancements.
Fix: Evaluate if the current feature set meets your needs. For projects requiring active development, newer Python compatibility, or specific bug fixes, consider the standard `subprocess` module or more actively maintained alternatives if `subprocess-run` specific features are not critical.

Install

pip install subprocess-run Install stable version

Imports

run
wrong:
```
import subprocess_run
```
correct:
```
from subprocess_run import run
```
The 'run' function is exposed directly, not as an attribute of the top-level package, and the package name is `subprocess_run`, not `subprocess.run` (stdlib).
popen
wrong:
```
import subprocess_run.popen
```
correct:
```
from subprocess_run import popen
```
The 'popen' function is exposed directly, similar to 'run'.

Quickstart

This quickstart demonstrates how to use the `subprocess_run.run` function for basic command execution, handling failing commands (due to default `check=True`), and providing input data via stdin using `input_data`.

from subprocess_run import run

# Execute a simple command
print("Executing a simple command:")
try:
    # run() returns (exit_code, stdout, stderr) by default with return_tuple=True
    exit_code, stdout, stderr = run(["echo", "Hello from subprocess-run!"])
    print(f"Success: '{stdout.strip()}'")
    print(f"Exit code: {exit_code}")
except Exception as e:
    print(f"Error: {e}")

# Command failing with default check=True
# 'false' is a common Unix command that always exits with a non-zero status.
# On Windows, you might use ['cmd', '/c', 'exit 1']
print("\nAttempting to run a command that will fail (check=True by default):")
try:
    run(["false"])
except Exception as e:
    print(f"Caught expected error for failing command: {e}") # e.g., CalledProcessError

# Command with input data (stdin)
# 'cat -' on Unix-like systems reads from stdin.
# For cross-platform, a simple python script could echo stdin:
# ['python', '-c', 'import sys; print(sys.stdin.read())']
print("\nExecuting a command with input data:")
try:
    input_text = "Data for stdin"
    _, output, _ = run(["cat", "-"], input_data=input_text.encode('utf-8'))
    print(f"Input: '{input_text}', Output from stdin command: '{output.strip()}'")
except Exception as e:
    print(f"Error with input_data: {e}")

view raw JSON →