Package: py-randomizer
RandomizerA small library that simplifies randomly selecting things from lists.RandomListRandomList is a class that collects together the pool of items that you want to be able to randomly select from. You can think of it as the "hat" from which your options will be drawn.Simple DefinitionThe simplest way of defining a RandomList is with a flat list:fromrandomizerimportRandomListflavor_list=RandomList(['vanilla','chocolate','strawberry'])random_flavor=flavor_list.get_random()Each item in a RandomList is given aprobabilityvalue, which is by default set to1. The odds of an item being selected are equal toitem probability / sum of all probabilities.Since each item in this RandomList is given a probability of1, they each have an equal chance of being returned byget_random().Custom ProbabilitiesYou can declare your own probability values for the items in your RandomList by using a list of dictionaries. Each dictionary must have anitemkey and aprobabilitykey, as follows:fromrandomizerimportRandomListflavor_list=RandomList([{"item":"vanilla","probability":3},{"item":"chocolate","probability":11}])random_flavor=flavor_list.get_random()In this example,vanillahas a probability of3, whilechocolatehas11. The sum of all the probability values is14, meaningvanillahas a 3/14 chance of being returned (~21%), whilechocolatehas 11/14 (~79%).If you want to work directly with percent values as inputs, just make sure that the sum of all probabilities equals 100, as shown below:fromrandomizerimportRandomListflavor_list=RandomList([{"item":"vanilla","probability":20},{"item":"chocolate","probability":80}])random_flavor=flavor_list.get_random()Nowvanillahas a 20/100 (20%) chance of being returned, whilechocolatehas an 80/100 (80%) chance. But you can rest assured that if your total probability ends up above or below 100, no errors will occur.Viewing RandomListsYou can view the contents of your RandomList in JSON format with theget_contents()method.print(flavor_list.get_contents())# Output:# {#   "item": "vanilla",#   "probability": 20# },# {#   "item": "chocolate",#   "probability": 80# }get_contents()will return the full contents of your RandomList, including any probability values. If you only want to see a list of the items in the RandomList, you can useget_items():print(flavor_list.get_items())# Output:# ['vanilla', 'chocolate']You can also view the current number of items in your RandomList withitem_count():print(flavor_list.item_count())# Output: 2Diminishing ProbabilityRandomLists can also operate like “raffle buckets”. Imagine each “probability” point is a ticket that’s been entered into a raffle -- whenever an item is selected with theget_random_and_remove()method, one of its “tickets” is removed, and its probability is decreased by one.In this example, there are a total of six “tickets”. We begin with a 1/6 chance of gettingvanilla. When we select an item withget_random_and_remove(), this number will change:flavor_list=RandomList([{"item":"vanilla","probability":5},{"item":"chocolate","probability":1}])random_flavor=flavor_list.get_random_and_remove()print(random_flavor)# Output: "vanilla"print(flavor_list.view_contents())# Output:# {#   "item": "vanilla",#   "probability": 4# },# {#   "item": "chocolate",#   "probability": 1# }Runningget_random_and_remove()returnedvanilla, and also decreased the probability forvanillafrom6to5. The next time we runget_random_and_remove(), we will have a 1/5 chance of gettingvanilla.When the probability of an item hits 0, it is removed from the RandomList and can no longer be returned.Resetting RandomListsYou can return a RandomList to its initial state withreset_contents():flavor_list=RandomList(['vanilla','chocolate','strawberry'])random_flavor=flavor_list.get_random_and_remove()print(random_flavor)# Output: "vanilla"print(flavor_list.view_items())# Output: ["chocolate", "strawberry"]flavor_list.reset_contents()print(flavor_list.view_items())# Output: ["vanilla", "chocolate", "strawberry"]reset_contents()sets all probabilities to their initial values and replaces any items that may have been removed.RandomGroupsPerhaps you don’t just want to randomly pull from one list -- maybe you want a chance for your item to come from several different lists. You can do this by defining a RandomGroup, which is essentially a "list of lists".fromrandomizerimportRandomList,RandomGroupflavor_group=RandomGroup([{"list":common_flavor_list,"probability":70},{"list":uncommon_flavor_list,"probability":30}])random_food=food_group.get_random()When we callflavor_group.get_random(), first it selects a RandomList based on the given probability, then it looks inside that RandomList and returns an item by calling itsRandomList.get_random().In this example, we have a 30% chance of selecting theuncommon_flavor_list. Let’s assume it looks like this:uncommon_flavor_list=RandomList(["pistachio","mocha chip","praline pecan"])Once this RandomList is selected,uncommon_flavor_list.get_random()will run. In this case, each item in this list has a default probability of 1/3.So ultimately, when we callflavor_group.get_random(),"pistachio","mocha chip", and"praline pecan"each have a 10% chance of being returned.