Shell commands

Run another program in a subprocess and wait for it to terminate.

Parameters:

cmd – Command to be executed (str or list). If shell=True, it must be a str.
stdout – standard output file handle. Omit for sys.stdout. Unlike the same parameter for subprocess.call(), which must be backed by a OS-level file descriptor, this can be a pseudo-stream like e.g. io.StringIO.
stdin – standard input file handle. Omit for no input.
stderr – standard error file handle. Omit for sys.stderr. Unlike the same parameter for subprocess.call(), which must be backed by a OS-level file descriptor, this can be a pseudo-stream like e.g. io.StringIO.
obfuscate_pwd (str) – if set, search for the target password and replace it with XXXX before logging it.
shell (bool) –
Invoke inside the shell. This differes from the same parameter of subprocess.call() in several ways:
- It is True by default instead of False
- In Linux and MacOSX, it sets some sane settings: errexit, nounset, pipefail
- In Linux and MacOSX, it is always guaranteed to be bash. This differs from subprocess.call(), which on Ubuntu will invoke dash and RedHat will invoke bash. On Windows it is CMD.
timeout (float) – kill command if doesn’t return within timeout limit

Returns:

command exit code

Return type:

int

Run another program in a subprocess and wait for it to terminate; raise exception in case of non-zero exit code.

See call() for parameters documentation.

Returns:: None
Raises:: CalledProcessError – if the command returns a non-zero exit code

pshell.check_output(cmd: str | list[str], *, stdin: IO | None = None, stderr: IO | None = None, obfuscate_pwd: str | None = None, shell: bool = True, timeout: float | None = None, decode: Literal[True] = True, encoding: str = 'utf-8', errors: str = 'replace') → str

pshell.check_output(cmd: str | list[str], *, stdin: IO | None = None, stderr: IO | None = None, obfuscate_pwd: str | None = None, shell: bool = True, timeout: float | None = None, decode: Literal[False], encoding: str = 'utf-8', errors: str = 'replace') → bytes

Run another program in a subprocess and wait for it to terminate; return its stdout. Raise exception in case of non-zero exit code.

See call() for parameters documentation.

Parameters:

decode (bool) – If True, decode the raw output to UTF-8 and return a str object. If False, return the raw bytes object. The default is to decode to UTF-8. This differs from subprocess.check_output(), which always returns the raw output.
encoding (str) – Encoding of the raw bytes output. Ignored if decode=False.
errors (str) – ‘replace’, ‘ignore’, or ‘strict’. See bytes.decode(). Ignored if decode=False. Note that the default value is replace, whereas the default in bytes.decode() is strict.

Returns:

command stdout

Return type:

str or bytes (see decode parameter)

Raises:

CalledProcessError – if the command returns a non-zero exit code

pshell.real_fh(fh: IO | None) → Any

The io module offers file-like objects which can be used to spoof a file handle. Among other things, they are extensively used by nosetests and py.test to capture stdout/stderr.

In most cases, this is transparent; however there are exceptions, like the subprocess module, which require a file handle with a real file descriptor underlying it - that is, an object which defines the fileno() method.

This context manager transparently detects these cases and automatically converts pseudo file handlers from the io module into real POSIX-based file handles.

Parameters:

fh –

Any of:

A file handle opened for write and backed by a POSIX file descriptor, e.g. as returned by open() or the default value of sys.stdout or sys.stderr.
A pseudo file handle such as io.StringIO, io.BytesIO, or the stub used by nosetests to mock sys.stdout and sys.stderr.
None (default for most subprocess functions)

Usage:

buf = io.StringIO()
with real_fh(buf) as real_buf:
    subprocess.check_call(cmd, stderr=real_buf)

All pshell functions that wrap around subprocess internally use this context manager. You don’t need to use it explicitly:

buf = io.StringIO()
pshell.check_call(cmd, stderr=buf)

exception pshell.CalledProcessError(returncode, cmd, output=None, stderr=None)

Raised when run() is called with check=True and the process returns a non-zero exit status.

Attributes:: cmd, returncode, stdout, stderr, output

exception pshell.TimeoutExpired(cmd, timeout, output=None, stderr=None)

This exception is raised when the timeout expires while waiting for a child process.

Attributes:: cmd, output, stdout, stderr, timeout