From: Raymond Hettinger <python@rcn.com>
Date: Thu, 2 Dec 2010 02:41:33 +0000 (+0000)
Subject: Add an example to the random docs.
X-Git-Tag: v3.2b1~133
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2fdc7b1f759e557c57d16e91b9ac53f2b441c0be;p=python

Add an example to the random docs.
---

diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index 7aa08942d8..10c2f3c561 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -295,3 +295,29 @@ change across Python versions, but two aspects are guaranteed not to change:
 
 * The generator's :meth:`random` method will continue to produce the same
   sequence when the compatible seeder is given the same seed.
+
+
+.. _random-examples:
+
+Examples and Recipes
+====================
+
+A common task is to make a :func:`random.choice` with weighted probababilites.
+
+If the weights are small integer ratios, a simple technique is to build a sample
+population with repeats::
+
+    >>> weighted_choices = [('Red', 3), ('Blue', 2), ('Yellow', 1), ('Green', 4)]
+    >>> population = [val for val, cnt in weighted_choices for i in range(cnt)]
+    >>> random.choice(population)
+    'Green'
+
+A more general approach is to arrange the weights in a cumulative probability
+distribution with :func:`itertools.accumulate`, and then locate the random value
+with :func:`bisect.bisect`::
+
+    >>> choices, weights = zip(*weighted_choices)
+    >>> cumdist = list(itertools.accumulate(weights))
+    >>> x = random.random() * cumdist[-1]
+    >>> choices[bisect.bisect(cumdist, x)]
+    'Blue'