Runs

1.3.0 · active · verified Thu Apr 09

Runs is a Python library (version 1.3.0) that enhances the standard `subprocess` module by providing improved functions to execute blocks of text as sequences of shell commands. It adds features like multi-command execution, line continuations, comment handling, optional logging, error handling, lazy evaluation, and defaults to UTF-8 encoding. It offers more robust handling for scenarios that often trip up the native `subprocess` functions.

Warnings

gotcha By default, the `runs` library splits input text into commands by newlines. Ensure that multi-line commands intended as a single unit use line continuations (e.g., `\`) as expected by your shell, or pass commands as a list of strings.
Fix: Use explicit line continuations for multi-line shell commands within a single text block, or pass commands as a list of strings if precise command separation is critical, e.g., `runs.run(['command arg1 arg2', 'another_command'])`.
gotcha While `runs` aims to improve `subprocess` error handling, raw shell commands executed with `shell=True` (which `runs` implies when passing a single string block) are susceptible to shell injection if untrusted input is included. Always sanitize or escape user-provided data.
Fix: Avoid constructing command strings with unsanitized user input. If user input must be part of a command, pass the command and its arguments as a list of strings (where each element is an argument) rather than a single string, to bypass shell interpretation. Alternatively, use `shlex.quote()` to properly escape individual arguments.
gotcha The `runs` library processes commands sequentially. For long-running or concurrent tasks, using `runs` might block your main program. It does not inherently provide asynchronous execution or process management capabilities beyond waiting for completion.
Fix: For asynchronous or parallel execution, consider directly using `subprocess.Popen` or dedicated async/parallel processing libraries like `asyncio.create_subprocess_exec` or `multiprocessing`.
breaking The library's functions (e.g., `run()`, `check_output()`) return a list of strings, one for each command executed in the input block. This differs from `subprocess.run()` which returns a single `CompletedProcess` object.
Fix: Adjust your code to iterate over the returned list if you expect multiple outputs, or access `result[0]` if only the first command's output is relevant. Remember that each element in the list is the `stdout` of a command, not a `CompletedProcess` object.

Install

pip install runs Install stable version

Imports

run
```
from runs import run
```
Used for executing commands and waiting for completion, returning a list of results.
call
```
from runs import call
```
Equivalent to subprocess.call() but for multiple commands/text blocks.
check_call
```
from runs import check_call
```
Similar to subprocess.check_call(), raises CalledProcessError on non-zero exit codes.
check_output
```
from runs import check_output
```
Similar to subprocess.check_output(), captures output and raises CalledProcessError on failure.

Quickstart

This example demonstrates how to use `runs.run()` to execute a multi-line block of commands and capture their output. It also shows how to enable echoing commands and handle exceptions from failing subprocesses. The library provides a more convenient interface for common shell interactions than the raw `subprocess` module.

from runs import run

# Run a block of text as multiple commands
output = run('''
  echo "Hello from Runs!"
  ls -l
''')

for line in output:
    print(line)

# Run with error handling and echo
try:
    result = run('false; echo ok', on_exception=False, echo=True)
except Exception as e:
    print(f"Caught expected error: {e}")

# Get stdout of a single command
stdout_list = run('echo "Single command output"')
print(stdout_list[0])

view raw JSON →