{"id":9294,"library":"sarge","title":"Sarge","description":"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.","status":"active","version":"0.1.8","language":"en","source_language":"en","source_url":"https://github.com/vsajip/sarge","tags":["subprocess","shell","command-line","pipeline","cross-platform","process management"],"install":[{"cmd":"pip install sarge","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Primary function to execute shell commands and pipelines.","symbol":"run","correct":"from sarge import run"},{"note":"Convenience function to run a command and capture its standard output.","symbol":"capture_stdout","correct":"from sarge import capture_stdout"},{"note":"Represents a sequence of commands, returned by `run()` and similar functions.","symbol":"Pipeline","correct":"from sarge import Pipeline"},{"note":"Represents a single command within a pipeline.","symbol":"Command","correct":"from sarge import Command"},{"note":"Object used to read captured stdout/stderr streams.","symbol":"Capture","correct":"from sarge import Capture"},{"note":"Utility for safely formatting shell commands to prevent injection attacks.","symbol":"shell_format","correct":"from sarge import shell_format"}],"quickstart":{"code":"import sarge\n\n# Run a simple command and get its output\np = sarge.run('echo \"Hello from Sarge!\"', stdout=sarge.Capture())\nprint(p.stdout.text.strip())\n\n# Run a command pipeline\np = sarge.run('ls -l | grep .py', stdout=sarge.Capture())\nprint(p.stdout.text)\n\n# Check return codes\np = sarge.run('false || echo success', stdout=sarge.Capture())\nprint(f\"Return code: {p.returncode}\")\nprint(f\"Output: {p.stdout.text.strip()}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always use `async_` instead of `async` when specifying asynchronous execution for commands, especially in Python 3.7 and newer.","message":"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`.","severity":"gotcha","affected_versions":"0.1.5+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (especially Python 2.x users)"},{"fix":"For programs requiring direct terminal interaction or pseudo-terminal emulation, consider using libraries like `pexpect` instead of `sarge`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the keyword argument from `async=True` to `async_=True`.","cause":"Using `async` as a keyword argument in `sarge.run()` or similar functions in Python 3.7+ environments, where `async` became a reserved keyword.","error":"SyntaxError: invalid syntax (for 'async')"},{"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.","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.","error":"UnicodeEncodeError: 'ascii' codec can't encode character..."},{"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.","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.","error":"CommandNotFound: [Errno 2] No such file or directory: 'some_command'"}]}