Let's say one is a computer programmer and let's say one's wife (or roommate; or significant other) does social science research (a totally hypothetical scenario of course). When doing social science research one needs to create randomized groups of participants.
So in a group you might be testing a variable X and you need to divide the group in half to test that variable with a number of control subjects. In this scenario, one needs to create groups A and B (or 1 and 2) such that there are the same number of A and B in a given set.
Now normally when generating random numbers you can just generate an arbitrary set of random numbers. But if you need a set of 10 numbers with 5 1's and 5 2's then that's a different problem. You could of course generate a set and test to make sure it's evenly distributed and then throw it away if it doesn't meet this constraint. That of course is an inefficient way of generating your sets because you would likely have to throw a lot of them away.
The solution to this conundrum is to use random numbers not to create your set, but to shuffle it. Luckily other smart people have proven ways to do this already. The Fisher-Yates shuffle is the technique that I used.
Basically the Fisher-Yates shuffle shuffle picks a random item and puts it at the end of the list by swapping the end with the randomly selected item. It then continues with the 'unpicked' numbers and puts them at the end of the unpicked set until it reaches the beginning of the list. Once it's traveled through, you have a randomly sorted set.
That's fine if you're a programmer and want to run python from the command line and change your items set if you need a different size, etc. But if you want an end-user who's not a programmer to use it, you better come up with something a bit configurable. So I need to allow for some variation to the sets that will be generated and shuffled.
Based on this information I created a simple class that would allow you to specify 3 properties that would define the random sets to generate: blocks, the number of individual sets; size, the number of numbers in each block; and groups, the number of variants within each block. So now you could generate a set of 10 blocks, with 12 numbers in each containing 1, 2, and 3 evenly distributed (i.e. 4 of each number).
Finally to wrap the shuffler in a nice command-line interface I created a simple specialization of the Shuffler class that would take command line arguments to generate blocks of specific properties.