blob: c68555b88a22e71ea9938ffff39baf2c63a9358b [file] [log] [blame]
#!/usr/bin/env python
r"""
This module provides valuable argument processing functions like
gen_get_options and sprint_args.
"""
import os
import gen_print as gp
exit_on_error = False
def set_exit_on_error(value):
r"""
Set the exit_on_error value to either True or False.
If exit_on_error is set, validation functions like valid_value will exit
the program on error instead of returning False.
Description of argument(s):
value Value to set global exit_on_error to.
"""
global exit_on_error
exit_on_error = value
def get_var_name(var_name):
r"""
If var_name has a value, simply return it. Otherwise, get the variable
name of the first argument used to call the validation function (e.g.
valid_value, valid_integer, etc.) and return it.
This function is designed solely for use by other functions in this file.
Example:
A programmer codes this:
valid_value(last_name)
Which results in the following call stack:
valid_value(last_name)
-> svalid_value(var_value...)
-> get_var_name(var_name)
In this example, this function will return "last_name".
Example:
err_msg = svalid_value(last_name, var_name="some_other_name")
Which results in the following call stack:
svalid_value(var_value, var_name="some_other_name")
-> get_var_name(var_name)
In this example, this function will return "some_other_name".
Description of argument(s):
var_name The name of the variable.
"""
if var_name != "":
return var_name
# Calculate stack_frame_ix. The validation functions in this file come
# in pairs. There is an "s" version of each validation function (e.g.
# svalid_value) whose job is to return an error message string. Then
# there is a wrapper function (e.g. valid_value) that will call the "s"
# version and print the result if there is an error. See examples 1 and 2
# above for illustration. This function must be cognizant of both
# scenarios to accurately determine the name of the variable being
# validated. Where the "s" function is being called directly, the
# stack_frame_ix should be set to 3. Where the wrapper function is being
# called, the stack_frame_ix should be incremented to 4.
stack_frame_ix = 3
parent_func_name = gp.sprint_func_name(2)
grandparent_func_name = gp.sprint_func_name(3)
if parent_func_name == "s" + grandparent_func_name:
stack_frame_ix += 1
var_name = gp.get_arg_name(0, 1, stack_frame_ix)
return var_name
def process_error_message(error_message):
r"""
Process the error_message as follows:
- If the error_message is blank, return True.
- If the error_message contains a value:
- Print the error_message as part of a full error report.
- If global exit_on_error is set, then exit the program with a return
code of 1.
- If exit_on_error is not set, return False.
This function is designed solely for use by wrapper functions in this file
(e.g. "valid_value").
Description of argument(s):
error_message An error message.
"""
if error_message == "":
return True
gp.print_error_report(error_message)
if exit_on_error:
exit(0)
return False
def svalid_value(var_value,
invalid_values=[],
valid_values=[],
var_name=""):
r"""
Return an empty string if var_value is a valid value. Otherwise, return
an error string.
Description of arguments:
var_value The value being validated.
invalid_values A list of invalid values. If var_value is
equal to any of these, it is invalid.
Note that if you specify anything for
invalid_values (below), the valid_values
list is not even processed. If you
specify nothing for both invalid_values
and valid_values, invalid_values will be
set to a default value of [""].
valid_values A list of valid values. var_value must be
equal to one of these values to be
considered valid.
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
success_message = ""
error_message = ""
# Validate this function's arguments.
len_valid_values = len(valid_values)
len_invalid_values = len(invalid_values)
if len_valid_values > 0 and len_invalid_values > 0:
error_message += "Programmer error - You must provide either an" +\
" invalid_values list or a valid_values" +\
" list but NOT both.\n" +\
gp.sprint_var(invalid_values) +\
gp.sprint_var(valid_values)
return error_message
show_blanks = 1
if len_valid_values > 0:
# Processing the valid_values list.
if var_value in valid_values:
return success_message
error_message += "The following variable has an invalid" +\
" value:\n" +\
gp.sprint_varx(get_var_name(var_name), var_value,
show_blanks) +\
"\nIt must be one of the following values:\n" +\
gp.sprint_varx("valid_values", valid_values,
show_blanks)
return error_message
if len_invalid_values == 0:
# Assign default value.
invalid_values = [""]
# Assertion: We have an invalid_values list. Processing it now.
if var_value not in invalid_values:
return success_message
error_message += "The following variable has an invalid value:\n" +\
gp.sprint_varx(get_var_name(var_name), var_value,
show_blanks) +\
"\nIt must NOT be one of the following values:\n" +\
gp.sprint_varx("invalid_values", invalid_values,
show_blanks)
return error_message
def valid_value(var_value,
invalid_values=[],
valid_values=[],
var_name=""):
r"""
Return True if var_value is valid. Otherwise, print an error message and
either return False or exit(1) depending on the value of exit_on_error.
Description of arguments:
(See description of arguments for svalid_value (above)).
"""
error_message = svalid_value(var_value, invalid_values, valid_values,
var_name)
return process_error_message(error_message)
def svalid_integer(var_value,
var_name=""):
r"""
Return an empty string if var_value is a valid integer. Otherwise, return
an error string.
Description of arguments:
var_value The value being validated.
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
success_message = ""
error_message = ""
try:
if isinstance(int(str(var_value), 0), int):
return success_message
except ValueError:
pass
# If we get to this point, the validation has failed.
show_blanks = 1
error_message +=\
"Invalid integer value:\n" +\
gp.sprint_varx(get_var_name(var_name), var_value, show_blanks)
return error_message
def valid_integer(var_value,
var_name=""):
r"""
Return True if var_value is a valid integer. Otherwise, print an error
message and either return False or exit(1) depending on the value of
exit_on_error.
Description of arguments:
(See description of arguments for svalid_integer (above)).
"""
error_message = svalid_integer(var_value, var_name)
return process_error_message(error_message)
def svalid_dir_path(var_value,
var_name=""):
r"""
Return an empty string if var_value is a valid directory path. Otherwise,
return an error string.
Description of arguments:
var_value The value being validated.
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
error_message = ""
if not os.path.isdir(str(var_value)):
error_message += "The following directory does not exist:\n" +\
gp.sprint_varx(get_var_name(var_name), var_value)
return error_message
def valid_dir_path(var_value,
var_name=""):
r"""
Return True if var_value is a valid directory path. Otherwise, print an
error message and either return False or exit(1) depending on the value of
exit_on_error.
Valid means that the directory path exists.
Description of arguments:
(See description of arguments for svalid_dir_path (above)).
"""
error_message = svalid_dir_path(var_value, var_name)
return process_error_message(error_message)
def svalid_file_path(var_value,
var_name=""):
r"""
Return an empty string if var_value is a valid file path. Otherwise,
return an error string.
Description of arguments:
var_value The value being validated.
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
error_message = ""
if not os.path.isfile(str(var_value)):
error_message += "Invalid file (does not exist):\n" +\
gp.sprint_varx(get_var_name(var_name), var_value)
return error_message
def valid_file_path(var_value,
var_name=""):
r"""
Return True if var_value is a valid file path. Otherwise, print an error
message and either return False or exit(1) depending on the value of
exit_on_error.
Valid means that the file exists.
Description of arguments:
(See description of arguments for svalid_file_path (above)).
"""
error_message = svalid_file_path(var_value, var_name)
return process_error_message(error_message)
def svalid_path(var_value,
var_name=""):
r"""
Return an empty string if var_value is either a valid file path or
directory path. Otherwise, return an error string.
Description of arguments:
var_value The value being validated.
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
error_message = ""
if not (os.path.isfile(str(var_value)) or os.path.isdir(str(var_value))):
error_message = "Invalid path (file or directory does not exist):\n" +\
gp.sprint_varx(get_var_name(var_name), var_value)
return error_message
def valid_path(var_value,
var_name=""):
r"""
Return True if var_value is a valid file path. Otherwise, print an error
message and either return False or exit(1) depending on the value of
exit_on_error.
Valid means that the file exists.
Description of arguments:
(See description of arguments for svalid_path (above)).
"""
error_message = svalid_path(var_value, var_name)
return process_error_message(error_message)
def svalid_range(var_value,
valid_range=[],
var_name=""):
r"""
Return an empty string if var_value is within the range. Otherwise,
return an error string.
Description of arguments:
var_value The value being validated. This value
must be an integer.
valid_range A list comprised of one or two elements
which are the lower and upper ends of a
range. These values must be integers
except where noted. Valid specifications
may be of the following forms: [lower,
upper], [lower] or [None, upper].
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
error_message = ""
# Validate this function's parms:
# First, ensure that the value is an integer.
error_message = svalid_integer(var_value, var_name)
if not error_message == "":
return error_message
var_value = int(var_value)
len_valid_range = len(valid_range)
if len_valid_range == 0 or len_valid_range > 2:
error_message += "Programmer error - For the valid_range parameter," +\
" you must provide a list consisting of one or two" +\
" elements.\n" +\
gp.sprint_var(valid_range)
return error_message
if len_valid_range == 1 or valid_range[0] is not None:
# Make sure lower valid_range value is an integer.
error_message = svalid_integer(valid_range[0], "valid_range[0]")
if not error_message == "":
error_message = "Programmer error:\n" + error_message
return error_message
if valid_range[0] is not None:
valid_range[0] = int(valid_range[0])
if len_valid_range == 2:
# Make sure upper valid_range value is an integer.
error_message = svalid_integer(valid_range[1], "valid_range[1]")
if not error_message == "":
error_message = "Programmer error:\n" + error_message
return error_message
valid_range[1] = int(valid_range[1])
if valid_range[0] is not None and valid_range[0] > valid_range[1]:
error_message = "Programmer error - In the following range, the" +\
" lower limit is greater than the upper" +\
" limit:\n" + gp.sprint_varx("valid_range",
valid_range)
return error_message
if len_valid_range == 1:
if var_value < valid_range[0]:
error_message += "The following variable is not within the" +\
" expected range:\n" +\
gp.sprint_varx(get_var_name(var_name),
var_value) +\
gp.sprint_varx("valid_range",
str(valid_range[0]) + "..")
return error_message
return error_message
if valid_range[0] is None:
if var_value > valid_range[1]:
error_message += "The following variable is not within the" +\
" expected range:\n" +\
gp.sprint_varx(get_var_name(var_name),
var_value) +\
gp.sprint_varx("valid_range",
".." + str(valid_range[1]))
return error_message
if var_value < valid_range[0] or var_value > valid_range[1]:
error_message += "The following variable is not within the expected" +\
" range:\n" +\
gp.sprint_varx(get_var_name(var_name), var_value) +\
gp.sprint_varx("valid_range",
str(valid_range[0]) + ".."
+ str(valid_range[1]))
return error_message
return error_message
def valid_range(var_value,
valid_range=[],
var_name=""):
r"""
Return True if var_value is within range. Otherwise, print an error
message and either return False or exit(1) depending on the value of
exit_on_error.
Description of arguments:
(See description of arguments for svalid_range (above)).
"""
error_message = svalid_range(var_value, valid_range, var_name)
return process_error_message(error_message)
def svalid_list(var_value,
valid_values=[],
var_name=""):
r"""
Return an empty string if var_value is a valid list. Otherwise, return an
error string.
Description of arguments:
var_value The value (i.e. list) being validated.
valid_values A list of valid values. Each element in
the var_value list must be equal to one of
these values to be considered valid.
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
error_message = ""
if len(var_value) == 0:
show_blanks = 1
error_message += "The \"" + get_var_name(var_name)
error_message += "\" list is empty and is therefore invalid:\n"
return error_message
found_error = 0
display_var_value = list(var_value)
for ix in range(0, len(var_value)):
if var_value[ix] not in valid_values:
found_error = 1
display_var_value[ix] = var_value[ix] + "*"
if found_error:
show_blanks = 1
error_message += "The list entries marked with \"*\" are not valid:\n"
error_message += gp.sprint_varx(get_var_name(var_name),
display_var_value, show_blanks)
error_message += gp.sprint_var(valid_values)
return error_message
return ""
def valid_list(var_value,
valid_values=[],
var_name=""):
r"""
Return True if var_value is a valid list. Otherwise, print an error
message and either return False or exit(1) depending on the value of
exit_on_error.
Description of arguments:
(See description of arguments for svalid_list (above)).
"""
error_message = svalid_list(var_value, valid_values, var_name)
return process_error_message(error_message)
def svalid_dict(var_value,
required_keys=[],
var_name=""):
r"""
Return an empty string if var_value is a valid dictionary. Otherwise,
return an error string.
Description of arguments:
var_value The value (i.e. dictionary) being
validated.
required_keys A list of keys which must be found in the
dictionary for it to be considered valid.
var_name The name of the variable whose value is
passed in var_value. This parameter is
normally unnecessary as this function can
figure out the var_name. This is provided
for Robot callers. In this scenario, we
are unable to get the variable name
ourselves.
"""
error_message = ""
keys_missing = list(set(required_keys) - set(var_value.keys()))
if len(keys_missing) > 0:
show_blanks = 1
var_name = get_var_name(var_name)
error_message = "The following key fields are missing from "
error_message += var_name + ":\n"
error_message += gp.sprint_var(keys_missing)
error_message += gp.sprint_varx(var_name, var_value, show_blanks)
return error_message
return ""
def valid_dict(var_value,
required_keys=[],
var_name=""):
r"""
Return True if var_value is a valid dictionary. Otherwise, print an error
message and either return False or exit(1) depending on the value of
exit_on_error.
Description of arguments:
(See description of arguments for svalid_list (above)).
"""
error_message = svalid_dict(var_value, required_keys, var_name)
return process_error_message(error_message)