parser_interface

tools.parser_interface.dict_formatter(in_dict)

DESCRIPTION:

This function formats a Python dictionary; all UNICODE and data-type conversions are performed within this function.

Parameters:

in_dict: Dict

A standalone Python dictionary to be formatted.

Returns:

out_dict: Dict

A standalone Python dictionary which has been formatted.

Return type:

Dict

tools.parser_interface.dict_key_remove(dict_in, key)

DESCRIPTION:

This function attempts to remove a Python dictionary key and value pair.

Parameters:

dict_in: Dict

A Python dictionary to be parsed.

key: str

A Python string indicating the dictionary key within the Python dictionary (see above).

Returns:

dict_in: Dict

A Python dictionary from which the specified key and value pair has been removed (if present in the Python dictionary on entry).

Return type:

Dict

tools.parser_interface.dict_key_value(dict_in, key, force=False, max_value=False, min_value=False, index_value=None, no_split=False)

DESCRIPTION:

This function ingests a Python dictionary and a dictionary key and return the value(s) corresponding to the respective dictionary key; if the optional variable force is True and the dictionary key does not exist within the Python dictionary, the function will return NoneType.

Parameters:

dict_in: Dict

A Python dictionary to be parsed.

key: str

A Python string indicating the dictionary key within the Python dictionary (see above).

Returns:

value: Any

A list of values collected from the ingested Python dictionary and the respective dictionary key if no_split is False; a string otherwise.

Raises:

ParserInterfaceError:

• raised if both minimum and maximum values of a list are requested; only minimum or only maximum may be requested upon entry.

• raised if the keyword argument combinations passed upon entry are incorrect.

Return type:

Any

tools.parser_interface.dict_merge(dict1, dict2)

DESCRIPTION:

This function merges two Python dictionaries and returns a generator containing the merged Python dictionary relative to the checks within the function.

Parameters:

dict1: Dict

A Python dictionary to be merged.

dict2: Dict

A Python dictionary to be merged.

Yields:

Dict:

A Python dictionary containing the contents of dict1 and dict2.

Return type:

Generator[Dict, Dict, Dict]

tools.parser_interface.dict_replace_value(in_dict, old, new)

DESCRIPTION:

This function replaces strings within a (nested) Python dictionary and returns the updated (nested) Python dictionary; this function adapted from https://tinyurl.com/dict-value-replace.

Parameters:

in_dict: Dict

A (nested) Python dictionary containing Python strings to be replaced/updated.

old: str

A Python string value specifying the Python string instance to be replaced.

new: str

A Python string value specifying the Python string to replace the value specified by the old attribute.

Returns:

out_dict: Dict

A (nested) Python dictionary updated in accordance within the attributes specified by the old and new attributes; otherwise this Python dictionary is identical to that defined by in_dict.

Return type:

Dict

tools.parser_interface.dict_toobject(in_dict)

DESCRIPTION:

This funcction converts and returns the Python dictionary in_dict, specified upon entry, to a Python Namespace out_obj.

Parameters:

in_dict: Dict

A Python dictionary containing the attribute key and value pairs to be cast as a Python Namespace.

Returns:

out_obj: SimpleNamespace

A Python SimpleNamespace defined by casting the Python dictionary in_dict specified upon input to the respective Python SimpleNamespace.

Return type:

SimpleNamespace

tools.parser_interface.enviro_get(envvar)

DESCRIPTION:

This function retrieves the environment variable corresponding to the specified string; if the environment variable is not defined, NoneType is returned.

Parameters:

envvar: str

A Python string specifying the environment variable name.

Returns:

envvarval: Union[bool, float, int, str]

A Python type that contains the query for the environment variable.

Return type:

Union[bool, float, int, str]

tools.parser_interface.enviro_set(envvar, value)

DESCRIPTION:

This function defines the environment variable corresponding to the supported specified value.

Parameters:

envvar: str

A Python string specifying the environment variable name.

value: Union[bool, float, int, str]

A Python value specifying the value of the environment variable.

Return type:

None

tools.parser_interface.f90_bool(value)

DESCRIPTION:

This method will transform boolean type values to a FORTRAN 90 boolean format; if the variable value specified upon entry is not of boolean format the value is returned unaltered.

Parameters:

