craftr.shell

This module is similar to the subprocess.run() interface that is available since Python 3.5 but is a bit customized so that it works better with Craftr.

class craftr.shell.safe

If this object is passed to quote(), it will not be escaped.

craftr.shell.quote(s)

Enhanced implementation for Windows systems as the original shlex.quote() function uses single-quotes on Windows which can lead to problems.

craftr.shell.format(fmt, *args, **kwargs)

Similar to str.format(), but this function will escape all arguments with the quote() function.

craftr.shell.join(cmd)

Join a list of strings to a single command.

craftr.shell.find_program(name)

Finds the program name in the PATH and returns the full absolute path to it. On Windows, this also takes the PATHEXT variable into account.

Parameters:

name – The name of the program to find.

Returns:

str – The absolute path to the program.

Raises:

• FileNotFoundError – If the program could not be found in the PATH.
• PermissionError – If a candidate for “name” was found but it is not executable.

craftr.shell.test_program(name)

Uses find_program() to find the path to “name” and returns True if it could be found, False otherwise.

exception craftr.shell.CalledProcessError(process)

This exception is raised when a process exits with a non-zero returncode and the run was to be checked for such state. The exception contains the process information.

exception craftr.shell.TimeoutExpired(process, timeout)

This exception is raised when a process did not exit after a specific timeout. If this exception was raised, the child process has already been killed.

class craftr.shell.CompletedProcess(cmd, returncode, stdout, stderr)

This class represents a completed process.

craftr.shell.run(cmd, *, stdin=None, input=None, stdout=None, stderr=None, shell=False, timeout=None, check=False, cwd=None, encoding='utf-8')

Run the process with the specified cmd. If cmd is a list of commands and shell is True, the list will be automatically converted to a properly escaped string for the shell to execute.

Note

If “shell” is True, this function will manually check if the file exists and is executable first and raise FileNotFoundError if not.

Raises:

• CalledProcessError – If check is True and the process exited with a non-zero exit-code.
• TimeoutExpired – If timeout was specified and the process did not finish before the timeout expires.
• OSError – For some OS-level error, eg. if the program could not be found.

craftr.shell.pipe(*args, merge=True, **kwargs)

Like run(), but pipes stdout and stderr to a buffer instead of directing them to the current standard out and error files. If merge is True, stderr will be merged into stdout.