labm8.system

Utilies for grokking the underlying system.

Variables:
  • HOSTNAME (str) System hostname.
  • USERNAME (str) Username.
  • UID (int) User ID.
  • PID (int) Process ID.
exception labm8.system.CommandNotFoundError

Error thrown a system command is not found.

exception labm8.system.Error
exception labm8.system.ScpError(stdout, stderr)

Error thrown if scp file transfer fails.

class labm8.system.Subprocess(cmd, shell=False, stdout=-1, stderr=-1, decode_out=True)

Subprocess abstraction.

Wrapper around subprocess.Popen() which provides the ability to force a timeout after a number of seconds have elapsed.

run(timeout=-1)

Run the subprocess.

Parameters:timeout (optional) – the given number of seconds.
Raises:SubprocessError If subprocess has not completed after “timeout” – seconds.
exception labm8.system.SubprocessError

Error thrown if a subprocess fails.

labm8.system.echo(*args, **kwargs)

Write a message to a file.

Parameters:A list of arguments which make up the message. The last argument (args) – is the path to the file to write to.
labm8.system.is_linux()
labm8.system.is_mac()
labm8.system.is_windows()
labm8.system.isprocess(pid, error=False)

Check that a process is running.

Parameters:pid (int) – Process ID to check.
Returns:True if the process is running, else false.
labm8.system.run(command, num_retries=1, timeout=-1, **kwargs)

Run a command with optional timeout and retries.

Provides a convenience method for executing a subprocess with additional error handling.

Parameters:
  • command (list of str) – The command to execute.
  • num_retries (int, optional) – If the subprocess fails, the number of attempts to execute it before failing.
  • timeout (float, optional) – If positive, the number of seconds to wait for subprocess completion before failing.
  • **kwargs – Additional args to pass to Subprocess.__init__()
Returns:

Where the variables represent (exit status, stdout, stderr).

Return type:

Tuple of (int, str, str)

Raises:

SubprocessError – If the command fails after the given number of retries.

labm8.system.scp(host, src, dst, user=None, path=None)

Copy a file or directory from a remote location.

A thin wrapper around the scp (1) system command.

If the destination already exists, this will attempt to overwrite it.

Parameters:
  • host (str) – name of the host
  • src (str) – path to the source file or directory.
  • dst (str) – path to the destination file or directory.
  • user (str, optional) – Alternative username for remote access. If not provided, the default scp behaviour is used.
  • path (str, optional) – Directory containing scp command. If not provided, attempt to locate scp using which().
Raises:
labm8.system.sed(match, replacement, path, modifiers='')

Perform sed text substitution.

labm8.system.which(program, path=None)

Returns the full path of shell commands.

Replicates the functionality of system which (1) command. Looks for the named program in the directories indicated in the $PATH environment variable, and returns the full path if found.

Examples

>>> system.which("ls")
"/bin/ls"
>>> system.which("/bin/ls")
"/bin/ls"
>>> system.which("not-a-real-command")
None
>>> system.which("ls", path=("/usr/bin", "/bin"))
"/bin/ls"
Parameters:
  • program (str) – The name of the program to look for. Can be an absolute path.
  • path (sequence of str, optional) – A list of directories to look for the pgoram in. Default value is system $PATH.
Returns:

Full path to program if found, else None.

Return type:

str