value: Any

A Python variable to be evaluated as a boolean type value; if a boolean type the corresponding value is returned as a FORTRAN 90 boolean format.

Returns:

value: Any

An evaluated Python variable; if value was boolean type upon entry the returned value is of FORTRAN 90 boolean format; if not, the unaltered input value is returned.

Return type:

Any

tools.parser_interface.find_commonprefix(strings_list)

DESCRIPTION:

This function returns the common prefix from a list of strings.

Parameters:

strings_list: List

A Python list of strings

Returns:

common_prefix: str

A Python string specifying the common prefix determined from a list of Python strings; NoneType if a common prefix cannot be determined.

Return type:

str

tools.parser_interface.handler(func, handle=<function <lambda>>, return_none=False, raise_exception=False, *args, **kwargs)

DESCRIPTION:

This method permits exceptions to raised (i.e., handled) within Python list comprehensions.

Parameters:

func: Callable

A Python function, often nested within a Python list comprehension, to be evaluated.

handle: Callable

A Python lambda function to be evaluated within the list comprehension.

Returns:

value: Union[Any, None, Exception]

A Python variable type containing the returned expression from the Python list evaluation of a function (func).

Return type:

Union[Any, None, Exception]

tools.parser_interface.list_get_type(in_list, dtype)

DESCRIPTION:

This function parses a list and returns a list of values in accordance with the specified data type.

Parameters:

in_list: List

A Python list containing values possibly of various data types.

dtype: str

A Python string specifying the data type to be sought.

Returns:

var_list: List

A Python list contain values collected from the input list but of the specified data type.

Return type:

List

tools.parser_interface.list_replace_value(in_list, old, new)

DESCRIPTION:

This function replaces strings within a Python list and returns the updated Python list; this function adapted from https://tinyurl.com/list-value-replace.

Parameters:

in_list: List

A Python list containing Python strings to be replaced/updated.

old: str

A Python string value specifying the Python string instance to be replaced.

new: str

A Python string value specifying the Python string to replace the value specified by the old attribute.

Returns:

out_list: List

A Python list updated in accordance within the attributes specified by the old and new attributes; otherwise this Python list is identical to that defined by in_list.

Return type:

List

tools.parser_interface.match_list(in_list, match_string, exact=False)

DESCRIPTION:

This function ingests a Python list and a Python string and matches, either exact or partial, are sought for the string within the provided; if exact is True upon entry, the matching Python string is returned if a match is found; otherwise NoneType is returned; if exact is False upon entry, a list of matching Python strings is returned.

Parameters:

in_list: List

A Python list of strings within matches will be sought.

match_string: str

A Python string for which to search for matches within the ingested list.

Returns:

match_chk: bool

A Python boolean variable indicating whether a match (or matches) has (have) been made.

match_str: str

A Python string (if exact is True upon entry) or a Python list of strings (if exact is False upon entry) containing all matches to the input match string; if no matches can be found, either NoneType (if exact is True upon entry) or an empty list (if exact is False upon entry) is returned.

Return type:

Tuple[bool, str]

tools.parser_interface.object_append(object_in, object_key, dict_in)

DESCRIPTION:

This function appends the contents of Python dictionary to specified object key.

Parameters:

object_in: object

A Python object to be appended.

object_key: str

A Python string value specifying the input Python object attribute.

dict_in: Dict

A Python dictionary containing the key and value pairs to append to the input Python object.

Returns:

object_out: object

An appended Python object containing the input Python dictionary key and value pairs relative to the specified Python object attribute.

Return type:

object

tools.parser_interface.object_compare(obj1, obj2)

DESCRIPTION:

This function compares two Python objects.

Parameters:

obj1: object

A Python object against which to compare with another object.

obj2: object

A Python object to compare to obj1 (above).

Returns:

compare: bool

A Python boolean variable specifying whether the respective Python objects are identical.

Return type:

bool

tools.parser_interface.object_deepcopy(object_in)

DESCRIPTION:

This function ingests a Python object and returns a deep copy of the respective object.

Parameters:

object_in: object

A Python object for which to create a deep copy.

Returns:

object_out: object

A Python object which is a deep copy of the specified input object object_in.

Return type:

object

tools.parser_interface.object_define()

