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: CommandNotFoundError
– If scp binary not found.IOError
– if transfer fails.
-
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