COT.data_validation module

Various helpers for data sanity checks.

Exceptions

InvalidInputError Miscellaneous error during validation of user input.
ValueMismatchError Values which were expected to be equal turned out to be not equal.
ValueUnsupportedError An unsupported value was provided.
ValueTooLowError A numerical input was less than the lowest supported value.
ValueTooHighError A numerical input was higher than the highest supported value.

Functions

alphanum_split Split the key into a list of [text, int, text, int, ..., text].
canonicalize_helper Try to find a mapping of input to output.
canonicalize_ide_subtype Try to convert the given IDE controller string to a canonical form.
canonicalize_nic_subtype Try to convert the given NIC subtype string to a canonical form.
canonicalize_scsi_subtype Try to convert the given SCSI controller string to a canonical form.
check_for_conflict Make sure the list does not contain references to more than one object.
device_address Parser helper function for device address arguments.
file_checksum Get the checksum of the given file.
mac_address Parser helper function for MAC address arguments.
match_or_die Make sure “first” and “second” are equal or raise an error.
natural_sort Sort the given list “naturally” rather than in ASCII order.
no_whitespace Parser helper function for arguments not allowed to contain whitespace.
non_negative_int Parser helper function for integer arguments that must be 0 or more.
positive_int Parser helper function for integer arguments that must be 1 or more.
to_string Get string representation of an object, special-case for XML Element.
validate_int Parser helper function for validating integer arguments in a range.
truth_value Parser helper function for truth values like ‘0’, ‘y’, or ‘false’.

Constants

NIC_TYPES List of NIC type strings recognized as canonical.
exception InvalidInputError[source]

Bases: exceptions.ValueError

Miscellaneous error during validation of user input.

exception ValueMismatchError[source]

Bases: exceptions.ValueError

Values which were expected to be equal turned out to be not equal.

exception ValueTooHighError(value_type, actual_value, expected_value)[source]

Bases: COT.data_validation.ValueUnsupportedError

A numerical input was higher than the highest supported value.

Parameters:
  • value_type (str) – descriptive string
  • actual_value (int) – invalid value that was provided
  • expected_value (int) – maximum supported value
exception ValueTooLowError(value_type, actual_value, expected_value)[source]

Bases: COT.data_validation.ValueUnsupportedError

A numerical input was less than the lowest supported value.

Parameters:
  • value_type (str) – descriptive string
  • actual_value (int) – invalid value that was provided
  • expected_value (int) – minimum supported value
exception ValueUnsupportedError(value_type, actual_value, expected_value)[source]

Bases: COT.data_validation.InvalidInputError

An unsupported value was provided.

Parameters:
  • value_type (str) – descriptive string
  • actual_value (str) – invalid value that was provided
  • expected_value (object) – expected/valid value(s) (item or list)
__init__(value_type, actual_value, expected_value)[source]

Create an instance of this class.

alphanum_split(key)[source]

Split the key into a list of [text, int, text, int, ..., text].

Parameters:key (str) – String to split.
Returns:list – List of tokens

Examples

>>> alphanum_split("hello1world27")
['hello', 1, 'world', 27, '']
>>> alphanum_split("1istheloneliestnumber")
['', 1, 'istheloneliestnumber']
canonicalize_helper(label, user_input, mappings, re_flags=0)[source]

Try to find a mapping of input to output.

Parameters:
  • label (str) – Label to use in any error raised
  • user_input (str) – User-provided string
  • mappings (list) – List of (expr, canonical) pairs for mapping.
  • re_flags (int) – re.IGNORECASE, etc. if desired
Returns:

str – The canonical string

Raises:

ValueUnsupportedError – If no expr in mappings matches the given user_input.

canonicalize_ide_subtype(subtype)[source]

Try to convert the given IDE controller string to a canonical form.

Parameters:subtype (str) – User-provided string
Returns:str – The canonical string, one of:
  • PIIX4
  • virtio
Raises:ValueUnsupportedError – If the canonical string cannot be determined

