Further refinements to the examples and recipes for the random module

Doc/library/random.rst

@@ -322,36 +322,49 @@ change across Python versions, but two aspects are guaranteed not to change:
 Examples and Recipes
 --------------------
 
-Basic usage::
+Basic examples::
 
-   >>> random.random()                      # Random float x, 0.0 <= x < 1.0
+   >>> random()                             # Random float:  0.0 <= x < 1.0
    0.37444887175646646
 
-   >>> random.uniform(1, 10)                # Random float x, 1.0 <= x < 10.0
-   1.1800146073117523
+   >>> uniform(2, 10)                       # Random float:  2.0 <= x < 10.0
+   3.1800146073117523
 
-   >>> random.randrange(10)                 # Integer from 0 to 9
+   >>> expovariate(1/5)                     # Interval between arrivals averaging 5 seconds
+   5.148957571865031
+
+   >>> randrange(10)                        # Integer from 0 to 9
    7
 
-   >>> random.randrange(0, 101, 2)          # Even integer from 0 to 100
+   >>> randrange(0, 101, 2)                 # Even integer from 0 to 100 inclusive
    26
 
-   >>> random.choice('abcdefghij')          # Single random element
+   >>> choice('abcdefghij')                 # Single random element from a sequence
    'c'
 
-   >>> deck = ['jack', 'queen', 'king', 'ace']
-   >>> shuffle(deck)
+   >>> deck = 'ace two three four'.split()
+   >>> shuffle(deck)                        # Shuffle a list
    >>> deck
-   ['king', 'queen', 'ace', 'jack']
+   ['four', 'two', 'ace', 'three']
+
+   >>> sample([10, 20, 30, 40, 50], k=4)    # Four samples without replacement
+   [40, 10, 50, 30]
 
-   >>> random.sample([1, 2, 3, 4, 5], k=3)  # Three samples without replacement
-   [4, 1, 5]
+Simulations::
 
-   >>>                                      # Six weighted samples with replacement
+   # Six roulette wheel spins (weighted sampling with replacement)
    >>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
    ['red', 'green', 'black', 'black', 'red', 'black']
 
-   # Probability of getting 5 or more heads from 7 spins
+   # Deal 20 cards without replacement from a deck of 52
+   # playing cards and determine the proportion of cards
+   # with a ten-value (i.e. a ten, jack, queen, or king).
+   >>> deck = collections.Counter(tens=16, low_cards=36)
+   >>> seen = sample(list(deck.elements()), k=20)
+   >>> print(seen.count('tens') / 20)
+   0.15
+
+   # Estimate the probability of getting 5 or more heads from 7 spins
    # of a biased coin that settles on heads 60% of the time.
    >>> n = 10000
    >>> cw = [0.60, 1.00]
@@ -360,8 +373,8 @@ Basic usage::
 
 Example of `statistical bootstrapping
 <https://en.wikipedia.org/wiki/Bootstrapping_(statistics)>`_ using resampling
-with replacement to estimate a confidence interval for the mean of a small
-sample of size five::
+with replacement to estimate a confidence interval for the mean of a sample of
+size five::
 
    # http://statistics.about.com/od/Applications/a/Example-Of-Bootstrapping.htm
    from statistics import mean