Proc (subprocess)

Asyncio subprocess wrapper featuring:

• Capture + live logging of stdout/stderr

• ANSI escape code cleaning for captured output: print colored output for humans, have clean output in a variable for processing, log, cache… and sending to LLMs!

• Separate start/wait methods for process control

Example usage:

# pass shell command in a string for convenience
proc = cli2.Proc('foo bar')

# or as list, better when building commands
proc = cli2.Proc('foo', 'bar')

# run in sync mode (ie. for jinja2)
proc.wait()

# OR run in async loop
await proc.waita()

# You can chain
proc = cli2.Proc('hi').wait()
proc = await cli2.Proc('hi').waita()

Note

There are also start functions, sync and async, in case you want to start the proc and wait later.

class cli2.proc.Proc(cmd, *args, quiet=False, inherit=True, timeout=None, **env)

Asynchronous subprocess manager with advanced IO handling.

args

Full command arguments list used to launch the process

rc

Return Code: process exit code (available after process completes)

out

Combined cleaned output with ANSI escape codes removed.

out_ansi

Combined stdout/stderr output with ANSI codes preserved.

stdout

Cleaned stdout output with ANSI escape codes removed.

stderr

Cleaned stdout output with ANSI escape codes removed.

stdout_ansi

Stdout output with ANSI escape codes preserved.

stderr_ansi

Stderr output with ANSI escape codes preserved.

clone()

Create a new unstarted Proc instance with identical configuration.

Returns:

New Proc instance ready for execution

property cmd

Get/set the command as a shell-joinable string.

Getter:

Returns shell-escaped command string

Setter:

Parses and updates internal args list

Type:

str

start()

Start the subprocess synchronously without waiting for output.

async starta()

Launch the subprocess asynchronously.

Returns:

Self reference for method chaining

Raises:

RuntimeError – If process is already started

wait()

Wait for process completion synchronously with timeout handling. Collects output streams after waiting.

async waita()

Wait for process completion with timeout handling.

Terminates process if timeout occurs. Gathers all output streams.

Returns:

Self reference for method chaining