Utility Functions

class mpf.core.utility_functions.Util

Bases: object

Utility functions for MPF.

Methods & Attributes

The Utility Functions has the following methods & attributes available. Note that methods & attributes inherited from the base class are not included here.

static any(futures: [<class 'asyncio.futures.Future'>], loop, timeout=None)

Return first future.

static bin_str_to_hex_str(source_int_str, num_chars)

Convert binary string to hex string.

static cancel_futures(futures: [<class 'asyncio.futures.Future'>])

Cancel futures.

static chunker(l, n)

Yield successive n-sized chunks from l.

static convert_to_simply_type(value)

Convert value to a simple type.

static convert_to_type(value, type_name)

Convert value to type.

static db_to_gain(db)

Convert a value in decibels (-inf to 0.0) to a gain (0.0 to 1.0).

Parameters:db -- The decibel value (float) to convert to a gain Returns:Float

static dict_merge(a, b, combine_lists=True)

Recursively merge dictionaries.

Used to merge dictionaries of dictionaries, like when we're merging together the machine configuration files. This method is called recursively as it finds sub-dictionaries.

For example, in the traditional python dictionary update() methods, if a dictionary key exists in the original and merging-in dictionary, the new value will overwrite the old value.

Consider the following example:

Original dictionary: config['foo']['bar'] = 1

New dictionary we're merging in: config['foo']['other_bar'] = 2

Default python dictionary update() method would have the updated dictionary as this:

{'foo': {'other_bar': 2}}

This happens because the original dictionary which had the single key bar was overwritten by a new dictionary which has a single key other_bar.)

But really we want this:

{'foo': {'bar': 1, 'other_bar': 2}}

This code was based on this: https://www.xormedia.com/recursively-merge-dictionaries-in-python/

Parameters:

• a (dict) -- The first dictionary
• b (dict) -- The second dictionary
• combine_lists (bool) -- Controls whether lists should be combined (extended) or overwritten. Default is True which combines them.

Returns:

The merged dictionaries.

static ensure_future(coro_or_future, loop)

Wrap ensure_future.

static event_config_to_dict(config)

Convert event config to a dict.

static first(futures: [<class 'asyncio.futures.Future'>], loop, timeout=None, cancel_others=True)

Return first future and cancel others.

static get_from_dict(dic, key_path)

Get a value from a nested dict (or dict-like object) from an iterable of key paths.

Parameters:

• dic -- Nested dict of dicts to get the value from.
• key_path -- iterable of key paths

Returns:

value

This code came from here: http://stackoverflow.com/questions/14692690/access-python-nested-dictionary-items-via-a-list-of-keys

static get_named_list_from_objects(switches: []) → [<class 'str'>]

Return a list of names from a list of switch objects.

static hex_string_to_int(inputstring, maxvalue=255)

Take a string input of hex numbers and an integer.

Parameters:

• inputstring -- A string of incoming hex colors, like ffff00.
• maxvalue -- Integer of the max value you'd like to return. Default is 255. (This is the real value of why this method exists.)

Returns:

Integer representation of the hex string.

static hex_string_to_list(input_string, output_length=3)

Take a string input of hex numbers and return a list of integers.

This always groups the hex string in twos, so an input of ffff00 will be returned as [255, 255, 0]

Parameters:

• input_string -- A string of incoming hex colors, like ffff00.
• output_length -- Integer value of the number of items you'd like in your returned list. Default is 3. This method will ignore extra characters if the input_string is too long, and it will pad the left with zeros if the input string is too short.

Returns:

List of integers, like [255, 255, 0]

Raises:

ValueError if the input string contains non-hex chars

static int_to_hex_string(source_int)

Convert an int from 0-255 to a one-byte (2 chars) hex string, with uppercase characters.

static is_hex_string(string)

Return true if string is hex.

static is_power2(num)

Check a number to see if it's a power of two.

Parameters:num -- The number to check

Returns: True or False

static keys_to_lower(source_dict)

Convert the keys of a dictionary to lowercase.

Parameters:source_dict -- The dictionary you want to convert. Returns:A dictionary with lowercase keys.

static list_of_lists(incoming_string)

Convert an incoming string or list into a list of lists.

static normalize_hex_string(source_hex, num_chars=2)

Take an incoming hex value and convert it to uppercase and fills in leading zeros.

Parameters:

• source_hex -- Incoming source number. Can be any format.
• num_chars -- Total number of characters that will be returned. Default is two.

Returns: String, uppercase, zero padded to the num_chars.

Example usage: Send "c" as source_hex, returns "0C".

static pwm32_to_hex_string(source_int)

Convert a PWM32 value to hex.

static pwm32_to_int(source_int)

Convert a PWM32 value to int.

static pwm8_to_hex_string(source_int)

Convert an int to a PWM8 string.

static pwm8_to_int(source_int)

Convert a PWM8 value to int.

static pwm8_to_on_off(source_int)

Convert a PWM8 value to on/off times.

static race(futures: {<class 'asyncio.futures.Future'>: <class 'str'>}, loop)

Return key of first future and cancel others.

static set_in_dict(dic, key_path, value)

Set a value in a nested dict-like object based on an iterable of nested keys.

Parameters:

• dic -- Nested dict of dicts to set the value in.
• key_path -- Iterable of the path to the key of the value to set.
• value -- Value to set.

static string_to_class(class_string)

Convert a string like mpf.core.events.EventManager into a Python class.

Parameters:class_string (str) -- The input string Returns:A reference to the python class object

This function came from here: http://stackoverflow.com/questions/452969/does-python-have-an-equivalent-to-java-class-forname

static string_to_gain(gain_string)

Convert string to gain.

Decode a string containing either a gain value (0.0 to 1.0) or a decibel value (-inf to 0.0) into a gain value (0.0 to 1.0).

Parameters:gain_string -- The string to convert to a gain value Returns:Float containing a gain value (0.0 to 1.0)

static string_to_list(string)

Convert a comma-separated and/or space-separated string into a Python list.

Parameters:string -- The string you'd like to convert. Returns:A python list object containing whatever was between commas and/or spaces in the string.

static string_to_lowercase_list(string)

Convert a comma-separated and/or space-separated string into a Python list.

Each item in the list has been converted to lowercase.

Parameters:string -- The string you'd like to convert. Returns:A python list object containing whatever was between commas and/or spaces in the string, with each item converted to lowercase.

static string_to_ms(time_string)

Decode a string of real-world time into an int of milliseconds.

Example inputs:

200ms 2s None

If no "s" or "ms" is provided, this method assumes "milliseconds."

If time is 'None' or a string of 'None', this method returns 0.

Returns:Integer. The examples listed above return 200, 2000 and 0, respectively

static string_to_secs(time_string)

Decode a string of real-world time into an float of seconds.

See 'string_to_ms' for a description of the time string.