DESCRIPTION:

This function defines an empty Python object.

Returns:

empty_obj: object

An empty Python object.

Return type:

object

tools.parser_interface.object_getattr(object_in, key, force=False)

DESCRIPTION:

This function ingests a Python object and a Python attribute and returns the value of the respective attribute; if force is True and the Python object attribute does not exist, this function returns NoneType.

Parameters:

object_in: object

A Python object within which to search for attributes.

key: str

A Python string value specifying the attribute to seek.

Returns:

value: Any

The result of the respective attribute search.

Raises:

ParserInterfaceError:

• raised if force is False and the Python object attribute does not exist.

Return type:

Any

tools.parser_interface.object_hasattr(object_in, key)

DESCRIPTION:

This function checks whether a Python object contains an attribute and returns an appropriate boolean value indicating the result of the inquiry.

Parameters:

object_in: object

A Python object within which to inquire about attributes.

key: str

A Python string value specifying the attribute to inquire about.

Returns:

chk_attr: bool

A Python boolean value containing the result of the attribute inquiry.

Return type:

bool

tools.parser_interface.object_setattr(object_in, key, value)

DESCRIPTION:

This function ingests a Python object and a Python key and value pair and defines the attributes for the respective object.

Parameters:

object_in: object

A Python object within which to search for attributes.

key: str

A Python string value specifying the attribute to define.

value: Any

A Python variable value specifying the value to accompany the Python object attribute (key).

Returns:

object_out: object

A Python object containing the specified key and value pair (e.g., attribute).

Return type:

object

tools.parser_interface.object_todict(object_in)

DESCRIPTION:

This function ingests a Python object and returns a Python dictionary containing the contents of the object.

Parameters:

object_in: object

A Python object containing specified content.

Returns:

dict_out: Dict

A Python dictionary containing the contents of the Python object.

Return type:

Dict

tools.parser_interface.str_to_bool(string)

DESCRIPTION:

This function converts a Python string to it’s corresponding boolean value; if a JSONDecodeError exception is encountered, NoneType is returned.

Parameters:

string: str

A Python string for which to convert to a corresponding boolean value.

Returns:

boolval: bool

A Python boolean valued variable containing the boolean value corresponding to the Python string specified upon entry; if a JSONDecodeError is encounterd, NoneType is returned.

Return type:

bool

tools.parser_interface.string_parser(in_list, remove_comma=False)

DESCRIPTION:

This function ingests a Python list of variables and returns a Python list of appropriately formatted values.

Parameters:

in_list: List

A Python list of variable values to be formatted.

Returns:

out_list: List

A Python list of appropriately formatted variable values.

Return type:

List

tools.parser_interface.true_or_false(argval)

DESCRIPTION:

This function checks whether an argument is a Boolean-type value; if so, this function defines the appropriate Python boolean-type; otherwise, this function returns NoneType.

Parameters:

argval: Any

A value corresponding to an argument.

Returns:

pytype: Union[bool or None]

A Python boolean-type value if the argument is a boolean variable; otherwise, NoneType.

Return type:

Optional[bool]

tools.parser_interface.unique_list(in_list)

DESCRIPTION:

This function ingests a list, possibly with duplicate values, and returns a list of only unique values.

Parameters:

in_list: List

A N-dimensional Python list containing strings.

Returns:

out_list: List

A Python list containing only uniquely-valued strings.

Return type:

List

tools.parser_interface.update_dict(default_dict, base_dict, update_none=False)

DESCRIPTION:

This function reads Python dictionaries containing default key and value pairs (default_dict) and a base (optional or changed values) Python dictionary containing key and value pairs (base_dict); the output Python dictionary output_dict is initialized with the base Python dictionary; any key and value pairs within default_dict which are not in output_dict are updated with those from default_dict.

Parameters:

default_dict: Dict

A Python dictionary containing default key and value pairs; this Python dictionary contains all possible key and value pairs to compute the output dictionary (output_dict).

base_dict: Dict

A Python dictionary containing either optional or changed key and value pairs; this Python dictionary is used to initialize the output Python dictionary output_dict.

Returns:

output_dict: Dict

A Python dictionary containing the respective attributes from the base and default Python dictionaries, base_dict and default_dict respectively.

Return type:

Dict