[3.12] More informative docstrings in the random module (gh-109745) (#109905)

More informative docstrings in the random module (gh-109745)
(cherry picked from commit 19bf398)

Co-authored-by: Raymond Hettinger <[email protected]>

Author: miss-islington

Lib/random.py

@@ -492,7 +492,14 @@ def choices(self, population, weights=None, *, cum_weights=None, k=1):
     ## -------------------- real-valued distributions  -------------------
 
     def uniform(self, a, b):
-        "Get a random number in the range [a, b) or [a, b] depending on rounding."
+        """Get a random number in the range [a, b) or [a, b] depending on rounding.
+
+        The mean (expected value) and variance of the random variable are:
+
+            E[X] = (a + b) / 2
+            Var[X] = (b - a) ** 2 / 12
+
+        """
         return a + (b - a) * self.random()
 
     def triangular(self, low=0.0, high=1.0, mode=None):
@@ -503,6 +510,11 @@ def triangular(self, low=0.0, high=1.0, mode=None):
 
         http://en.wikipedia.org/wiki/Triangular_distribution
 
+        The mean (expected value) and variance of the random variable are:
+
+            E[X] = (low + high + mode) / 3
+            Var[X] = (low**2 + high**2 + mode**2 - low*high - low*mode - high*mode) / 18
+
         """
         u = self.random()
         try:
@@ -593,12 +605,15 @@ def expovariate(self, lambd=1.0):
         positive infinity if lambd is positive, and from negative
         infinity to 0 if lambd is negative.
 
-        """
-        # lambd: rate lambd = 1/mean
-        # ('lambda' is a Python reserved word)
+        The mean (expected value) and variance of the random variable are:
+
+            E[X] = 1 / lambd
+            Var[X] = 1 / lambd ** 2
 
+        """
         # we use 1-random() instead of random() to preclude the
         # possibility of taking the log of zero.
+
         return -_log(1.0 - self.random()) / lambd
 
     def vonmisesvariate(self, mu, kappa):
@@ -654,8 +669,12 @@ def gammavariate(self, alpha, beta):
           pdf(x) =  --------------------------------------
                       math.gamma(alpha) * beta ** alpha
 
+        The mean (expected value) and variance of the random variable are:
+
+            E[X] = alpha * beta
+            Var[X] = alpha * beta ** 2
+
         """
-        # alpha > 0, beta > 0, mean is alpha*beta, variance is alpha*beta**2
 
         # Warning: a few older sources define the gamma distribution in terms
         # of alpha > -1.0
@@ -714,6 +733,11 @@ def betavariate(self, alpha, beta):
         Conditions on the parameters are alpha > 0 and beta > 0.
         Returned values range between 0 and 1.
 
+        The mean (expected value) and variance of the random variable are:
+
+            E[X] = alpha / (alpha + beta)
+            Var[X] = alpha * beta / ((alpha + beta)**2 * (alpha + beta + 1))
+
         """
         ## See
         ## http://mail.python.org/pipermail/python-bugs-list/2001-January/003752.html
@@ -766,6 +790,11 @@ def binomialvariate(self, n=1, p=0.5):
 
         Returns an integer in the range:   0 <= X <= n
 
+        The mean (expected value) and variance of the random variable are:
+
+            E[X] = n * p
+            Var[x] = n * p * (1 - p)
+
         """
         # Error check inputs and handle edge cases
         if n < 0: