Module reference

Thread-safety

All module’s objects are thread-safe with the following exception: process output iterators (see Iterating over output) are not thread-safe. You mustn’t use the same output iterator from different threads simultaneously. In other case it leads to unexpected results. You also mustn’t use with contexts simultaneously from different threads on the same Process object, because when one thread leaves with context it invalidates an output iterator from another thread which is not thread-safe.

Module objects

class psh.Sh(**default_options)

Program object factory.

__call__(program)

Creates a Program instance.

__getattribute__(program)

Creates a Program instance.

class psh.Program(program, *default_args, **default_options)

Represents an executable program.

__call__(*args, **options)

Creates a Process instance for this program.

psh.sh

Default Program object factory.

class psh.Process(program, *args, **options)

Represents a process.

A Process object doesn’t hold any resources (file descriptors, threads, etc.) until it is executed. If it’s created with _defer = True option (which is default, see Command execution) or executed with execute(), all its resources will be freed and the process will be waited when Process instance with _defer = True option will be created or execute() returns. But if you execute a command in other way by execute(wait = False) or issuing iteration over its output (see Iterating over output), you should always use with context manager to guarantee that the process will be wait()‘ed and all its resources will be freed when the code leaves the with context - not when Python’s garbage collector decide to collect the Process and Process‘ output iterator objects. You aren’t ought to do so, but its very good to do so to be sure in your program’s behaviour.

When code leaves a with context associated with a Process instance, all its output iterators became closed.

Parameters:

• _defer (bool) – if False, the process will be executed automatically in the Process constructor (see Command execution) (default is True)
• _env (dict or None) – overrides the process environment, if None does nothing (default is None)
• _iter_delimiter (str or unicode) – separator which will be used as a delimiter for process output iteration (see Iterating over output) (default is “\n”)
• _iter_raw (bool) – if True, output iteration will be on raw strings instead of unicode strings (see Iterating over output) (default is True)
• _ok_statuses (a list of integers) – a list of exit status codes that are considered as successful (see Exit codes) (default is [ 0 ])
• _on_execute (collections.Callable) – if is not None, the object is called before the process execution (default is None)
• _shell (bool) – if True, accept Process objects as command arguments by translating them into a shell script (see Working with SSH) (default is False)
• _stdin (str, unicode, STDIN, File, collections.Iterator, collections.Iterable) – specifies stdin redirection (see I/O redirection) (default is DEVNULL)
• _stdout (PIPE, File, STDOUT, STDERR) – specifies stdout redirection (see I/O redirection) (default is PIPE)
• _stderr (PIPE, File, STDOUT, STDERR) – specifies stderr redirection (see I/O redirection) (default is PIPE)
• _truncate_output (bool) – if _wait_for_output = False and _truncate_output = True, no exception is raised by execute() when there is data in stdout or stderr after the process termination (default is False)
• _wait_for_output (bool) – if _stdout = PIPE or _stderr = PIPE and _wait_for_output = True, execute() and wait() returns only when EOF is gotten on this pipes (attention: output iterators always read all data from stdout) (default is True)

__exit__(exc_type, exc_val, exc_tb)

Waits for the process termination and closes the output iterator (if created).

__iter__()

Executes the process and returns an iterator to its output.

__or__(process)

Shell-style pipelines.

__str__()

Returns the command string.

Note

Very lazy formatting.

__unicode__()

Returns the command string.

Note

Very lazy formatting.

command()

Returns command arguments as it will be executed.

execute(wait=True, check_status=True)

Executes the command.

Parameters:wait (bool) – if True, calls wait(check_status = check_status) after process execution.

kill(signal=15)

Kills the process.

Parameters:signal (int) – signal which will be used to kill the process. Returns:True if the process received the signal (which indicates that it’s still running).

pid()

Returns the process’ PID.

raw_stderr()

Returns the process’ captured raw stderr (if _stderr = PIPE).

raw_stdout()

Returns the process’ captured raw stdout (if _stdout = PIPE).

status()

Returns the process’ exit status.

stderr()

Returns the process’ captured stderr (if _stderr = PIPE).

stdout()

Returns the process’ captured stdout (if _stdout = PIPE).

wait(check_status=False, kill=None)

Waits for the process termination.

Parameters:

• check_status (bool) – if True, check the process status code (see Exit codes) and other (communication) errors and raise an exception if any error occurred.
• kill (int) – if is not None, kills the process with the kill(signal = kill) and waits for its termination.

Returns:

the process exit status

class psh.STDIN

A value to disable stdin redirection.

class psh.STDOUT

A value to disable stdout redirection or configure redirection of stderr to stdout.

class psh.STDERR

A value to disable stderr redirection or configure redirection of stdout to stderr.

class psh.PIPE

A value to configure redirection of stdout/stderr to a pipe.

class psh.File(path, append=False)

A class to configure redirection of stdin/stdout/stderr from/to a file.

psh.DEVNULL = <psh.process.File object at 0x297df10>

A class to configure redirection of stdin/stdout/stderr from/to a file.

Exceptions

exception psh.Error(error, *args, **kwargs)

A base class for all exceptions the module throws.

exception psh.ExecutionError(command, status, stdout, stderr, error=None)

Raised when a command fails to execute or returns an error exit status code.

command()

Returns the command string.

raw_stderr()

Returns the process’ captured raw stderr (if _stderr = PIPE).

raw_stdout()

Returns the process’ captured raw stdout (if _stdout = PIPE).

status()

Returns the process’s exit status.

stderr()

Returns the process’ captured stderr (if _stderr = PIPE).

stdout()

Returns the process’ captured stdout (if _stdout = PIPE).

exception psh.InvalidArgument(*args, **kwargs)

Raised on attempt to start a process with an invalid argument.

exception psh.InvalidOperation(*args, **kwargs)

Raised on attempt to process an invalid operation on a process.

exception psh.InvalidProcessState(*args, **kwargs)

Raised on attempt to process an operation on a process with an invalid state for this operation.

exception psh.ProcessOutputWasTruncated(command, status, stdout, stderr)

Raised when process terminates and its output is truncated because one of its children didn’t close the output descriptor.