Shell commands

pshell.call(cmd, *, stdout=None, stdin=None, stderr=None, obfuscate_pwd=None, shell=True, timeout=None)

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 bash. This differes from the same parameter of subprocess.call() in several ways:

  • It is True by default instead of False
  • It sets some sane settings: errexit, nounset, pipefail
  • It is always guaranteed to be bash. subprocess.call() instead uses:
    • On RedHat and other distros, bash
    • On Ubuntu and other distros, dash (whichm among many other things, does not support set -o pipefail)
    • On Windows, CMD (completely different syntax!)

  Windows users need to make sure they somehow have the bash command in their %PATH%.

• timeout (float) – kill command if doesn’t return within timeout limit

Returns:

command exit code

Return type:

int

pshell.check_call(cmd, *, stdin=None, stdout=None, stderr=None, obfuscate_pwd=None, shell=True, timeout=None)

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

See call() for parameters description.

Returns:None Raises:CalledProcessError – if the command returns with non-zero exit status

pshell.check_output(cmd, *, stdin=None, stderr=None, obfuscate_pwd=None, shell=True, timeout=None, decode=True, encoding='utf-8', errors='replace')

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

See call() for parameters description.

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. Note how 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 str.decode(). Ignored if decode=False.

Returns:

command stdout

Return type:

str or bytes (see decode parameter)

Raises:

CalledProcessError – if the command returns with non-zero exit status

pshell.real_fh(fh)

With the io module, Python offers file-like objects which can be used to spoof a file handle. For example, this is extensively used by nosetests 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, stdout=real_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