Rename weighted_choices() to just choices()

Doc/library/random.rst

@@ -124,7 +124,7 @@ Functions for sequences:
    Return a random element from the non-empty sequence *seq*. If *seq* is empty,
    raises :exc:`IndexError`.
 
-.. function:: weighted_choices(k, population, weights=None, *, cum_weights=None)
+.. function:: choices(k, population, weights=None, *, cum_weights=None)
 
    Return a *k* sized list of elements chosen from the *population* with replacement.
    If the *population* is empty, raises :exc:`IndexError`.

Lib/random.py

@@ -51,7 +51,7 @@ __all__ = ["Random","seed","random","uniform","randint","choice","sample",
            "randrange","shuffle","normalvariate","lognormvariate",
            "expovariate","vonmisesvariate","gammavariate","triangular",
            "gauss","betavariate","paretovariate","weibullvariate",
-           "getstate","setstate", "getrandbits", "weighted_choices",
+           "getstate","setstate", "getrandbits", "choices",
            "SystemRandom"]
 
 NV_MAGICCONST = 4 * _exp(-0.5)/_sqrt(2.0)
@@ -337,7 +337,7 @@ class Random(_random.Random):
                 result[i] = population[j]
         return result
 
-    def weighted_choices(self, k, population, weights=None, *, cum_weights=None):
+    def choices(self, k, population, weights=None, *, cum_weights=None):
         """Return a k sized list of population elements chosen with replacement.
 
         If the relative weights or cumulative weights are not specified,
@@ -749,7 +749,7 @@ choice = _inst.choice
 randrange = _inst.randrange
 sample = _inst.sample
 shuffle = _inst.shuffle
-weighted_choices = _inst.weighted_choices
+choices = _inst.choices
 normalvariate = _inst.normalvariate
 lognormvariate = _inst.lognormvariate
 expovariate = _inst.expovariate

Lib/test/test_random.py

@@ -142,8 +142,8 @@ class TestBasicOps:
     def test_sample_on_dicts(self):
         self.assertRaises(TypeError, self.gen.sample, dict.fromkeys('abcdef'), 2)
 
-    def test_weighted_choices(self):
+    def test_choices(self):
-        weighted_choices = self.gen.weighted_choices
+        choices = self.gen.choices
         data = ['red', 'green', 'blue', 'yellow']
         str_data = 'abcd'
         range_data = range(4)
@@ -151,63 +151,63 @@ class TestBasicOps:
 
         # basic functionality
         for sample in [
-            weighted_choices(5, data),
+            choices(5, data),
-            weighted_choices(5, data, range(4)),
+            choices(5, data, range(4)),
-            weighted_choices(k=5, population=data, weights=range(4)),
+            choices(k=5, population=data, weights=range(4)),
-            weighted_choices(k=5, population=data, cum_weights=range(4)),
+            choices(k=5, population=data, cum_weights=range(4)),
         ]:
             self.assertEqual(len(sample), 5)
             self.assertEqual(type(sample), list)
             self.assertTrue(set(sample) <= set(data))
 
         # test argument handling
-        with self.assertRaises(TypeError):                                        # missing arguments
+        with self.assertRaises(TypeError):                               # missing arguments
-            weighted_choices(2)
+            choices(2)
 
-        self.assertEqual(weighted_choices(0, data), [])                           # k == 0
+        self.assertEqual(choices(0, data), [])                           # k == 0
-        self.assertEqual(weighted_choices(-1, data), [])                          # negative k behaves like ``[0] * -1``
+        self.assertEqual(choices(-1, data), [])                          # negative k behaves like ``[0] * -1``
         with self.assertRaises(TypeError):
-            weighted_choices(2.5, data)                                           # k is a float
+            choices(2.5, data)                                           # k is a float
 
-        self.assertTrue(set(weighted_choices(5, str_data)) <= set(str_data))      # population is a string sequence
+        self.assertTrue(set(choices(5, str_data)) <= set(str_data))      # population is a string sequence
-        self.assertTrue(set(weighted_choices(5, range_data)) <= set(range_data))  # population is a range
+        self.assertTrue(set(choices(5, range_data)) <= set(range_data))  # population is a range
         with self.assertRaises(TypeError):
-            weighted_choices(2.5, set_data)                                       # population is not a sequence
+            choices(2.5, set_data)                                       # population is not a sequence
 
-        self.assertTrue(set(weighted_choices(5, data, None)) <= set(data))        # weights is None
+        self.assertTrue(set(choices(5, data, None)) <= set(data))        # weights is None
-        self.assertTrue(set(weighted_choices(5, data, weights=None)) <= set(data))
+        self.assertTrue(set(choices(5, data, weights=None)) <= set(data))
         with self.assertRaises(ValueError):
-            weighted_choices(5, data, [1,2])                                      # len(weights) != len(population)
+            choices(5, data, [1,2])                                      # len(weights) != len(population)
         with self.assertRaises(IndexError):
-            weighted_choices(5, data, [0]*4)                                      # weights sum to zero
+            choices(5, data, [0]*4)                                      # weights sum to zero
         with self.assertRaises(TypeError):
-            weighted_choices(5, data, 10)                                         # non-iterable weights
+            choices(5, data, 10)                                         # non-iterable weights
         with self.assertRaises(TypeError):
-            weighted_choices(5, data, [None]*4)                                   # non-numeric weights
+            choices(5, data, [None]*4)                                   # non-numeric weights
         for weights in [
                 [15, 10, 25, 30],                                                 # integer weights
                 [15.1, 10.2, 25.2, 30.3],                                         # float weights
                 [Fraction(1, 3), Fraction(2, 6), Fraction(3, 6), Fraction(4, 6)], # fractional weights
                 [True, False, True, False]                                        # booleans (include / exclude)
         ]:
-            self.assertTrue(set(weighted_choices(5, data, weights)) <= set(data))
+            self.assertTrue(set(choices(5, data, weights)) <= set(data))
 
         with self.assertRaises(ValueError):
-            weighted_choices(5, data, cum_weights=[1,2])                          # len(weights) != len(population)
+            choices(5, data, cum_weights=[1,2])                          # len(weights) != len(population)
         with self.assertRaises(IndexError):
-            weighted_choices(5, data, cum_weights=[0]*4)                          # cum_weights sum to zero
+            choices(5, data, cum_weights=[0]*4)                          # cum_weights sum to zero
         with self.assertRaises(TypeError):
-            weighted_choices(5, data, cum_weights=10)                             # non-iterable cum_weights
+            choices(5, data, cum_weights=10)                             # non-iterable cum_weights
         with self.assertRaises(TypeError):
-            weighted_choices(5, data, cum_weights=[None]*4)                       # non-numeric cum_weights
+            choices(5, data, cum_weights=[None]*4)                       # non-numeric cum_weights
         with self.assertRaises(TypeError):
-            weighted_choices(5, data, range(4), cum_weights=range(4))             # both weights and cum_weights
+            choices(5, data, range(4), cum_weights=range(4))             # both weights and cum_weights
         for weights in [
                 [15, 10, 25, 30],                                                 # integer cum_weights
                 [15.1, 10.2, 25.2, 30.3],                                         # float cum_weights
                 [Fraction(1, 3), Fraction(2, 6), Fraction(3, 6), Fraction(4, 6)], # fractional cum_weights
         ]:
-            self.assertTrue(set(weighted_choices(5, data, cum_weights=weights)) <= set(data))
+            self.assertTrue(set(choices(5, data, cum_weights=weights)) <= set(data))
 
     def test_gauss(self):
         # Ensure that the seed() method initializes all the hidden state.  In

Misc/NEWS

@@ -101,7 +101,7 @@ Library
 - Issue #27691: Fix ssl module's parsing of GEN_RID subject alternative name
   fields in X.509 certs.
 
-- Issue #18844: Add random.weighted_choices().
+- Issue #18844: Add random.choices().
 
 - Issue #25761: Improved error reporting about truncated pickle data in
   C implementation of unpickler.  UnpicklingError is now raised instead of