Sarge

0.1.8 · active · verified Thu Apr 16

Sarge is a Python library that wraps the standard `subprocess` module, providing enhanced cross-platform functionality for running shell commands and pipelines. It simplifies common tasks such as command chaining, robust output capture, and secure command formatting to prevent shell injection, aiming to make interactions with external programs easier than direct `subprocess` usage. The current stable version is 0.1.8, released recently in 2026, and the project actively maintains its documentation.

Common errors

```
SyntaxError: invalid syntax (for 'async')
```
cause Using `async` as a keyword argument in `sarge.run()` or similar functions in Python 3.7+ environments, where `async` became a reserved keyword.

fix Change the keyword argument from `async=True` to `async_=True`.
```
UnicodeEncodeError: 'ascii' codec can't encode character...
```
cause Attempting to pass Unicode strings containing non-ASCII characters to a child process on Python 2.x, especially when `sarge`'s environment handling expects native strings on Windows, without proper encoding.

fix Explicitly encode Unicode strings to bytes using UTF-8 before passing them as input, or ensure environment variables on Python 2.x Windows are native `str` types. Sarge itself will use UTF-8 for text-to-bytes conversion internally for most inputs.
```
CommandNotFound: [Errno 2] No such file or directory: 'some_command'
```
cause The shell command specified in `sarge.run()` or similar functions cannot be found in the system's PATH, or on Windows, the command or its associated executable cannot be resolved.

fix Verify that the command is correctly spelled and executable, and that its directory is included in the system's PATH environment variable. On Windows, ensure that associated executables (e.g., Python for `.py` scripts) are properly registered or in PATH.

Warnings

gotcha The `async` keyword argument was renamed to `async_` in version 0.1.5+ because `async` became a reserved keyword in Python 3.7. Using `async` in newer Python versions will result in a `SyntaxError`.
Fix: Always use `async_` instead of `async` when specifying asynchronous execution for commands, especially in Python 3.7 and newer.
gotcha Sarge's asynchronous features (commands specified with `&` in a pipeline) are considered experimental and their API might be subject to change in future minor releases.
Fix: While these features are available, be aware that code relying heavily on asynchronous command execution might require adjustments with future updates. Stick to synchronous execution for maximum stability if not critical.
gotcha Sarge communicates data (input to commands, captured output) as bytes, not text, and defaults to UTF-8 encoding for text-to-bytes conversion. This differs from Python 2.x's default ASCII encoding and can lead to `UnicodeEncodeError` or `UnicodeDecodeError` if not handled correctly.
Fix: Ensure all input data is properly encoded to bytes (e.g., `text.encode('utf-8')`) and decoded from bytes (e.g., `p.stdout.text` will decode with UTF-8 by default in sarge). For Python 2.x, use `from __future__ import unicode_literals` and byte literals (e.g., `b'foo'`) for cross-version compatibility.
gotcha Sarge, like `subprocess`, cannot directly interact with programs that require a controlling terminal (e.g., `ftp`, `ssh` for password prompts). It operates on `stdin`, `stdout`, and `stderr` streams, not pseudo-terminals.
Fix: For programs requiring direct terminal interaction or pseudo-terminal emulation, consider using libraries like `pexpect` instead of `sarge`.

Install

pip install sarge Install stable version

Imports

run
```
from sarge import run
```
Primary function to execute shell commands and pipelines.
capture_stdout
```
from sarge import capture_stdout
```
Convenience function to run a command and capture its standard output.
Pipeline
```
from sarge import Pipeline
```
Represents a sequence of commands, returned by `run()` and similar functions.
Command
```
from sarge import Command
```
Represents a single command within a pipeline.
Capture
```
from sarge import Capture
```
Object used to read captured stdout/stderr streams.
shell_format
```
from sarge import shell_format
```
Utility for safely formatting shell commands to prevent injection attacks.

Quickstart

This quickstart demonstrates how to use `sarge.run` to execute single commands and pipelines, capture output, and inspect return codes. The `Capture()` object is used to collect stdout for later access.

import sarge

# Run a simple command and get its output
p = sarge.run('echo "Hello from Sarge!"', stdout=sarge.Capture())
print(p.stdout.text.strip())

# Run a command pipeline
p = sarge.run('ls -l | grep .py', stdout=sarge.Capture())
print(p.stdout.text)

# Check return codes
p = sarge.run('false || echo success', stdout=sarge.Capture())
print(f"Return code: {p.returncode}")
print(f"Output: {p.stdout.text.strip()}")

view raw JSON →