blob: a422e0f57f1ba900f9285ae98ae525398927f8ce [file] [log] [blame]
#!/usr/bin/env python3
r"""
This module provides validation functions like valid_value(), valid_integer(), etc.
"""
import datetime
import os
import func_args as fa
import gen_cmd as gc
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 is not None, simply return its value. Otherwise, get the variable name of the first argument
used to call the validation function (e.g. valid, 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)
-> get_var_name(var_name)
In this example, this function will return "last_name".
Example:
err_msg = valid_value(last_name, var_name="some_other_name")
Which results in the following call stack:
valid_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.
"""
return var_name or gp.get_arg_name(0, 1, stack_frame_ix=3)
def process_error_message(error_message):
r"""
Process the error_message in the manner described below.
This function is designed solely for use by other functions in this file.
NOTE: A blank error_message means that there is no error.
For the following explanations, assume the caller of this function is a function with the following
definition:
valid_value(var_value, valid_values=[], invalid_values=[], var_name=None):
If the user of valid_value() is assigning the valid_value() return value to a variable,
process_error_message() will simply return the error_message. This mode of usage is illustrated by the
following example:
error_message = valid_value(var1)
This mode is useful for callers who wish to validate a variable and then decide for themselves what to do
with the error_message (e.g. raise(error_message), BuiltIn().fail(error_message), etc.).
If the user of valid_value() is NOT assigning the valid_value() return value to a variable,
process_error_message() will behave as follows.
First, if error_message is non-blank, it will be printed to stderr via a call to
gp.print_error_report(error_message).
If exit_on_error is set:
- If the error_message is blank, simply return.
- If the error_message is non-blank, exit the program with a return code of 1.
If exit_on_error is NOT set:
- If the error_message is blank, return True.
- If the error_message is non-blank, return False.
Description of argument(s):
error_message An error message.
"""
# Determine whether the caller's caller is assigning the result to a variable.
l_value = gp.get_arg_name(None, -1, stack_frame_ix=3)
if l_value:
return error_message
if error_message == "":
if exit_on_error:
return
return True
gp.print_error_report(error_message, stack_frame_ix=4)
if exit_on_error:
exit(1)
return False
# Note to programmers: All of the validation functions in this module should follow the same basic template:
# def valid_value(var_value, var1, var2, varn, var_name=None):
#
# error_message = ""
# if not valid:
# var_name = get_var_name(var_name)
# error_message += "The following variable is invalid because...:\n"
# error_message += gp.sprint_varx(var_name, var_value, gp.blank())
#
# return process_error_message(error_message)
# The docstring header and footer will be added to each validation function's existing docstring.
docstring_header = r"""
Determine whether var_value is valid, construct an error_message and call
process_error_message(error_message).
See the process_error_message() function defined in this module for a description of how error messages
are processed.
"""
additional_args_docstring_footer = r"""
var_name The name of the variable whose value is passed in var_value. For the
general case, this argument is unnecessary as this function can figure
out the var_name. This is provided for Robot callers in which case, this
function lacks the ability to determine the variable name.
"""
def valid_type(var_value, required_type, var_name=None):
r"""
The variable value is valid if it is of the required type.
Examples:
valid_type(var1, int)
valid_type(var1, (list, dict))
Description of argument(s):
var_value The value being validated.
required_type A type or a tuple of types (e.g. str, int, etc.).
"""
error_message = ""
if type(required_type) is tuple:
if type(var_value) in required_type:
return process_error_message(error_message)
else:
if type(var_value) is required_type:
return process_error_message(error_message)
# If we get to this point, the validation has failed.
var_name = get_var_name(var_name)
error_message += "Invalid variable type:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
error_message += "\n"
error_message += gp.sprint_var(required_type)
return process_error_message(error_message)
def valid_value(var_value, valid_values=[], invalid_values=[], var_name=None):
r"""
The variable value is valid if it is either contained in the valid_values list or if it is NOT contained
in the invalid_values list. If the caller specifies nothing for either of these 2 arguments,
invalid_values will be initialized to ['', None]. This is a good way to fail on variables which contain
blank values.
It is illegal to specify both valid_values and invalid values.
Example:
var1 = ''
valid_value(var1)
This code would fail because var1 is blank and the default value for invalid_values is ['', None].
Example:
var1 = 'yes'
valid_value(var1, valid_values=['yes', 'true'])
This code would pass.
Description of argument(s):
var_value The value being validated.
valid_values A list of valid values. The variable value must be equal to one of these
values to be considered valid.
invalid_values A list of invalid values. If the variable value is equal to any of
these, it is considered invalid.
"""
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"
error_message += " invalid_values list or a valid_values"
error_message += " list but NOT both:\n"
error_message += gp.sprint_var(invalid_values)
error_message += gp.sprint_var(valid_values)
return process_error_message(error_message)
error_message = valid_type(valid_values, list, var_name="valid_values")
if error_message:
return process_error_message(error_message)
error_message = valid_type(invalid_values, list, var_name="invalid_values")
if error_message:
return process_error_message(error_message)
if len_valid_values > 0:
# Processing the valid_values list.
if var_value in valid_values:
return process_error_message(error_message)
var_name = get_var_name(var_name)
error_message += "Invalid variable value:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.verbose() | gp.show_type()
)
error_message += "\n"
error_message += "It must be one of the following values:\n"
error_message += "\n"
error_message += gp.sprint_var(
valid_values, gp.blank() | gp.show_type()
)
return process_error_message(error_message)
if len_invalid_values == 0:
# Assign default value.
invalid_values = ["", None]
# Assertion: We have an invalid_values list. Processing it now.
if var_value not in invalid_values:
return process_error_message(error_message)
var_name = get_var_name(var_name)
error_message += "Invalid variable value:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.verbose() | gp.show_type()
)
error_message += "\n"
error_message += "It must NOT be any of the following values:\n"
error_message += "\n"
error_message += gp.sprint_var(invalid_values, gp.blank() | gp.show_type())
return process_error_message(error_message)
def valid_range(var_value, lower=None, upper=None, var_name=None):
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 is not None and upper is not None:
if lower > upper:
var_name = get_var_name(var_name)
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(var_name)
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 valid_integer(var_value, lower=None, upper=None, var_name=None):
r"""
The variable value is valid if it is an integer or can be interpreted as an integer (e.g. 7, "7", etc.).
This function also calls valid_range to make sure the integer value is within the specified range (if
any).
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 = ""
var_name = get_var_name(var_name)
try:
var_value = int(str(var_value), 0)
except ValueError:
error_message += "Invalid integer value:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
return process_error_message(error_message)
# Check the range (if any).
if lower:
lower = int(str(lower), 0)
if upper:
upper = int(str(upper), 0)
error_message = valid_range(var_value, lower, upper, var_name=var_name)
return process_error_message(error_message)
def valid_float(var_value, lower=None, upper=None, var_name=None):
r"""
The variable value is valid if it is a floating point value or can be interpreted as a floating point
value (e.g. 7.5, "7.5", etc.).
This function also calls valid_range to make sure the float value is within the specified range (if any).
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 = ""
var_name = get_var_name(var_name)
try:
var_value = float(str(var_value))
except ValueError:
error_message += "Invalid float value:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
return process_error_message(error_message)
# Check the range (if any).
if lower:
lower = float(str(lower))
if upper:
upper = float(str(upper))
error_message = valid_range(var_value, lower, upper, var_name=var_name)
return process_error_message(error_message)
def valid_date_time(var_value, var_name=None):
r"""
The variable value is valid if it can be interpreted as a date/time (e.g. "14:49:49.981", "tomorrow",
etc.) by the linux date command.
Description of argument(s):
var_value The value being validated.
"""
error_message = ""
rc, out_buf = gc.shell_cmd(
"date -d '" + str(var_value) + "'", quiet=1, show_err=0, ignore_err=1
)
if rc:
var_name = get_var_name(var_name)
error_message += "Invalid date/time value:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
return process_error_message(error_message)
return process_error_message(error_message)
def valid_dir_path(var_value, var_name=None):
r"""
The variable value is valid if it contains the path of an existing directory.
Description of argument(s):
var_value The value being validated.
"""
error_message = ""
if not os.path.isdir(str(var_value)):
var_name = get_var_name(var_name)
error_message += "The following directory does not exist:\n"
error_message += gp.sprint_varx(var_name, var_value, gp.blank())
return process_error_message(error_message)
def valid_file_path(var_value, var_name=None):
r"""
The variable value is valid if it contains the path of an existing file.
Description of argument(s):
var_value The value being validated.
"""
error_message = ""
if not os.path.isfile(str(var_value)):
var_name = get_var_name(var_name)
error_message += "The following file does not exist:\n"
error_message += gp.sprint_varx(var_name, var_value, gp.blank())
return process_error_message(error_message)
def valid_path(var_value, var_name=None):
r"""
The variable value is valid if it contains the path of an existing file or directory.
Description of argument(s):
var_value The value being validated.
"""
error_message = ""
if not (os.path.isfile(str(var_value)) or os.path.isdir(str(var_value))):
var_name = get_var_name(var_name)
error_message += "Invalid path (file or directory does not exist):\n"
error_message += gp.sprint_varx(var_name, var_value, gp.blank())
return process_error_message(error_message)
def valid_list(
var_value,
valid_values=[],
invalid_values=[],
required_values=[],
fail_on_empty=False,
var_name=None,
):
r"""
The variable value is valid if it is a list where each entry can be found in the valid_values list or if
none of its values can be found in the invalid_values list or if all of the values in the required_values
list can be found in var_value.
The caller may only specify one of these 3 arguments: valid_values, invalid_values, required_values.
Description of argument(s):
var_value The value 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.
invalid_values A list of invalid values. If any element in var_value is equal to any of
the values in this argument, var_value is considered invalid.
required_values Every value in required_values must be found in var_value. Otherwise,
var_value is considered invalid.
fail_on_empty Indicates that an empty list for the variable value should be considered
an error.
"""
error_message = ""
# Validate this function's arguments.
if not (
bool(len(valid_values))
^ bool(len(invalid_values))
^ bool(len(required_values))
):
error_message += "Programmer error - You must provide only one of the"
error_message += " following: valid_values, invalid_values,"
error_message += " required_values.\n"
error_message += gp.sprint_var(invalid_values, gp.show_type())
error_message += gp.sprint_var(valid_values, gp.show_type())
error_message += gp.sprint_var(required_values, gp.show_type())
return process_error_message(error_message)
if type(var_value) is not list:
var_name = get_var_name(var_name)
error_message = valid_type(var_value, list, var_name=var_name)
if error_message:
return process_error_message(error_message)
if fail_on_empty and len(var_value) == 0:
var_name = get_var_name(var_name)
error_message += "Invalid empty list:\n"
error_message += gp.sprint_varx(var_name, var_value, gp.show_type())
return process_error_message(error_message)
if len(required_values):
found_error = 0
display_required_values = list(required_values)
for ix in range(0, len(required_values)):
if required_values[ix] not in var_value:
found_error = 1
display_required_values[ix] = (
str(display_required_values[ix]) + "*"
)
if found_error:
var_name = get_var_name(var_name)
error_message += "The following list is invalid:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
error_message += "\n"
error_message += "Because some of the values in the "
error_message += "required_values list are not present (see"
error_message += ' entries marked with "*"):\n'
error_message += "\n"
error_message += gp.sprint_varx(
"required_values",
display_required_values,
gp.blank() | gp.show_type(),
)
error_message += "\n"
return process_error_message(error_message)
if len(invalid_values):
found_error = 0
display_var_value = list(var_value)
for ix in range(0, len(var_value)):
if var_value[ix] in invalid_values:
found_error = 1
display_var_value[ix] = str(var_value[ix]) + "*"
if found_error:
var_name = get_var_name(var_name)
error_message += "The following list is invalid (see entries"
error_message += ' marked with "*"):\n'
error_message += gp.sprint_varx(
var_name, display_var_value, gp.blank() | gp.show_type()
)
error_message += "\n"
error_message += gp.sprint_var(invalid_values, gp.show_type())
return process_error_message(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] = str(var_value[ix]) + "*"
if found_error:
var_name = get_var_name(var_name)
error_message += "The following list is invalid (see entries marked"
error_message += ' with "*"):\n'
error_message += gp.sprint_varx(
var_name, display_var_value, gp.blank() | gp.show_type()
)
error_message += "\n"
error_message += gp.sprint_var(valid_values, gp.show_type())
return process_error_message(error_message)
return process_error_message(error_message)
def valid_dict(
var_value,
required_keys=[],
valid_values={},
invalid_values={},
var_name=None,
):
r"""
The dictionary variable value is valid if it contains all required keys and each entry passes the
valid_value() call.
Examples:
person_record = {'last_name': 'Jones', 'first_name': 'John'}
valid_values = {'last_name': ['Doe', 'Jones', 'Johnson'], 'first_name': ['John', 'Mary']}
invalid_values = {'last_name': ['Manson', 'Hitler', 'Presley'], 'first_name': ['Mickey', 'Goofy']}
valid_dict(person_record, valid_values=valid_values)
valid_dict(person_record, invalid_values=invalid_values)
Description of argument(s):
var_value The value being validated.
required_keys A list of keys which must be found in the dictionary for it to be
considered valid.
valid_values A dictionary whose entries correspond to the entries in var_value. Each
value in valid_values is itself a valid_values list for the corresponding
value in var_value. For any var_value[key] to be considered valid, its
value must be found in valid_values[key].
invalid_values A dictionary whose entries correspond to the entries in var_value. Each
value in invalid_values is itself an invalid_values list for the
corresponding value in var_value. For any var_value[key] to be
considered valid, its value must NOT be found in invalid_values[key].
"""
error_message = ""
missing_keys = list(set(required_keys) - set(var_value.keys()))
if len(missing_keys) > 0:
var_name = get_var_name(var_name)
error_message += "The following dictionary is invalid because it is"
error_message += " missing required keys:\n"
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
error_message += "\n"
error_message += gp.sprint_var(missing_keys, gp.show_type())
return process_error_message(error_message)
var_name = get_var_name(var_name)
if len(valid_values):
keys = valid_values.keys()
error_message = valid_dict(
var_value, required_keys=keys, var_name=var_name
)
if error_message:
return process_error_message(error_message)
for key, value in valid_values.items():
key_name = " [" + key + "]"
sub_error_message = valid_value(
var_value[key], valid_values=value, var_name=key_name
)
if sub_error_message:
error_message += (
"The following dictionary is invalid because one of its"
" entries is invalid:\n"
)
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
error_message += "\n"
error_message += sub_error_message
return process_error_message(error_message)
for key, value in invalid_values.items():
if key not in var_value:
continue
key_name = " [" + key + "]"
sub_error_message = valid_value(
var_value[key], invalid_values=value, var_name=key_name
)
if sub_error_message:
error_message += (
"The following dictionary is invalid because one of its"
" entries is invalid:\n"
)
error_message += gp.sprint_varx(
var_name, var_value, gp.blank() | gp.show_type()
)
error_message += "\n"
error_message += sub_error_message
return process_error_message(error_message)
return process_error_message(error_message)
def valid_program(var_value, var_name=None):
r"""
The variable value is valid if it contains the name of a program which can be located using the "which"
command.
Description of argument(s):
var_value The value being validated.
"""
error_message = ""
rc, out_buf = gc.shell_cmd(
"which " + var_value, quiet=1, show_err=0, ignore_err=1
)
if rc:
var_name = get_var_name(var_name)
error_message += "The following required program could not be found"
error_message += " using the $PATH environment variable:\n"
error_message += gp.sprint_varx(var_name, var_value, gp.blank())
PATH = os.environ.get("PATH", "").split(":")
error_message += "\n"
error_message += gp.sprint_var(PATH)
return process_error_message(error_message)
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)
# Modify selected function docstrings by adding headers/footers.
func_names = [
"valid_type",
"valid_value",
"valid_range",
"valid_integer",
"valid_dir_path",
"valid_file_path",
"valid_path",
"valid_list",
"valid_dict",
"valid_program",
"valid_length",
"valid_float",
"valid_date_time",
]
raw_doc_strings = {}
for func_name in func_names:
cmd_buf = "raw_doc_strings['" + func_name + "'] = " + func_name
cmd_buf += ".__doc__"
exec(cmd_buf)
cmd_buf = func_name + ".__doc__ = docstring_header + " + func_name
cmd_buf += '.__doc__.rstrip(" \\n") + additional_args_docstring_footer'
exec(cmd_buf)