STR Coding Club logo STR Coding ClubLearn to code, together
Club Projects

Build a Python Pair Rotation Tool for Club Nights

Our club pairs people up every week, and for two years I did it with a shuffled pack of index cards. It worked badly in a way that took me a while to notice.

A whiteboard showing eight names arranged in a circle with lines drawn between pairs for one club night

Our club pairs people up every week, and for two years I did it with a shuffled pack of index cards. It worked badly in a way that took me a while to notice. Two of our stronger students ended up together on five nights out of nine, one quiet fifteen year old was paired with the same friend every time he came, and three members had never once sat with each other after a full term. Random felt fair and was not.

So we built a tool for it, and it turned out to be the best group project I have run with a mixed ability room. The program takes tonight's attendance list, looks at who has already worked with whom, and prints the pairs for the session. That is a small enough task that beginners can see the whole shape of it, and the part in the middle is a real scheduling problem with proper mathematics underneath, which keeps the experienced members busy for weeks.

The mathematics the project hands you for free

Start the first session at the whiteboard with no computers open. Ask the room how many different pairs you can make from twelve people. Someone will say 144, someone will say 66, and the argument that follows teaches more than a lecture on combinations would.

The answer is 66, since each of the twelve can pair with eleven others and every pair gets counted twice. Six pairs fit in one evening, so a club of twelve needs eleven sessions to put every possible pair together exactly once. That is not an estimate, it is exact, and the schedule that achieves it has a name and a construction: the circle method, the same thing used to draw up a round robin league.

Demonstrate it with eight chairs. Write one name on the board and leave it fixed, then arrange the other seven in a circle and rotate them one position each round. Pair the fixed name with whoever lands beside it, then work inward across the circle. Seven rounds later every pair has met once. Students who have been told combinations are abstract get to watch a formula produce a seating plan.

Then break the good news gently: attendance is never complete. Four people are away, two new ones turn up, and the perfect schedule falls apart in week two. That gap between the clean mathematics and the messy room is the whole project.

The four parts, and who takes them

Agree the data formats before anyone writes a line of code. We use a plain text file with one name per line for the roster, and a CSV with three columns, date and the two names, for the history. Fix that in the first twenty minutes and the four jobs below can run in parallel.

  1. Roster and attendance. Two newer members write the part that reads the roster file, asks who is present tonight, and returns a clean list. This sounds trivial and is not. They have to handle trailing spaces, a name typed in lowercase, a name that is not on the roster at all, and the empty line at the end of the file. I have watched a whole project stall because Sara and sara counted as two people.
  2. The history store. One or two members in the middle of the range handle reading the CSV into memory and writing new rows back. The useful idea here is storing each pair as a frozenset of two names so that the pair reads the same in either order, then keeping a count per pair rather than just a yes or no. Counts let the tool prefer the pair that has met once over the pair that has met four times.
  3. The pairing itself. This is the hard part and it belongs to whoever wants a fight. A first version sorts all possible pairs of the people present by how often they have met and takes them greedily, which is twenty lines and usually good enough. The flaw appears quickly: a greedy pass can paint itself into a corner and leave two people who have already met six times. Fixing that needs either a retry loop with a different random order or a proper search that backs out of a bad choice.
  4. Output and the odd one out. Printing six pairs is easy, so give this job more scope: an odd number of people present, which means one group of three rather than someone sitting alone, plus a short report of who has not yet worked with whom. The report is what convinces a sceptical club that the tool does something a shuffle does not.

With six to ten students, those four jobs fill five sessions of about seventy five minutes, plus one session to join them up. Our write up on planning a six week coding club project has the session by session shape we use for projects of this size.

Why I steer groups away from random shuffling

Nearly every club does what we did, and most advice online says the same: shuffle the list and pair neighbours. It is two lines of Python and it is defensible. I now think it is the wrong starting point for this project, for a reason worth arguing about in front of the students.

Ask them to estimate how long random pairing takes to repeat. Ten members, five pairs a night: by the third session you should expect a repeat, and by the sixth most members have at least one duplicate partner while several pairs have still never happened. You can test that claim rather than taking my word for it, and simulating 1,000 terms of random pairing to count duplicates makes an excellent side task for a fast finisher.

The second argument against shuffling is pedagogical. A random pairing takes no account of who is learning what, and the pairing that helps a club most often puts a confident member with a newer one on purpose. Once the tool holds a skill band per person, even a rough one on a scale of one to three, you can add a rule that no two band three members pair up while any band one member is unpaired. That single constraint changed the feel of our sessions more than the repeat avoidance did.

I will be honest about the limit here. A tool cannot tell you that two particular students should not sit together, and it will cheerfully pair people who do not get on. We keep a short exclusion list that only the mentors can edit, and I would rather have that than pretend the program knows the room. There is more on that side of things in our notes on training volunteer mentors.

Where it gets tested properly

The honest test is a simulated term. Feed the finished tool twelve names and twelve weeks of made up attendance, with a quarter of people absent at random each week, then count how many distinct pairs the term produced out of the 66 possible. A greedy version typically lands somewhere around 45 to 52. A version with retries reaches the high fifties. Nobody hits 66 with patchy attendance, and understanding why not is the real lesson.

Keep the whole thing in one repository with everyone committing to it, since four parts joining in a final session is exactly the situation that teaches why branches exist. We run that alongside the project using the approach in our guide to a Git group project.

One last thing I would insist on: use the tool at the club the week after it is finished, and let the students watch the pairs they generated appear on the whiteboard. A program that gets used stops feeling like homework.

FAQ

How much Python does a member need to join in?

For the roster and output jobs, loops, lists and reading a file is enough, which is a few weeks of study. The pairing job wants someone comfortable with dictionaries and functions.

Can this run without storing a file?

It can, but then it forgets everything between sessions, which removes the entire point. The CSV is the memory, and writing it is a good reason to teach file handling early.

What if the club is small, say six people?

Six people means fifteen possible pairs and three pairs a night, so a full cycle takes five sessions. The project works the same, and the test at the end becomes easier to verify by hand.

Is a round robin library easier than writing the algorithm?

Easier, yes, and the wrong trade for a club. The scheduling code is the only genuinely interesting part of the program, so handing it to a library leaves the stronger members with nothing to do.

BN
Bartholomew Ng

Bartholomew taught maths for years before switching to teaching Python. He writes about the basics of the language and about teaching code without drowning learners in syntax.

More posts by Bartholomew

More in Club Projects

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto