sh: Python Subprocess Replacement

Warnings

• breaking The `sh` library is designed exclusively for Unix-like operating systems (Linux, macOS, BSDs). It relies on various Unix system calls and does not support Windows environments.
  Fix: Use `subprocess` module or alternative libraries for cross-platform compatibility, or ensure deployment on Unix-like systems only.
• breaking Upgrading from `sh` 1.x to 2.x involves significant breaking changes. Users are strongly advised to consult the `MIGRATION.md` file in the project's repository or PyPI page before upgrading.
  Fix: Review `MIGRATION.md` and adapt code as necessary to align with the 2.x API.
• gotcha When an executed command exits with a non-zero status code, `sh` raises an `sh.ErrorReturnCode_X` exception (where X is the exit code), rather than silently failing. This behavior must be explicitly handled with `try...except` blocks.
  Fix: Wrap command calls that might return non-zero exit codes in `try...except sh.ErrorReturnCode` blocks to handle errors gracefully.
• gotcha Prior to version 2.2.2, using `async` commands in combination with `_return_cmd=True` could lead to unexpected behavior. Specifically, `await` on such a command might return `str(self)` instead of a `RunningCommand` object, and earlier versions (pre-2.2.1) had bugs where async commands with `return_cmd` did not raise exceptions correctly.
  Fix: Upgrade to `sh` 2.2.2 or later to ensure correct asynchronous behavior and error handling for commands using `_return_cmd=True`.
• gotcha While `sh` provides a Pythonic wrapper, it directly executes underlying shell commands. This means many common shell footguns (e.g., issues with improper quoting, globbing, or special characters in filenames) can still affect your scripts.
  Fix: Be mindful of shell scripting best practices, especially concerning argument quoting and validation. Leverage `sh`'s list-based argument passing where possible, as it generally handles quoting automatically.

Install

• pip install sh Install stable version

Imports

• sh

  import sh

  Imports the main 'sh' object, from which system commands are accessed as attributes (e.g., sh.ls).
• Command

  from sh import Command

  Useful for explicitly calling commands not in PATH or with special characters, e.g., `cmd = Command('/usr/bin/ffmpeg')`.
• ErrorReturnCode

  from sh import ErrorReturnCode_127

  Specific error codes (e.g., ErrorReturnCode_1, ErrorReturnCode_127) are raised when a command exits with a non-zero status. Catch `sh.ErrorReturnCode` for a general handler.
• bash

  from sh.contrib import bash

  Introduced in 2.1.0 for improved Bash integration.

Quickstart

This quickstart demonstrates basic command execution, passing arguments, capturing output, handling non-zero exit codes, and piping commands. Replace `ls` and `python` with commands available on your system.

import sh
import os

# Get the current user
user = os.environ.get('USER', 'unknown_user')
print(f"Hello, {user}!")

# Run a simple command and capture output
output = sh.ls('-l', '/tmp')
print(f"\nls -l /tmp:\n{output}")

# Run a command with arguments
version_info = sh.python('-V')
print(f"\nPython version:\n{version_info}")

# Handle a non-zero exit code
try:
    sh.false()
except sh.ErrorReturnCode_1 as e:
    print(f"\nCaught expected error: {e.full_cmd}, Exit Code: {e.exit_code}")

# Pipe commands (similar to shell)
piped_output = sh.wc('-l', _in=sh.ls('-1'))
print(f"\nNumber of files in current directory: {piped_output.strip()}")