hbutils.random.sequence

Random utilities for sequence-like collections.

This module provides utilities for shuffling sequences and selecting multiple items, with optional control of the random number generator. The functions preserve the input collection type by reconstructing a new instance from shuffled or selected elements.

The module contains the following public functions:

• shuffle() - Shuffle a collection and return a new collection of the same type.

• multiple_choice() - Select multiple elements with or without replacement.

Note

The returned collection is constructed by calling type(seq) with a list of items, so the input type must be constructible from a list of elements.

Example:

>>> from hbutils.random.sequence import shuffle, multiple_choice
>>> shuffle([1, 2, 3])  
[3, 1, 2]
>>> multiple_choice(('a', 'b', 'c'), 2)  
('b', 'a')

__all__

hbutils.random.sequence.__all__ = ['shuffle', 'multiple_choice']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

shuffle

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

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

The function converts the input collection to a list, creates a shuffled index order using the provided random instance, and then reconstructs a new collection using type(seq) from the reordered elements.

Parameters:

• seq (Collection[_ElementType]) – Original collection to be shuffled.

• random (Optional[random_module.Random]) – Random instance for shuffling. If None, uses the native instance from the random module.

Returns:

A new shuffled collection of the same type as seq.

Return type:

Collection[_ElementType]

Note

The input collection is not modified.

Example:

>>> shuffle([1, 2, 3])  
[3, 1, 2]
>>> shuffle(('a', 1, 'b', 2))  
('b', 1, 2, 'a')

multiple_choice

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

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

When put_back is False, the selection is performed without replacement and count must not exceed the collection length. When put_back is True, sampling is done with replacement, allowing repeated items.

Parameters:

• seq (Collection[_ElementType]) – Original collection to choose items from.

• count (int) – Number of items to choose. Must be no more than len(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.

• random (Optional[random_module.Random]) – Random instance for selection. If None, uses the native instance from the random module.

Returns:

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

Return type:

Collection[_ElementType]

Raises:

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

Example:

>>> multiple_choice([1, 2, 3], 2)  
[2, 3]
>>> multiple_choice([1, 2, 3], 2, put_back=True)  
[2, 2]