shufflemates 0.1.2

A Python package for randomly grouping students or teams.

Shufflemates 🎲✨

A simple Python package for randomly grouping members while supporting fixed pairs and locked teams.

Shufflemates is a Python package that helps you shuffle a list of members into balanced groups while ensuring that some members stay together (fixed pairs) and others remain in exclusive groups (locked teams).

🚀 Installation

You can install Shufflemates via pip:

pip install shufflemates

🎯 Features

• Randomly shuffle members into groups of a specified size.
• Ensure fixed pairs or teams are always grouped together.
• Lock specific groups so that no extra members are added.
• Ensure balanced team sizes even when the total number of members is not a perfect multiple of the group size.

🛠️ Usage

Here's a quick example of how to use Shufflemates:

from shufflemates import shuffle_groups
members = list(range(17))  # Members 0 to 16

group_size = 3
fixed_pairs = [(3, 4), (7, 8, 9)]
locked_teams = [(11, 12, 13)]

# case 1
groups = shuffle_groups(members, group_size, fixed_pairs=fixed_pairs, locked_teams=locked_teams)

for idx, group in enumerate(groups, 1):
    print(f"Group {idx}: {group}")

# or 
# case 2
print_shuffle_groups(
    members,
    group_size,
    fixed_pairs=fixed_pairs,
    locked_teams=locked_teams,
    num_iterations=12,
    iterations_time=0.5)

✅ Example Output

Group 1: [3, 4, 1]
Group 2: [7, 8, 9]
Group 3: [11, 12, 13]  <-- Locked team (No extra members)
Group 4: [2, 10, 14]
Group 5: [15, 0, 6]
Group 6: [5, 16]

📜 License

This project is licensed under the MIT License.