[Python-checkins] cpython (merge 3.6 -> default): merge

[raymond.hettinger]

https://hg.python.org/cpython/rev/53f5e16695d0
changeset:   105179:53f5e16695d0
parent:      105177:8fab4ba536fc
parent:      105178:3e6f23fd0c34
user:        Raymond Hettinger <python at rcn.com>
date:        Thu Nov 17 01:50:16 2016 -0800
summary:
  merge

files:
  Doc/library/random.rst |  22 ++++++++++++++--------
  1 files changed, 14 insertions(+), 8 deletions(-)


diff --git a/Doc/library/random.rst b/Doc/library/random.rst
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -152,13 +152,19 @@
 
 .. function:: shuffle(x[, random])
 
-   Shuffle the sequence *x* in place. The optional argument *random* is a
-   0-argument function returning a random float in [0.0, 1.0); by default, this is
-   the function :func:`.random`.
+   Shuffle the sequence *x* in place.
 
-   Note that for even rather small ``len(x)``, the total number of permutations of
-   *x* is larger than the period of most random number generators; this implies
-   that most permutations of a long sequence can never be generated.
+   The optional argument *random* is a 0-argument function returning a random
+   float in [0.0, 1.0); by default, this is the function :func:`.random`.
+
+   To shuffle an immutable sequence and return a new shuffled list, use
+   ``sample(x, k=len(x))`` instead.
+
+   Note that even for small ``len(x)``, the total number of permutations of *x*
+   can quickly grow larger than the period of most random number generators.
+   This implies that most permutations of a long sequence can never be
+   generated.  For example, a sequence of length 2080 is the largest that
+   can fit within the period of the Mersenne Twister random number generator.
 
 
 .. function:: sample(population, k)
@@ -175,9 +181,9 @@
    Members of the population need not be :term:`hashable` or unique.  If the population
    contains repeats, then each occurrence is a possible selection in the sample.
 
-   To choose a sample from a range of integers, use an :func:`range` object as an
+   To choose a sample from a range of integers, use a :func:`range` object as an
    argument.  This is especially fast and space efficient for sampling from a large
-   population:  ``sample(range(10000000), 60)``.
+   population:  ``sample(range(10000000), k=60)``.
 
    If the sample size is larger than the population size, a :exc:`ValueError`
    is raised.

-- 
Repository URL: https://hg.python.org/cpython