Executor: Programmer friendly subprocess wrapper

Warnings

• breaking The `executor` library underwent a significant interface change from version 1.x to 2.x. In 1.x, `execute()` was the sole interface. In 2.x+, the `ExternalCommand` class was introduced for more flexible and asynchronous operations, with `execute()` becoming a wrapper around it. Code written for 1.x using only `execute()` for complex scenarios might need refactoring to leverage `ExternalCommand` in 2.x+.
  Fix: For complex or asynchronous command execution, migrate from direct `execute()` calls to using `ExternalCommand` instances, calling `start()` and `wait()` as needed. Simple synchronous calls to `execute()` remain compatible.
• gotcha The `executor` package is explicitly designed for and tested on "UNIX systems." While it might function on other platforms to some extent, full compatibility and all features (like chroot or schroot integration) are not guaranteed on non-UNIX environments (e.g., Windows).
  Fix: Verify functionality on target non-UNIX platforms or consider alternative libraries if cross-platform compatibility is critical for all features. For basic subprocess execution, it might work, but advanced features are UNIX-specific.
• gotcha By default, the `execute()` function raises an `ExternalCommandFailed` exception if the external command exits with a non-zero status code. This is a robust error-checking mechanism but can be unexpected if you intend to handle non-zero exit codes as part of normal program flow.
  Fix: If a non-zero exit code is expected and should not raise an exception, pass `check=False` to the `execute()` function (e.g., `execute('false', check=False)`). The function will then return `False` for failure and `True` for success.
• gotcha The primary `execute()` function is synchronous and will block the Python interpreter until the external command completes. For long-running commands or to achieve non-blocking execution, you must use the `ExternalCommand` class directly, which provides `start()` for asynchronous initiation and `wait()` to block only when results are needed.
  Fix: For asynchronous execution, instantiate `ExternalCommand` (e.g., `cmd = ExternalCommand(['long_running_script'])`), call `cmd.start()`, and later `cmd.wait()` to retrieve results, or poll its status.
• breaking In `executor` version 14.0, the behavior of the `command` property changed. It became valid to set `input` and `shell` options without explicitly providing a `command` argument (which was previously mandatory). Additionally, the `command` property became mutable, allowing it to be changed using normal attribute assignment or reset with `del`.
  Fix: Review code that relies on implicit `command` requirement or attempts to modify the `command` property directly. While this change generally improves flexibility, older code might rely on the prior, stricter behavior or expect `command` to be immutable after initialization.

Install

• pip install executor Install stable version

Imports

• execute
  wrong:

  import executor; executor.execute()

  correct:

  from executor import execute

  The primary function for simple command execution is usually imported directly.
• ExternalCommand

  from executor import ExternalCommand

  Used for more advanced, asynchronous, or pre-configured command execution.
• foreach

  from executor.ssh.client import foreach

  For executing commands concurrently on multiple remote hosts via SSH.

Quickstart

This quickstart demonstrates how to run basic commands, handle their success/failure, provide standard input, and capture standard output using the `execute` function.

from executor import execute
import os

# Run a simple command and check its success
print(f"'true' command success: {execute('true')}")
print(f"'false' command success (without check): {execute('false', check=False)}")

# Provide input to a command and capture its output
output = execute('tr a-z A-Z', input='Hello Python Executor\n', capture=True)
print(f"Transformed output: {output.strip()}")

# Example of running a command that fails, demonstrating default error handling
try:
    execute('non_existent_command')
except Exception as e:
    print(f"Caught expected error for non-existent command: {e}")