mutwo.utilities.tools

Generic utility functions.

Functions:

accumulate_from_n(iterable, n)	Accumulates iterable starting with value n.
accumulate_from_zero(iterable)	Accumulates iterable starting from 0.
cyclic_permutations(sequence)	Cyclic permutation of an iterable.
find_closest_index(item, data[, key])	Return index of element in data with smallest difference to item.
find_closest_item(item, data[, key])	Return element in data with smallest difference to item.
get_nested_item_from_indices(indices, sequence)	Get item in nested Sequence.
insert_next_to(iterable, item_to_find, ...)	Insert an item into a list relative to the first item equal to a certain value.
scale(value, old_min, old_max, new_min, new_max)	Scale a value from one range to another range.
set_nested_item_from_indices(indices, ...)	Set item in nested Sequence.
uniqify_iterable(iterable[, sort_key, ...])	Not-Order preserving function to uniqify any iterable with non-hashable objects.

accumulate_from_n(iterable, n)

Accumulates iterable starting with value n.

Parameters

• iterable (Iterable[Union[float, fractions.Fraction]]) – The iterable which values shall be accumulated.

• n (Union[float, fractions.Fraction]) – The start number from which shall be accumulated.

Return type

Iterator

Example:

>>> from mutwo.utilities import tools
>>> tools.accumulate_from_n((4, 2, 3), 0)
(0, 4, 6, 9)
>>> tools.accumulate_from_n((4, 2, 3), 2)
(2, 6, 8, 11)

accumulate_from_zero(iterable)

Accumulates iterable starting from 0.

Parameters

iterable (Iterable[Union[float, fractions.Fraction]]) – The iterable which values shall be accumulated.

Return type

Iterator

Example:

>>> from mutwo.utilities import tools
>>> tools.accumulate_from_zero((4, 2, 3), 0)
(0, 4, 6, 9)

cyclic_permutations(sequence)

Cyclic permutation of an iterable. Return a generator object.

Parameters

sequence (Sequence[Any]) – The sequence from which cyclic permutations shall be generated.

Return type

Generator

Example:

>>> from mutwo.utilities import tools
>>> permutations = tools.cyclic_permutations((1, 2, 3, 4))
>>> next(permutations)
(2, 3, 4, 1)
>>> next(permutations)
(3, 4, 1, 2)

Adapted function from the reply of Paritosh Singh

find_closest_index(item, data, key=<function <lambda>>)

Return index of element in data with smallest difference to item.

Parameters

• item (Union[float, fractions.Fraction]) – The item from which the closest item shall be found.

• data (Iterable) – The data to which the closest item shall be found.

• key (Callable[[Any], mutwo.utilities.tools.T]) –

Return type

int

Example:

>>> from mutwo.utilities import tools
>>> tools.find_closest_index(2, (1, 4, 5))
0
>>> tools.find_closest_index(127, (100, 4, 300, 53, 129))
4
>>> tools.find_closest_index(127, (('hi', 100), ('hey', 4), ('hello', 300)), key=lambda item: item[1])
0

find_closest_item(item, data, key=<function <lambda>>)

Return element in data with smallest difference to item.

Parameters

• item (Union[float, fractions.Fraction]) – The item from which the closest item shall be found.

• data (Sequence) – The data to which the closest item shall be found.

• key (Callable[[Any], mutwo.utilities.tools.T]) –

Returns

The closest number to item in data.

Return type

mutwo.utilities.tools.T

Example:

>>> from mutwo.utilities import tools
>>> tools.find_closest_item(2, (1, 4, 5))
1
>>> tools.find_closest_item(127, (100, 4, 300, 53, 129))
129
>>> tools.find_closest_item(127, (('hi', 100), ('hey', 4), ('hello', 300)), key=lambda item: item[1])
('hi', 100)

get_nested_item_from_indices(indices, sequence)

Get item in nested Sequence.

Parameters

• indices (typing.Sequence[int]) – The indices of the nested item.

• sequence (typing.Sequence[typing.Any]) – A nested sequence.

Return type

Any

Example:

>>> from mutwo.utilities import tools
>>> nested_sequence = (1, 2, (4, (5, 1), (9, (3,))))
>>> tools.get_nested_item_from_indices((2, 2, 0), nested_sequence)
9
>>> nested_sequence[2][2][0]  # is equal
9

insert_next_to(iterable, item_to_find, distance, item_to_insert)

Insert an item into a list relative to the first item equal to a certain value.

Parameters

• iterable (MutableSequence) –

• item_to_find (Any) –

• distance (int) –

• item_to_insert (Any) –

scale(value, old_min, old_max, new_min, new_max)

Scale a value from one range to another range.

Parameters

• value (Union[float, fractions.Fraction]) – The value that shall be scaled.

• old_min (Union[float, fractions.Fraction]) – The minima of the old range.

• old_max (Union[float, fractions.Fraction]) – The maxima of the old range.

• new_min (Union[float, fractions.Fraction]) – The minima of the new range.

• new_max (Union[float, fractions.Fraction]) – The maxima of the new range.

Return type

Union[float, fractions.Fraction]

Example:

>>> from mutwo.utilities import tools
>>> tools.scale(1, 0, 1, 0, 100)
100
>>> tools.scale(0.5, 0, 1, 0, 100)
50
>>> tools.scale(0.2, 0, 1, 0, 100)
20

set_nested_item_from_indices(indices, sequence, item)

Set item in nested Sequence.

Parameters

• indices (typing.Sequence[int]) – The indices of the nested item which shall be set.

• sequence (typing.MutableSequence[typing.Any]) – A nested sequence.

• item (typing.Any) – The new item value.

Return type

None

Example:

>>> from mutwo.utilities import tools
>>> nested_sequence = [1, 2, [4, [5, 1], [9, [3]]]]]
>>> tools.set_nested_item_from_indices((2, 2, 0), nested_sequence, 100)
>>> nested_sequence[2][2][0] = 100  # is equal

uniqify_iterable(iterable, sort_key=None, group_by_key=None)

Not-Order preserving function to uniqify any iterable with non-hashable objects.

Parameters

• iterable (Sequence) – The iterable which items shall be uniqified.

• sort_key (Optional[Callable[[Any], Union[float, fractions.Fraction]]]) –

• group_by_key (Optional[Callable[[Any], Any]]) –

Returns

Return uniqified version of the entered iterable. The function will try to return the same type of the passed iterable. If Python raises an error during initialisation of the original iterable type, the function will simply return a tuple.

Return type

Iterable

Example:

>>> from mutwo.parameters import pitches
>>> from mutwo.utilities import tools
>>> tools.uniqify_iterable([pitches.WesternPitch(pitch_name) for pitch_name in 'c d e c d e e f a c a'.split(' ')])
[WesternPitch(c4),
WesternPitch(d4),
WesternPitch(e4),
WesternPitch(f4),
WesternPitch(a4)]