JumpAvg: Fix string format
[csit.git] / resources / libraries / python / LocalExecution.py
1 # Copyright (c) 2021 Cisco and/or its affiliates.
2 # Licensed under the Apache License, Version 2.0 (the "License");
3 # you may not use this file except in compliance with the License.
4 # You may obtain a copy of the License at:
5 #
6 #     http://www.apache.org/licenses/LICENSE-2.0
7 #
8 # Unless required by applicable law or agreed to in writing, software
9 # distributed under the License is distributed on an "AS IS" BASIS,
10 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 # See the License for the specific language governing permissions and
12 # limitations under the License.
13
14 """Python library from executing command on local hosts.
15
16 Subprocess offers various functions,
17 but there are differences between Python 2 and 3.
18
19 Overall, it is more convenient to introduce this internal API
20 so call sites are shorter and unified.
21
22 This library should support commands given as Iterable, OptionString.
23
24 Commands given as a string are explicitly not supported,
25 call sites should call .split(" ") on their own risk.
26 Similarly, parts within OptionString should not be aggregates.
27 Alternatively, long string can be wrapped as 'bash -c "{str}"'.
28 Both approaches can be hacked by malicious values.
29 """
30
31 import subprocess
32
33 from robot.api import logger
34
35 from resources.libraries.python.OptionString import OptionString
36
37 __all__ = [u"run"]
38
39
40 MESSAGE_TEMPLATE = u"Command {com} ended with RC {ret} and output:\n{out}"
41
42
43 def run(command, msg=u"", check=True, log=False, console=False):
44     """Wrapper around subprocess.check_output that can tolerates nonzero RCs.
45
46     Stderr is redirected to stdout, so it is part of output
47     (but can be mingled as the two streams are buffered independently).
48     If check and rc is nonzero, RuntimeError is raised.
49     If log (and not checked failure), both rc and output are logged.
50     Logging is performed on robot logger. By default .debug(),
51     optionally .console() instead.
52     The default log message is optionally prepended by user-given string,
53     separated by ": ".
54
55     Commands given as single string are not supported, for safety reasons.
56     Invoke bash explicitly if you need its glob support for arguments.
57
58     :param command: List of commands and arguments. Split your long string.
59     :param msg: Message prefix. Argument name is short just to save space.
60     :param check: Whether to raise if return code is nonzero.
61     :param log: Whether to log results.
62     :param console: Whether use .console() instead of .debug().
63         Mainly useful when running from non-main thread.
64     :type command: Iterable or OptionString
65     :type msg: str
66     :type check: bool
67     :type log: bool
68     :type console: bool
69     :returns: rc and output
70     :rtype: 2-tuple of int and str
71     :raises RuntimeError: If check is true and return code non-zero.
72     :raises TypeError: If command is not an iterable.
73     """
74     if isinstance(command, OptionString):
75         command = command.parts
76     if not hasattr(command, u"__iter__"):
77         # Strings are indexable, but turning into iterator is not supported.
78         raise TypeError(f"Command {command!r} is not an iterable.")
79     ret_code = 0
80     output = u""
81     try:
82         output = subprocess.check_output(command, stderr=subprocess.STDOUT)
83     except subprocess.CalledProcessError as err:
84         output = err.output
85         ret_code = err.returncode
86         if check:
87             raise RuntimeError(
88                 MESSAGE_TEMPLATE.format(com=err.cmd, ret=ret_code, out=output)
89             )
90     if log:
91         message = MESSAGE_TEMPLATE.format(com=command, ret=ret_code, out=output)
92         if msg:
93             message = f"{msg}: {message}"
94         if console:
95             logger.console(message)
96         else:
97             logger.debug(message)
98     return ret_code, output