def valid_length(var_value, min_length=None, max_length=None, var_name=None):
r"""
The variable value is valid if it is an object (e.g. list, dictionary) whose length is within the
specified range.
Description of argument(s):
var_value The value being validated.
min_length The minimum length of the object. If not None, the length of var_value
must be greater than or equal to min_length.
max_length The maximum length of the object. If not None, the length of var_value
must be less than or equal to min_length.
"""
error_message = ""
length = len(var_value)
error_message = valid_range(length, min_length, max_length)
if error_message:
var_name = get_var_name(var_name)
error_message = "The length of the following object is not within the"
error_message += " expected range:\n"
error_message += gp.sprint_vars(min_length, max_length)
error_message += gp.sprint_var(length)
error_message += gp.sprint_varx(var_name, var_value, gp.blank())
error_message += "\n"
return process_error_message(error_message)
return process_error_message(error_message)
def valid_http_status_code(status, valid_status_codes):
r"""
Raise exception if status is not found in the valid_status_codes list.
Description of argument(s):
status An HTTP status code (e.g. 200, 400, etc.).
valid_status_codes A list of status codes that the caller
considers acceptable. If this is a null
list, then any status code is considered
acceptable. Note that for the convenience
of the caller, valid_status_codes may be
either a python list or a string which can
be evaluated to become a python list (e.g.
"[200]").
"""
if type(valid_status_codes) is not list:
valid_status_codes = eval(valid_status_codes)
if len(valid_status_codes) == 0:
return
if status in valid_status_codes:
return
message = "The HTTP status code was not valid:\n"
message += gp.sprint_vars(status, valid_status_codes)
raise ValueError(message)
def valid_range(var_value, lower=None, upper=None, *args, **kwargs):
r"""
The variable value is valid if it is within the specified range.
This function can be used with any type of operands where they can have a
greater than/less than relationship to each other (e.g. int, float, str).
Description of argument(s):
var_value The value being validated.
lower The lower end of the range. If not None,
the var_value must be greater than or
equal to lower.
upper The upper end of the range. If not None,
the var_value must be less than or equal
to upper.
"""
error_message = ""
if lower is None and upper is None:
return process_error_message(error_message)
if lower is None and var_value <= upper:
return process_error_message(error_message)
if upper is None and var_value >= lower:
return process_error_message(error_message)
if lower and upper:
if lower > upper:
var_name = get_var_name(*args, **kwargs)
error_message += "Programmer error - the lower value is greater"
error_message += " than the upper value:\n"
error_message += gp.sprint_vars(lower, upper, fmt=gp.show_type())
return process_error_message(error_message)
if lower <= var_value <= upper:
return process_error_message(error_message)
var_name = get_var_name(*args, **kwargs)
error_message += "The following variable is not within the expected"
error_message += " range:\n"
error_message += gp.sprint_varx(var_name, var_value, gp.show_type())
error_message += "\n"
error_message += "range:\n"
error_message += gp.sprint_vars(lower, upper, fmt=gp.show_type(), indent=2)
return process_error_message(error_message)
def wait_for_activation_state_change(version_id, initial_state):
r"""
Wait for the current activation state of ${version_id} to
change from the state provided by the calling function.
Description of argument(s):
version_id The version ID whose state change we are
waiting for.
initial_state The activation state we want to wait for.
"""
keyword.run_key_u("Open Connection And Log In")
retry = 0
num_read_errors = 0
read_fail_threshold = 1
while (retry < 30):
# TODO: Use retry option in run_key when available.
status, software_state = keyword.run_key("Read Properties "
+ var.SOFTWARE_VERSION_URI
+ str(version_id),
ignore=1)
if status == 'FAIL':
num_read_errors += 1
if num_read_errors > read_fail_threshold:
message = "Read errors exceeds threshold:\n " \
+ gp.sprint_vars(num_read_errors, read_fail_threshold)
BuiltIn().fail(message)
time.sleep(10)
continue
current_state = (software_state)["Activation"]
if (initial_state == current_state):
time.sleep(10)
retry += 1
num_read_errors = 0
else:
return
return
def wait_for_activation_state_change(version_id, initial_state):
r"""
Wait for the current activation state of ${version_id} to
change from the state provided by the calling function.
Description of argument(s):
version_id The version ID whose state change we are
waiting for.
initial_state The activation state we want to wait for.
"""
keyword.run_key_u("Open Connection And Log In")
retry = 0
num_read_errors = 0
read_fail_threshold = 1
while (retry < 60):
# TODO: Use retry option in run_key when available.
status, software_state = keyword.run_key("Read Properties "
+ var.SOFTWARE_VERSION_URI
+ str(version_id),
ignore=1)
if status == 'FAIL':
num_read_errors += 1
if num_read_errors > read_fail_threshold:
message = "Read errors exceeds threshold:\n " \
+ gp.sprint_vars(num_read_errors, read_fail_threshold)
BuiltIn().fail(message)
time.sleep(10)
continue
current_state = (software_state)["Activation"]
if (initial_state == current_state):
time.sleep(10)
retry += 1
num_read_errors = 0
else:
return
return
def verify_no_duplicate_image_priorities(image_purpose):
r"""
Check that there are no active images with the same purpose and priority.
Description of argument(s):
image_purpose The purpose that images must have to be
checked for priority duplicates.
"""
taken_priorities = {}
_, image_names = keyword.run_key("Get Software Objects " +
"version_type=" + image_purpose)
for image_name in image_names:
_, image = keyword.run_key("Get Host Software Property " + image_name)
if image["Activation"] != var.ACTIVE:
continue
image_priority = image["Priority"]
if image_priority in taken_priorities:
BuiltIn().fail(
"Found active images with the same priority.\n" +
gp.sprint_vars(image, taken_priorities[image_priority]))
taken_priorities[image_priority] = image
def verify_no_duplicate_image_priorities(image_purpose):
r"""
Check that there are no active images with the same purpose and priority.
Description of argument(s):
image_purpose The purpose that images must have to be
checked for priority duplicates.
"""
taken_priorities = {}
_, image_names = keyword.run_key("Get Software Objects "
+ "version_type=" + image_purpose)
for image_name in image_names:
_, image = keyword.run_key("Get Host Software Property " + image_name)
if image["Activation"] != var.ACTIVE:
continue
image_priority = image["Priority"]
if image_priority in taken_priorities:
BuiltIn().fail("Found active images with the same priority.\n"
+ gp.sprint_vars(image,
taken_priorities[image_priority]))
taken_priorities[image_priority] = image
def terminate_descendants():
r"""
Terminate descendants of the current process according to the requirements layed out in global
term_options variable.
Note: If term_options is not null, gen_exit_function() will automatically call this function.
When this function gets called, descendant processes may be running and may be printing to the same
stdout stream being used by this process. If this function writes directly to stdout, its output can
be interspersed with any output generated by descendant processes. This makes it very difficult to
interpret the output. In order solve this problem, the activity of this process will be logged to a
temporary file. After descendant processes have been terminated successfully, the temporary file
will be printed to stdout and then deleted. However, if this function should fail to complete (i.e.
get hung waiting for descendants to terminate gracefully), the temporary file will not be deleted and
can be used by the developer for debugging. If no descendant processes are found, this function will
return before creating the temporary file.
Note that a general principal being observed here is that each process is responsible for the
children it produces.
"""
message = "\n" + gp.sprint_dashes(width=120) \
+ gp.sprint_executing() + "\n"
current_process = psutil.Process()
descendants, descendant_pids, process_report = get_descendant_info(
current_process)
if not descendants:
# If there are no descendants, then we have nothing to do.
return
terminate_descendants_temp_file_path = gm.create_temp_file_path()
gp.print_vars(terminate_descendants_temp_file_path)
message += gp.sprint_varx("pgm_name", gp.pgm_name) \
+ gp.sprint_vars(term_options) \
+ process_report
# Process the termination requests:
if term_options['term_requests'] == 'children':
term_processes = current_process.children(recursive=False)
term_pids = [str(process.pid) for process in term_processes]
elif term_options['term_requests'] == 'descendants':
term_processes = descendants
term_pids = descendant_pids
else:
# Process term requests by pgm_names.
term_processes = []
for pgm_name in term_options['term_requests']['pgm_names']:
term_processes.extend(
select_processes_by_pgm_name(descendants, pgm_name))
term_pids = [str(process.pid) for process in term_processes]
message += gp.sprint_timen("Processes to be terminated:") \
+ gp.sprint_var(term_pids)
for process in term_processes:
process.terminate()
message += gp.sprint_timen("Waiting on the following pids: " +
' '.join(descendant_pids))
gm.append_file(terminate_descendants_temp_file_path, message)
psutil.wait_procs(descendants)
# Checking after the fact to see whether any descendant processes are still alive. If so, a process
# report showing this will be included in the output.
descendants, descendant_pids, process_report = get_descendant_info(
current_process)
if descendants:
message = "\n" + gp.sprint_timen("Not all of the processes terminated:") \
+ process_report
gm.append_file(terminate_descendants_temp_file_path, message)
message = gp.sprint_dashes(width=120)
gm.append_file(terminate_descendants_temp_file_path, message)
gp.print_file(terminate_descendants_temp_file_path)
os.remove(terminate_descendants_temp_file_path)
def shell_cmd(command_string,
quiet=None,
print_output=None,
show_err=1,
test_mode=0,
time_out=None,
max_attempts=1,
retry_sleep_time=5,
valid_rcs=[0],
ignore_err=None,
return_stderr=0,
fork=0,
error_regexes=None):
r"""
Run the given command string in a shell and return a tuple consisting of the shell return code and the
output.
Description of argument(s):
command_string The command string to be run in a shell (e.g. "ls /tmp").
quiet If set to 0, this function will print "Issuing: <cmd string>" to stdout.
When the quiet argument is set to None, this function will assign a
default value by searching upward in the stack for the quiet variable
value. If no such value is found, quiet is set to 0.
print_output If this is set, this function will print the stdout/stderr generated by
the shell command to stdout.
show_err If show_err is set, this function will print a standardized error report
if the shell command fails (i.e. if the shell command returns a shell_rc
that is not in valid_rcs). Note: Error text is only printed if ALL
attempts to run the command_string fail. In other words, if the command
execution is ultimately successful, initial failures are hidden.
test_mode If test_mode is set, this function will not actually run the command. If
print_output is also set, this function will print "(test_mode) Issuing:
<cmd string>" to stdout. A caller should call shell_cmd directly if they
wish to have the command string run unconditionally. They should call
the t_shell_cmd wrapper (defined below) if they wish to run the command
string only if the prevailing test_mode variable is set to 0.
time_out A time-out value expressed in seconds. If the command string has not
finished executing within <time_out> seconds, it will be halted and
counted as an error.
max_attempts The max number of attempts that should be made to run the command string.
retry_sleep_time The number of seconds to sleep between attempts.
valid_rcs A list of integers indicating which shell_rc values are not to be
considered errors.
ignore_err Ignore error means that a failure encountered by running the command
string will not be raised as a python exception. When the ignore_err
argument is set to None, this function will assign a default value by
searching upward in the stack for the ignore_err variable value. If no
such value is found, ignore_err is set to 1.
return_stderr If return_stderr is set, this function will process the stdout and stderr
streams from the shell command separately. In such a case, the tuple
returned by this function will consist of three values rather than just
two: rc, stdout, stderr.
fork Run the command string asynchronously (i.e. don't wait for status of the
child process and don't try to get stdout/stderr) and return the Popen
object created by the subprocess.popen() function. See the kill_cmd
function for details on how to process the popen object.
error_regexes A list of regular expressions to be used to identify errors in the
command output. If there is a match for any of these regular
expressions, the command will be considered a failure and the shell_rc
will be set to -1. For example, if error_regexes = ['ERROR:'] and the
command output contains 'ERROR: Unrecognized option', it will be counted
as an error even if the command returned 0. This is useful when running
commands that do not always return non-zero on error.
"""
err_msg = gv.valid_value(command_string)
if err_msg:
raise ValueError(err_msg)
# Assign default values to some of the arguments to this function.
quiet = int(gm.dft(quiet, gp.get_stack_var('quiet', 0)))
print_output = int(gm.dft(print_output, not quiet))
show_err = int(show_err)
ignore_err = int(gm.dft(ignore_err, gp.get_stack_var('ignore_err', 1)))
gp.qprint_issuing(command_string, test_mode)
if test_mode:
return (0, "", "") if return_stderr else (0, "")
# Convert a string python dictionary definition to a dictionary.
valid_rcs = fa.source_to_object(valid_rcs)
# Convert each list entry to a signed value.
valid_rcs = [gm.to_signed(x) for x in valid_rcs]
stderr = subprocess.PIPE if return_stderr else subprocess.STDOUT
# Write all output to func_out_history_buf rather than directly to stdout. This allows us to decide
# what to print after all attempts to run the command string have been made. func_out_history_buf will
# contain the complete history from the current invocation of this function.
global command_timed_out
command_timed_out = False
func_out_history_buf = ""
for attempt_num in range(1, max_attempts + 1):
sub_proc = subprocess.Popen(command_string,
preexec_fn=os.setsid,
bufsize=1,
shell=True,
universal_newlines=True,
executable='/bin/bash',
stdout=subprocess.PIPE,
stderr=stderr)
if fork:
return sub_proc
if time_out:
command_timed_out = False
# Designate a SIGALRM handling function and set alarm.
signal.signal(signal.SIGALRM, shell_cmd_timed_out)
signal.alarm(time_out)
try:
stdout_buf, stderr_buf = sub_proc.communicate()
except IOError:
command_timed_out = True
# Restore the original SIGALRM handler and clear the alarm.
signal.signal(signal.SIGALRM, original_sigalrm_handler)
signal.alarm(0)
# Output from this loop iteration is written to func_out_buf for later processing. This can include
# stdout, stderr and our own error messages.
func_out_buf = ""
if print_output:
if return_stderr:
func_out_buf += stderr_buf
func_out_buf += stdout_buf
shell_rc = sub_proc.returncode
if shell_rc in valid_rcs:
# Check output for text indicating there is an error.
if error_regexes and re.match('|'.join(error_regexes), stdout_buf):
shell_rc = -1
else:
break
err_msg = "The prior shell command failed.\n"
err_msg += gp.sprint_var(attempt_num)
err_msg += gp.sprint_vars(command_string, command_timed_out, time_out)
err_msg += gp.sprint_varx("child_pid", sub_proc.pid)
err_msg += gp.sprint_vars(shell_rc, valid_rcs, fmt=gp.hexa())
if error_regexes:
err_msg += gp.sprint_vars(error_regexes)
if not print_output:
if return_stderr:
err_msg += "stderr_buf:\n" + stderr_buf
err_msg += "stdout_buf:\n" + stdout_buf
if show_err:
func_out_buf += gp.sprint_error_report(err_msg)
if attempt_num < max_attempts:
cmd_buf = "time.sleep(" + str(retry_sleep_time) + ")"
if show_err:
func_out_buf += gp.sprint_issuing(cmd_buf)
exec(cmd_buf)
func_out_history_buf += func_out_buf
if shell_rc in valid_rcs:
gp.gp_print(func_out_buf)
else:
if show_err:
gp.gp_print(func_out_history_buf, stream='stderr')
else:
# There is no error information to show so just print output from last loop iteration.
gp.gp_print(func_out_buf)
if not ignore_err:
# If the caller has already asked to show error info, avoid repeating that in the failure message.
err_msg = "The prior shell command failed.\n" if show_err \
else err_msg
if robot_env:
BuiltIn().fail(err_msg)
else:
raise ValueError(err_msg)
return (shell_rc, stdout_buf, stderr_buf) if return_stderr \
else (shell_rc, stdout_buf)
