py-randomizer 0.0.3

A small library that simplifies randomly selecting things from lists.

Randomizer

A small library that simplifies randomly selecting things from lists.

RandomList

RandomList 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 Definition

The simplest way of defining a RandomList is with a flat list:

from randomizer import RandomList

flavor_list = RandomList(['vanilla', 'chocolate', 'strawberry'])
random_flavor = flavor_list.get_random()

Each item in a RandomList is given a probability value, which is by default set to 1. The odds of an item being selected are equal to item probability / sum of all probabilities.

Since each item in this RandomList is given a probability of 1, they each have an equal chance of being returned by get_random().

Custom Probabilities

You can declare your own probability values for the items in your RandomList by using a list of dictionaries. Each dictionary must have an item key and a probability key, as follows:

from randomizer import RandomList

flavor_list = RandomList([
    {
      "item": "vanilla",
      "probability": 3
    },
    {
      "item": "chocolate",
      "probability": 11
    }
])
random_flavor = flavor_list.get_random()

In this example, vanilla has a probability of 3, while chocolate has 11. The sum of all the probability values is 14, meaning vanilla has a 3/14 chance of being returned (~21%), while chocolate has 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:

from randomizer import RandomList

flavor_list = RandomList([
    {
      "item": "vanilla",
      "probability": 20
    },
    {
      "item": "chocolate",
      "probability": 80
    }
])
random_flavor = flavor_list.get_random()

Now vanilla has a 20/100 (20%) chance of being returned, while chocolate has 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 RandomLists

You can view the contents of your RandomList in JSON format with the get_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 use get_items():

print(flavor_list.get_items())
# Output:
# ['vanilla', 'chocolate']

You can also view the current number of items in your RandomList with item_count():

print(flavor_list.item_count())
# Output: 2

Diminishing Probability

RandomLists 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 the get_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 getting vanilla. When we select an item with get_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
# }

Running get_random_and_remove() returned vanilla, and also decreased the probability for vanilla from 6 to 5. The next time we run get_random_and_remove(), we will have a 1/5 chance of getting vanilla.

When the probability of an item hits 0, it is removed from the RandomList and can no longer be returned.

Resetting RandomLists

You can return a RandomList to its initial state with reset_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.

RandomGroups

Perhaps 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".

from randomizer import RandomList, RandomGroup

flavor_group = RandomGroup([
  {
    "list": common_flavor_list,
    "probability": 70
  },
  {
    "list": uncommon_flavor_list,
    "probability": 30
  }
])
random_food = food_group.get_random()

When we call flavor_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 its RandomList.get_random().

In this example, we have a 30% chance of selecting the uncommon_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 call flavor_group.get_random(), "pistachio", "mocha chip", and "praline pecan" each have a 10% chance of being returned.