Examples

>>> canonicalize_ide_subtype('VirtIO')
'virtio'
>>> canonicalize_ide_subtype('PIIX4')
'PIIX4'
>>> try:  
...     canonicalize_ide_subtype('usb')
... except ValueUnsupportedError as e:
...     print(e)
Unsupported value 'usb' for IDE controller subtype...
canonicalize_nic_subtype(subtype)[source]

Try to convert the given NIC subtype string to a canonical form.

Parameters:subtype (str) – User-provided string
Returns:str – The canonical string, one of NIC_TYPES
Raises:ValueUnsupportedError – If the canonical string cannot be determined

Examples

>>> canonicalize_nic_subtype('e1000')
'E1000'
>>> canonicalize_nic_subtype('vmxnet 3')
'VMXNET3'
>>> try:  
...     canonicalize_nic_subtype('foobar')
... except ValueUnsupportedError as e:
...     print(e)
Unsupported value 'foobar' for NIC subtype ...

See also

COT.platforms.GenericPlatform.validate_nic_type()

canonicalize_scsi_subtype(subtype)[source]

Try to convert the given SCSI controller string to a canonical form.

Parameters:subtype (str) – User-provided string
Returns:str – The canonical string, one of:
  • buslogic
  • lsilogic
  • lsilogicsas
  • virtio
  • VirtualSCSI
Raises:ValueUnsupportedError – If the canonical string cannot be determined

Examples

>>> canonicalize_scsi_subtype('LSI Logic')
'lsilogic'
>>> canonicalize_scsi_subtype('VirtIO')
'virtio'
>>> try:  
...     canonicalize_scsi_subtype('baz')
... except ValueUnsupportedError as e:
...     print(e)
Unsupported value 'baz' for SCSI controller subtype...
check_for_conflict(label, li)[source]

Make sure the list does not contain references to more than one object.

Parameters:
  • label (str) – Descriptive label to be used if an error is raised
  • li (list) – List of object references (which may include None)
Raises:

ValueMismatchError – if references differ

Returns:

object – the object or None

Examples

>>> check_for_conflict("example", ['foo', None, 'foo'])
'foo'
>>> try:
...     check_for_conflict("conflict", [None, 'foo', 'bar'])
... except ValueMismatchError as e:
...     print(e)
Found multiple candidates for the conflict:
foo
...and...
bar
Please correct or clarify your search parameters.
device_address(string)[source]

Parser helper function for device address arguments.

Validate string is an appropriately formed device address such as ‘1:0’.

Parameters:string (str) – String to validate
Raises:InvalidInputError – if string is not a well-formatted device address
Returns:str – Validated string (with leading/trailing whitespace stripped)

Examples

>>> device_address("  1:0\n")
'1:0'
>>> try:
...     device_address("1:0:1")
... except InvalidInputError as e:
...     print(e)
'1:0:1' is not a valid device address
file_checksum(path_or_obj, checksum_type)[source]

Get the checksum of the given file.

Parameters:
  • path_or_obj (str) – File path to checksum OR an opened file object
  • checksum_type (str) – Supported values are ‘md5’ and ‘sha1’.
Returns:

str – Hexadecimal file checksum

mac_address(string)[source]

Parser helper function for MAC address arguments.

Validate whether a string is a valid MAC address. Recognized formats are:

  • xx:xx:xx:xx:xx:xx
  • xx-xx-xx-xx-xx-xx
  • xxxx.xxxx.xxxx
Parameters:string (str) – String to validate
Raises:InvalidInputError – if string is not a valid MAC address
Returns:str – Validated string(with leading/trailing whitespace stripped)
match_or_die(first_label, first, second_label, second)[source]

Make sure “first” and “second” are equal or raise an error.

Parameters:
  • first_label (str) – Descriptive label for first
  • first (object) – First object to compare
  • second_label (str) – Descriptive label for second
  • second (object) – Second object to compare
Raises:

ValueMismatchError – if first != second

Examples

>>> try:
...     match_or_die("old", 1, "new", 2)
... except ValueMismatchError as e:
...     print(e)
old 1 does not match new 2
natural_sort(l)[source]

Sort the given list “naturally” rather than in ASCII order.

E.g, “10” comes after “9” rather than between “1” and “2”.

See also http://nedbatchelder.com/blog/200712/human_sorting.html

Parameters:l (list) – List to sort
Returns:list – Sorted list

Examples

>>> natural_sort(["Eth3", "Eth1", "Eth10", "Eth2"])
['Eth1', 'Eth2', 'Eth3', 'Eth10']
>>> natural_sort(["3rd", "1st", "10th", "101st"])
['1st', '3rd', '10th', '101st']
no_whitespace(string)[source]

Parser helper function for arguments not allowed to contain whitespace.

Parameters:string (str) – String to validate
Raises:InvalidInputError – if string contains internal whitespace
Returns:str – Validated string (with leading/trailing whitespace stripped)

Examples

>>> no_whitespace("    hello    ")
'hello'
>>> try:
...     no_whitespace('hello world')
... except InvalidInputError as e:
...     print(e)
'hello world' contains invalid whitespace
non_negative_int(string)[source]

Parser helper function for integer arguments that must be 0 or more.

Alias for validate_int() setting minimum to 0.

Parameters:

string (str) – String to validate.

Returns:

int – Validated integer value

Raises:

Examples

>>> non_negative_int('0')
0
>>> non_negative_int('1000')
1000
>>> try:
...     non_negative_int('-1')
... except ValueTooLowError as e:
...     print(e)
Value '-1' for input is too low - must be at least 0
positive_int(string)[source]

Parser helper function for integer arguments that must be 1 or more.

Alias for validate_int() setting minimum to 1.

Parameters:

string (str) – String to validate.

Returns:

int – Validated integer value

Raises:

Examples

>>> positive_int('1')
1
>>> try:
...     positive_int('0')
... except ValueTooLowError as e:
...     print(e)
Value '0' for input is too low - must be at least 1
to_string(obj)[source]

Get string representation of an object, special-case for XML Element.

Parameters:obj (object) – Object to represent as a string.
Returns:str – string representation

Examples

>>> to_string("Hello")
'Hello'
>>> to_string(27.5)
'27.5'
>>> e = ET.Element('hello', attrib={'key': 'value'})
>>> print(e)   
<Element ...hello... at ...>
>>> print(to_string(e))
<hello key="value" />
truth_value(value)[source]

Parser helper function for truth values like ‘0’, ‘y’, or ‘false’.

Makes use of distutils.util.strtobool(), but returns True/False rather than 1/0.

Parameters:value (str) – String to parse/validate
Returns:bool – True or False
Raises:ValueUnsupportedError – if the value can’t be parsed to a boolean.

Examples

>>> truth_value('y')
True
>>> truth_value('false')
False
>>> truth_value(True)
True
>>> try:    
...     truth_value('foo')
... except ValueUnsupportedError as e:
...     print(e)
Unsupported value 'foo' for truth value - expected ['y', ...
validate_int(string, minimum=None, maximum=None, label='input')[source]

Parser helper function for validating integer arguments in a range.

Parameters:
  • string (str) – String to convert to an integer and validate
  • minimum (int) – Minimum valid value (optional)
  • maximum (int) – Maximum valid value (optional)
  • label (str) – Label to include in any errors raised
Returns:

int – Validated integer value

Raises:

Examples

>>> validate_int('1')
1
>>> try:
...     validate_int('foo', label='x')
... except ValueUnsupportedError as e:
...     print(e)
Unsupported value 'foo' for x - expected integer
>>> try:
...     validate_int('100', label='x', maximum=10)
... except ValueTooHighError as e:
...     print(e)
Value '100' for x is too high - must be at most 10
NIC_TYPES = ['E1000e', 'E1000', 'PCNet32', 'virtio', 'VMXNET3']

List of NIC type strings recognized as canonical.