hbutils.random.sequence

Overview:: Random function utilities for sequences, providing shuffle and multiple choice operations with support for custom random instances and various collection types.

shuffle

hbutils.random.sequence.shuffle(seq: Collection[_ElementType], *, random: Random | None = None) → Collection[_ElementType][source]

Shuffle the given collection and return a new shuffled collection of the same type.

Parameters:

seq (Collection[_ElementType]) – Original sequence to be shuffled.
random (Optional[random_module.Random]) – Random instance for shuffling. If None, uses the native instance from random module.

Returns:

A new shuffled collection of the same type as input.

Return type:

Collection[_ElementType]

Examples::

>>> shuffle([1, 2, 3])
[3, 1, 2]  # just one of the possibilities
>>> shuffle(('a', 1, 'b', 2))
('b', 1, 2, 'a')  # the tuple type will be kept

multiple_choice

hbutils.random.sequence.multiple_choice(seq: Collection[_ElementType], count: int, *, put_back: bool = False, random: Random | None = None) → Collection[_ElementType][source]

Choose multiple items from the given sequence with or without replacement.

Parameters:

seq (Collection[_ElementType]) – Original sequence to choose items from.
count (int) – Number of items to choose. Should be no more than length of seq when put_back is False.
put_back (bool) – Whether to put back the chosen items (sampling with replacement). If False, chosen items will be unique. Default is False.
random (Optional[random_module.Random]) – Random instance for selection. If None, uses the native instance from random module.

Returns:

A new collection of the same type as input containing the chosen items.

Return type:

Collection[_ElementType]

Raises:

ValueError – If put_back is False and count exceeds the length of seq.

Examples::

>>> multiple_choice([1, 2, 3], 2)
[2, 3]  # one of the possibilities
>>> multiple_choice([1, 2, 3], 2, put_back=True)
[2, 2]  # this is possible when put back option is on