added docstrings

prob_functions.py

@@ -4,19 +4,28 @@
 
 @lru_cache(maxsize=None)
 def bino(a, b):
+    """
+    computes the binomial coefficient (a choose b)
+    """
     if b > a:
         return 0
     return fac(a) // (fac(a - b) * fac(b))
 
 
 @lru_cache(maxsize=None)
 def hypogeo(N1, n1, N2, n2, N3, n3):
+    """
+    computes hypergeometric probability in three variables
+    """
     numerator = bino(N1, n1) * bino(N2, n2) * bino(N3, n3)
     denominator = bino(N1 + N2 + N3, n1 + n2 + n3)
     return numerator / denominator
 
 
 def hand_gen(bazaars, powders, other, hand_size=7):
+    """
+    generates all possible opening hands given makeup of the deck
+    """
     for i in range(bazaars + 1):
         for j in range(powders + 1):
             for k in range(other + 1):
@@ -25,6 +34,10 @@ def hand_gen(bazaars, powders, other, hand_size=7):
 
 
 def powder_gen(powders_in_hand, other_in_hand, to_put_under):
+    """
+    generates all possible ways to put cards from hand onto bottom of library while mulling, leaving at least one powder
+    assumes that there are no bazaar in hand as the hand would be kept
+    """
     for i in range(powders_in_hand):
         for j in range(other_in_hand + 1):
             if i + j == to_put_under:
@@ -41,6 +54,10 @@ def prob_of_keep(bazaars_in_hand,
                  powders_on_bottom=0,
                  other_on_bottom=0,
                  mull_count=0):
+    """
+    computes the probability that a given hand will result in a keep or will mulligan into a hand that will keep
+    """
+
     # make sure that we're never trying to draw from a library which is too small
     if bazaars_in_deck + powders_in_deck + other_in_deck < 7:
         raise Exception('Not enough cards in library')
@@ -83,7 +100,8 @@ def prob_of_keep(bazaars_in_hand,
         powders_left = powders_in_deck - powders_in_hand
         other_left = other_in_deck - other_in_hand
         powder_mull = 0
-        for i, j, k in hand_gen(bazaars_in_deck, powders_left, other_left, 6 - mull_count):
+        for i, j, k in hand_gen(bazaars_in_deck, powders_left, other_left,
+                                6 - mull_count):
             prob = hypogeo(bazaars_in_deck, i, powders_left, j, other_left, k)
             prob *= prob_of_keep(i, bazaars_in_deck, j, powders_left, k,
                                  other_left,
@@ -97,6 +115,9 @@ def prob_of_keep(bazaars_in_hand,
 
 
 def prob_of_good_hand(bazaars=4, powders=4, other=52):
+    """
+    computes the overall probability of a keep for all possible hands
+    """
     total = 0
     for i, j, k in hand_gen(bazaars, powders, other):
         prob = hypogeo(bazaars, i, powders, j, other, k)
@@ -106,6 +127,9 @@ def prob_of_good_hand(bazaars=4, powders=4, other=52):
 
 
 def advice_string(key, mull_count):
+    """
+    parses the mulligan decision into a readable string
+    """
     if key == 'regular':
         return 'Take a regular mulligan.'
     if mull_count == 0:
@@ -122,6 +146,9 @@ def action_to_take(powders_in_hand,
                    powders_on_bottom=0,
                    other_on_bottom=0,
                    mull_count=0):
+    """
+    given a hand, advises on how to proceed
+    """
     mull_dict = dict()
     regular_mull = 0
     for i, j, k in hand_gen(4, powders_in_deck + powders_on_bottom,