random_collections package

Submodules

random_collections.random_collection module

class random_collections.random_collection.RandomCollection(values: List[V], weights: List[float], randomization_factor: float = 1.5)

Bases: Generic[V], IRandom[V]

Collection enabling weighted random selection of enum values with dynamic weight randomization.

_values

List of enum members to choose from.

Type:

List[V]

_weights

Corresponding weights for each enum member.

Type:

List[float]

randomization_factor

Multiplier range for weight perturbation.

Type:

float

__init__(values: List[V], weights: List[float], randomization_factor: float = 1.5)

Initialize with lists of enum members and their base weights.

Parameters:

• values (List[V]) – Enum members available for selection.

• weights (List[float]) – Base weights for each member.

• randomization_factor (float) – Max multiplier for weight randomization.

get_random_value(excluding: List[V] = None) → V

Select a random enum member based on weights, excluding specified members.

Parameters:

excluding (List[V], optional) – Members to skip. Defaults to None.

Returns:

Selected enum member.

Return type:

V

class random_collections.random_collection.RandomCollectionBuilder

Bases: object

Factory for creating RandomCollection instances from common data structures.

static build_from_enum(enum_type: type[Enum]) → RandomCollection[Enum]

Create a RandomCollection for enum members with equal base weights.

Parameters:

enum_type (type[Enum]) – Enum class to build collection from.

Returns:

Collection with uniform weights.

Return type:

RandomCollection[Enum]

static build_from_value_weight_dict(value_weight_dict: dict[V, float]) → RandomCollection[V]

Create a RandomCollection from a dict of values to weights.

Parameters:

value_weight_dict (dict[V, float]) – Mapping of enum or values to base weights.

Returns:

Collection reflecting specified weights.

Return type:

RandomCollection[V]

static build_from_list_of_values(values: List[V]) → RandomCollection[V]

Create a RandomCollection from a list of values using uniform weights.

Parameters:

values (List[V]) – List of enum members or values.

Returns:

Collection with equal weights.

Return type:

RandomCollection[V]

random_collections.random_collection_interface module

class random_collections.random_collection_interface.IRandom

Bases: ABC, Generic

abstractmethod get_random_value(*args, **kwargs) → V

random_collections.random_collection_table module

class random_collections.random_collection_table.RandomTable(value_weight_dict: Dict[K, RandomCollection[V]])

Bases: Generic[K, V], IRandom[V]

Table mapping keys to RandomCollections for weighted random value selection.

value_weight_dict

Maps each key to a RandomCollection of values.

Type:

Dict[K, RandomCollection[V]]

__init__(value_weight_dict: Dict[K, RandomCollection[V]])

Initialize RandomTable with a mapping from keys to collections.

Parameters:

value_weight_dict (Dict[K, RandomCollection[V]]) – Prebuilt collections per key.

get_random_value(key: K) → V

Select a random value from the collection associated with key.

Parameters:

key (K) – The key for which to sample a value.

Returns:

Randomly selected enum member.

Return type:

V

Raises:

KeyError – If key is not in the table.

class random_collections.random_collection_table.RandomTableBuilder

Bases: object

Factory for constructing RandomTable instances from weight definitions.

static build_from_weight_table(key_enum: type[Enum], value_enum: type[Enum], weights: List[List[float]]) → RandomTable[Enum, Enum]

Build a RandomTable given parallel enums and a weight matrix.

Parameters:

• key_enum (type[Enum]) – Enum class for table keys.

• value_enum (type[Enum]) – Enum class for table values.

• weights (List[List[float]]) – Weight lists per key.

Returns:

Table sampling values by key.

Return type:

RandomTable[Enum, Enum]

static validate_value_weight_dict(key_enum: type[K], value_enum: type[V], value_weight_dict: Dict[K, Dict[V, float]]) → None

Ensure provided dict covers all enum members exactly.

Parameters:

• key_enum (type[K]) – Enum of expected keys.

• value_enum (type[V]) – Enum of expected values.

• value_weight_dict (Dict[K, Dict[V, float]]) – Mapping from keys to value-weight dicts.

Raises:

AssertionError – If keys or value sets don’t match enums.

static build_from_dict(key_enum: type[K], value_enum: type[V], value_weight_dict: Dict[K, Dict[V, float]]) → RandomTable[K, V]

Construct a RandomTable from nested dict of weights.

Parameters:

• key_enum (type[K]) – Enum class for keys.

• value_enum (type[V]) – Enum class for values.

• value_weight_dict (Dict[K, Dict[V, float]]) – Outer key-> inner value-> weight dict.

Returns:

Table ready for random sampling.

Return type:

RandomTable[K, V]

random_collections.random_collection_test module

random_collections.random_table_node_test module

Module contents