Utils

Generic utility functions and classes which can be used throughout the entire package.

Classes:

SafeDict

Extends dict to ignore missing keys when using format_map operations

Functions:

strip_ignore_words(value[, words])	Remove ignorable words from the beginning of a string.
safe_format_map(value, format_map)	Apply a format_map to a given value ignoring missing keys.
unicode_len(value)	Returns the visible length of value when rendered with fixed-width font.
unicode_reversed(value)	Returns a reversed string or value keeping unicode characters which combine in the correct order
get_max_width(values[, min_width, max_width])	Get max width of given list of values for column-aligned logging.
align_string(value[, max_width, truncate_left])	Align string with space padding and truncate any string longer than max_width with ...
limit_value(value[, floor, ceil])	Limit a given value to always be between some floor and ceil
to_collection(data[, cls])	Safely turn any object into a collection of a given type T.
unique_list(value)	Returns a copy of the given value that contains only unique elements.
flatten_nested(nested[, previous])	Flatten the final layers of the values of a nested map to a single list
merge_maps(source, new[, extend, overwrite])	Recursively update a given source map in place with a new map.
get_most_common_values(values)	Get an ordered list of the most common values for a given collection of values
get_user_input([text])	Print formatted dialog with optional text and get the user's input.
clean_kwargs(func, kwargs)	Clean kwargs by removing any kwarg not in the signature of the given func.
required_modules_installed(modules[, this])	Check the required modules are installed, raise MusifyImportError if not.

class musify.utils.SafeDict

Bases: dict

Extends dict to ignore missing keys when using format_map operations

musify.utils.strip_ignore_words(value, words=frozenset({'A', 'The'}))

Remove ignorable words from the beginning of a string.

Useful for sorting collections strings with ignorable start words and/or special characters. Only removes the first word it finds at the start of the string.

Returns:

tuple[bool, str] – Tuple of (True if the string starts with some special character, the formatted string)

musify.utils.safe_format_map(value, format_map)

Apply a format_map to a given value ignoring missing keys. If value is a map, apply the format_map recursively.

Return type:

TypeVar(T)

musify.utils.unicode_len(value)

Returns the visible length of value when rendered with fixed-width font.

Takes into account unicode characters which render with varying widths.

Return type:

int

musify.utils.unicode_reversed(value)

Returns a reversed string or value keeping unicode characters which combine in the correct order

Return type:

str

musify.utils.get_max_width(values, min_width=15, max_width=50)

Get max width of given list of values for column-aligned logging.

Uses width as would be seen in a fixed-width font taking into account characters with varying widths.

Return type:

int

musify.utils.align_string(value, max_width=0, truncate_left=False)

Align string with space padding and truncate any string longer than max_width with ...

This function aligns based on fixed-width fonts. Therefore, unicode characters (e.g. emojis) will be aligned based on their width in a fixed-width font.

Parameters:

• value (Any) – The value to be aligned. Will first be converted to a string.

• max_width (int (default: 0)) – The expected width (i.e. number of fixed-width characters) the string should occupy in a fixed-width font.

• truncate_left (bool (default: False)) – When truncating, truncate the left (i.e. start) of the string.

Returns:

str – The padded and truncated string with visible length == max_width.

musify.utils.limit_value(value, floor=1, ceil=50)

Limit a given value to always be between some floor and ceil

Return type:

int | float

musify.utils.to_collection(data, cls=<class 'tuple'>)

Safely turn any object into a collection of a given type T.

Strings are converted to collections of size 1 where the first element is the string. Returns None if value is None.

Return type:

Optional[TypeVar(T, list, set, tuple)]

musify.utils.unique_list(value)

Returns a copy of the given value that contains only unique elements. Useful for producing unique lists whilst preserving order.

Return type:

list[Any]

musify.utils.flatten_nested(nested, previous=None)

Flatten the final layers of the values of a nested map to a single list

Return type:

list[TypeVar(T, bound= Any)]

musify.utils.merge_maps(source, new, extend=True, overwrite=False)

Recursively update a given source map in place with a new map.

Parameters:

• source (TypeVar(T, bound= MutableMapping)) – The source map.

• new (Mapping) – The new map with values to update for the source map.

• extend (bool (default: True)) – When a value is a list and a list is already present in the source map, extend the list when True. When False, only replace the list if overwrite is True.

• overwrite (bool (default: False)) – When True, overwrite any value in the source list destructively.

Returns:

TypeVar(T, bound= MutableMapping) – The updated dict.

musify.utils.get_most_common_values(values)

Get an ordered list of the most common values for a given collection of values

Return type:

list[Any]

musify.utils.get_user_input(text=None)

Print formatted dialog with optional text and get the user’s input.

Return type:

str

musify.utils.clean_kwargs(func, kwargs)

Clean kwargs by removing any kwarg not in the signature of the given func.

Return type:

None

musify.utils.required_modules_installed(modules, this=None)

Check the required modules are installed, raise MusifyImportError if not.

Return type:

bool