cmdcapture 1.0.0

A Python library for capturing output from terminal commands with advanced features

Command Capture Library

A comprehensive Python library for capturing output from terminal commands with advanced features including timeouts, real-time output, parallel execution, and more.

Features

• 🚀 Simple and intuitive API - Easy to use for basic command execution
• ⏱️ Timeout support - Prevent commands from running indefinitely
• 🔄 Real-time output - Stream command output as it happens
• 🏃 Parallel execution - Run multiple commands simultaneously
• 🌍 Environment control - Set custom environment variables
• 📁 Working directory - Execute commands in specific directories
• 💾 Input/Output handling - Send input to commands and capture all output
• 🛡️ Error handling - Comprehensive error handling with custom exceptions
• 📊 Detailed results - Rich result objects with execution metadata
• 🖥️ Cross-platform - Works on Linux, macOS, and Windows
• 📦 Zero dependencies - Uses only Python standard library

Installation

From source

git clone <repository-url>
cd CommandCapture 
pip install .

For development

pip install -e ".[dev]"

Quick Start

from cmdcapture import CommandCapture

# Create a CommandCapture instance
capture = CommandCapture()

# Execute a simple command
result = capture.run("echo 'Hello, World!'")
print(result.stdout)  # Hello, World!
print(result.success)  # True
print(result.return_code)  # 0

Basic Usage

Simple Command Execution

from cmdcapture import CommandCapture

capture = CommandCapture()
result = capture.run("ls -la")

if result.success:
    print("Command succeeded!")
    print(result.stdout)
else:
    print(f"Command failed with return code: {result.return_code}")
    print(result.stderr)

Error Handling

from cmdcapture import CommandCapture, CommandError

capture = CommandCapture()
try:
    # Use check=True to raise exception on command failure
    result = capture.run("ls /nonexistent", check=True)
except CommandError as e:
    print(f"Command failed: {e}")
    print(f"Return code: {e.return_code}")

Timeout Support

from cmdcapture import CommandCapture, TimeoutError

capture = CommandCapture()
try:
    result = capture.run("sleep 10", timeout=5.0)
except TimeoutError as e:
    print(f"Command timed out after {e.timeout} seconds")

Advanced Features

Real-time Output

def progress_callback(line):
    print(f"[OUTPUT] {line}")

result = capture.run("ping -c 3 google.com", progress_callback=progress_callback)

Environment Variables

result = capture.run("echo $MY_VAR", env={"MY_VAR": "Hello World"})
print(result.stdout)  # Hello World

Working Directory

result = capture.run("pwd", cwd="/tmp")
print(result.stdout)  # /tmp (or equivalent)

Input Data

result = capture.run("grep 'pattern'", input_data="line with pattern\nother line")
print(result.stdout)  # line with pattern

Multiple Commands

# Sequential execution
commands = ["echo 'first'", "echo 'second'", "echo 'third'"]
results = capture.run_multiple(commands)

# Parallel execution
results = capture.run_multiple(commands, parallel=True)

Command Availability

if capture.is_available("git"):
    result = capture.run("git --version")
    print(result.stdout)
else:
    print("Git is not available")

Command Line Interface

The library also provides a CLI interface:

# Basic usage
cmdcapture "echo 'Hello, World!'"

# With JSON output
cmdcapture "ls -la" --json

# With timeout
cmdcapture "sleep 5" --timeout 2

# With working directory
cmdcapture "pwd" --cwd /tmp

# Send input
cmdcapture "cat" --input "Hello, World!"

API Reference

CommandCapture

Main class for executing commands.

Constructor

CommandCapture(
    default_timeout: Optional[float] = None,
    default_cwd: Optional[Union[str, Path]] = None,
    default_env: Optional[Dict[str, str]] = None
)

Methods

run(command, **kwargs) -> CaptureResult

Execute a command and return results.

Parameters:

• command: Command to execute (string or list)
• timeout: Timeout in seconds
• cwd: Working directory
• env: Environment variables
• check: Raise exception on command failure
• shell: Execute through shell (default: True)
• input_data: Data to send to stdin
• progress_callback: Function to call with real-time output

run_multiple(commands, parallel=False, **kwargs) -> List[CaptureResult]

Execute multiple commands.

is_available(command) -> bool

Check if a command is available in the system PATH.

CaptureResult

Result object containing command execution details.

Attributes:

• command: The executed command
• return_code: Exit code
• stdout: Standard output
• stderr: Standard error output
• execution_time: Execution time in seconds
• success: Boolean indicating success (return_code == 0)
• pid: Process ID

Exceptions

CommandError: Raised when command execution fails (when check=True) TimeoutError: Raised when command execution times out

Testing

Run the test suite:

python test_cmdcapture.py

Run the examples:

python example.py

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.