Shuffler

This class implements shuffling with a special consistency property. Consistency means that, for a given seed and key function, if two sets of items are shuffled, the resulting order will agree on the intersection of the two sets. For example, if items are removed from an original set, the shuffled order for the new set will be the shuffled order of the original set restricted to the smaller set.

Attributes

Attribute	Type	Description
hash_algorithm	string = "md5"	The name of the hashing algorithm used to generate deterministic sort keys for items.

---

Constructor

Signature

def Shuffler(
    seed: any = None
) - > null

Parameters

Name	Type	Description
seed	any = None	An optional seed value to ensure deterministic shuffling. If None, a random seed is generated.

---

Methods

---

seed_display()

@classmethod
def seed_display() - > string

Provides a formatted string representation of the current seed and its origin for debugging or logging purposes.

Returns

Type	Description
string	A string containing the seed value and whether it was 'generated' or 'given'.

---

shuffle()

@classmethod
def shuffle(
    items: iterable,
    key: callable
) - > list

Return a new list of the items in a shuffled order. The key is a function that accepts an item in items and returns a string unique for that item that can be viewed as a string id. The order of the return value is deterministic. It depends on the seed and key function but not on the original order.

Parameters

Name	Type	Description
items	iterable	The collection of items to be reordered.
key	callable	A function that returns a unique string ID for each item to ensure deterministic shuffling.

Returns

Type	Description
list	A new list containing the original items sorted by their computed hashes.

---