cpython-lru_cache-weakref: Doc/library/random.rst annotate

annotate Doc/library/random.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	2291aff20a05
children	48b618a9ad10

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 :mod:`random` --- Generate pseudo-random numbers
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 ================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. module:: random
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 :synopsis: Generate pseudo-random numbers with various common distributions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
71952 b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 65995 diff changeset	7 Source code: :source:`Lib/random.py`
b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 65995 diff changeset	8
b5674229d0f9 Backport source links from 3.x. Éric Araujo <merwok@netwok.org> parents: 65995 diff changeset	9 --------------
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 This module implements pseudo-random number generators for various
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 distributions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 For integers, uniform selection from a range. For sequences, uniform selection
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 of a random element, a function to generate a random permutation of a list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 in-place, and a function for random sampling without replacement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 On the real line, there are functions to compute uniform, normal (Gaussian),
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 lognormal, negative exponential, gamma, and beta distributions. For generating
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 distributions of angles, the von Mises distribution is available.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 Almost all module functions depend on the basic function :func:`random`, which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 generates a random float uniformly in the semi-open range [0.0, 1.0). Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 uses the Mersenne Twister as the core generator. It produces 53-bit precision
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 floats and has a period of 2\\19937-1. The underlying implementation in C is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 both fast and threadsafe. The Mersenne Twister is one of the most extensively
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 tested random number generators in existence. However, being completely
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 deterministic, it is not suitable for all purposes, and is completely unsuitable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 for cryptographic purposes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 The functions supplied by this module are actually bound methods of a hidden
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 instance of the :class:`random.Random` class. You can instantiate your own
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 instances of :class:`Random` to get generators that don't share state. This is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 especially useful for multi-threaded programs, creating a different instance of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 :class:`Random` for each thread, and using the :meth:`jumpahead` method to make
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 it likely that the generated sequences seen by each thread don't overlap.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 Class :class:`Random` can also be subclassed if you want to use a different
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 basic generator of your own devising: in that case, override the :meth:`random`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 :meth:`seed`, :meth:`getstate`, :meth:`setstate` and :meth:`jumpahead` methods.
48100 40e949a68344 getrandombits is actually getrandbits Benjamin Peterson <benjamin@python.org> parents: 46046 diff changeset	41 Optionally, a new generator can supply a :meth:`getrandbits` method --- this
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 allows :meth:`randrange` to produce selections over an arbitrarily large range.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 .. versionadded:: 2.4
48100 40e949a68344 getrandombits is actually getrandbits Benjamin Peterson <benjamin@python.org> parents: 46046 diff changeset	45 the :meth:`getrandbits` method.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 As an example of subclassing, the :mod:`random` module provides the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 :class:`WichmannHill` class that implements an alternative generator in pure
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 Python. The class provides a backward compatible way to reproduce results from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 earlier versions of Python, which used the Wichmann-Hill algorithm as the core
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 generator. Note that this Wichmann-Hill generator can no longer be recommended:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 its period is too short by contemporary standards, and the sequence generated is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 known to fail some stringent randomness tests. See the references below for a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 recent variant that repairs these flaws.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 .. versionchanged:: 2.3
58992 ab6fd9e45436 #7076: mention SystemRandom class near start of the module docs; reword change description for clarity. Noted by Shawn Ligocki. Andrew M. Kuchling <amk@amk.ca> parents: 54708 diff changeset	57 MersenneTwister replaced Wichmann-Hill as the default generator.
ab6fd9e45436 #7076: mention SystemRandom class near start of the module docs; reword change description for clarity. Noted by Shawn Ligocki. Andrew M. Kuchling <amk@amk.ca> parents: 54708 diff changeset	58
ab6fd9e45436 #7076: mention SystemRandom class near start of the module docs; reword change description for clarity. Noted by Shawn Ligocki. Andrew M. Kuchling <amk@amk.ca> parents: 54708 diff changeset	59 The :mod:`random` module also provides the :class:`SystemRandom` class which
ab6fd9e45436 #7076: mention SystemRandom class near start of the module docs; reword change description for clarity. Noted by Shawn Ligocki. Andrew M. Kuchling <amk@amk.ca> parents: 54708 diff changeset	60 uses the system function :func:`os.urandom` to generate random numbers
ab6fd9e45436 #7076: mention SystemRandom class near start of the module docs; reword change description for clarity. Noted by Shawn Ligocki. Andrew M. Kuchling <amk@amk.ca> parents: 54708 diff changeset	61 from sources provided by the operating system.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 Bookkeeping functions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 .. function:: seed([x])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 Initialize the basic random number generator. Optional argument x can be any
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 42603 diff changeset	69 :term:`hashable` object. If x is omitted or ``None``, current system time is used;
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 current system time is also used to initialize the generator when the module is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 first imported. If randomness sources are provided by the operating system,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 they are used instead of the system time (see the :func:`os.urandom` function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 for details on availability).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 formerly, operating system resources were not used.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 .. function:: getstate()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 Return an object capturing the current internal state of the generator. This
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 object can be passed to :func:`setstate` to restore the state.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 .. versionadded:: 2.1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
44122 97210d863d12 Issue #1727780: Support loading pickles of random.Random objects created Martin v. Löwis <martin@v.loewis.de> parents: 43849 diff changeset	85 .. versionchanged:: 2.6
97210d863d12 Issue #1727780: Support loading pickles of random.Random objects created Martin v. Löwis <martin@v.loewis.de> parents: 43849 diff changeset	86 State values produced in Python 2.6 cannot be loaded into earlier versions.
97210d863d12 Issue #1727780: Support loading pickles of random.Random objects created Martin v. Löwis <martin@v.loewis.de> parents: 43849 diff changeset	87
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 .. function:: setstate(state)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 state should have been obtained from a previous call to :func:`getstate`, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 :func:`setstate` restores the internal state of the generator to what it was at
78527 df337391f9f5 it's getstatus() not setstatus(); thanks to Shaddi Hasan from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 72395 diff changeset	93 the time :func:`getstate` was called.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 .. versionadded:: 2.1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 .. function:: jumpahead(n)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 Change the internal state to one different from and likely far away from the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 current state. n is a non-negative integer which is used to scramble the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 current state vector. This is most useful in multi-threaded programs, in
45429 853af5bbb497 A lot more typo fixes by Ori Avtalion. Georg Brandl <georg@python.org> parents: 44122 diff changeset	103 conjunction with multiple instances of the :class:`Random` class:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 :meth:`setstate` or :meth:`seed` can be used to force all instances into the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 same internal state, and then :meth:`jumpahead` can be used to force the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 instances' states far apart.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 .. versionadded:: 2.1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 Instead of jumping to a specific state, n steps ahead, ``jumpahead(n)``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 jumps to another state likely to be separated by many steps.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 .. function:: getrandbits(k)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 Returns a python :class:`long` int with k random bits. This method is supplied
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 with the MersenneTwister generator and some other generators may also provide it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 as an optional part of the API. When available, :meth:`getrandbits` enables
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 :meth:`randrange` to handle arbitrarily large ranges.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 Functions for integers:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
79025 2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 78527 diff changeset	127 .. function:: randrange(stop)
2291aff20a05 #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. Ezio Melotti <ezio.melotti@gmail.com> parents: 78527 diff changeset	128 randrange(start, stop[, step])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 Return a randomly selected element from ``range(start, stop, step)``. This is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 range object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 .. versionadded:: 1.5.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 .. function:: randint(a, b)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 Return a random integer N such that ``a <= N <= b``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 Functions for sequences:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 .. function:: choice(seq)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 Return a random element from the non-empty sequence seq. If seq is empty,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 raises :exc:`IndexError`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 .. function:: shuffle(x[, random])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 Shuffle the sequence x in place. The optional argument random is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 0-argument function returning a random float in [0.0, 1.0); by default, this is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 the function :func:`random`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 Note that for even rather small ``len(x)``, the total number of permutations of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 x is larger than the period of most random number generators; this implies
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 that most permutations of a long sequence can never be generated.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 .. function:: sample(population, k)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 Return a k length list of unique elements chosen from the population sequence.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 Used for random sampling without replacement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 Returns a new list containing elements from the population while leaving the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 original population unchanged. The resulting list is in selection order so that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 all sub-slices will also be valid random samples. This allows raffle winners
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 (the sample) to be partitioned into grand prize and second place winners (the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 subslices).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 42603 diff changeset	174 Members of the population need not be :term:`hashable` or unique. If the population
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 contains repeats, then each occurrence is a possible selection in the sample.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 To choose a sample from a range of integers, use an :func:`xrange` object as an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 argument. This is especially fast and space efficient for sampling from a large
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 population: ``sample(xrange(10000000), 60)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 The following functions generate specific real-valued distributions. Function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 parameters are named after the corresponding variables in the distribution's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 equation, as used in common mathematical practice; most of these equations can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 be found in any statistics text.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 .. function:: random()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 Return the next random floating point number in the range [0.0, 1.0).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 .. function:: uniform(a, b)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	194 Return a random floating point number N such that ``a <= N <= b`` for
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	195 ``a <= b`` and ``b <= N <= a`` for ``b < a``.
49253 923fb458bd0c #3918: note that uniform() args can be swapped. Georg Brandl <georg@python.org> parents: 48100 diff changeset	196
54708 7cf89ed90f9d Issue 6261: Clarify behavior of random.uniform(). Raymond Hettinger <python@rcn.com> parents: 52762 diff changeset	197 The end-point value ``b`` may or may not be included in the range
7cf89ed90f9d Issue 6261: Clarify behavior of random.uniform(). Raymond Hettinger <python@rcn.com> parents: 52762 diff changeset	198 depending on floating-point rounding in the equation ``a + (b-a) * random()``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
72395 169e07315ba5 Add info from the docstring for random.gammavariate() to the docs. Georg Brandl <georg@python.org> parents: 71952 diff changeset	200
46029 f1e51785947f Issue 1681432: Add triangular distribution the random module. Raymond Hettinger <python@rcn.com> parents: 45429 diff changeset	201 .. function:: triangular(low, high, mode)
f1e51785947f Issue 1681432: Add triangular distribution the random module. Raymond Hettinger <python@rcn.com> parents: 45429 diff changeset	202
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	203 Return a random floating point number N such that ``low <= N <= high`` and
46046 8c2604fe5886 Tighten documentation for Random.triangular. Raymond Hettinger <python@rcn.com> parents: 46030 diff changeset	204 with the specified mode between those bounds. The low and high bounds
8c2604fe5886 Tighten documentation for Random.triangular. Raymond Hettinger <python@rcn.com> parents: 46030 diff changeset	205 default to zero and one. The mode argument defaults to the midpoint
8c2604fe5886 Tighten documentation for Random.triangular. Raymond Hettinger <python@rcn.com> parents: 46030 diff changeset	206 between the bounds, giving a symmetric distribution.
46030 1d5a11619eca Adopt Nick's suggestion for useful default arguments. Raymond Hettinger <python@rcn.com> parents: 46029 diff changeset	207
46046 8c2604fe5886 Tighten documentation for Random.triangular. Raymond Hettinger <python@rcn.com> parents: 46030 diff changeset	208 .. versionadded:: 2.6
46030 1d5a11619eca Adopt Nick's suggestion for useful default arguments. Raymond Hettinger <python@rcn.com> parents: 46029 diff changeset	209
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 .. function:: betavariate(alpha, beta)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	213 Beta distribution. Conditions on the parameters are ``alpha > 0`` and
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	214 ``beta > 0``. Returned values range between 0 and 1.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 .. function:: expovariate(lambd)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218
50786 2d453b221bec Merged revisions 68292,68344,68361,68378,68424,68426,68429-68430,68450,68457,68480-68481,68493,68495,68499,68501,68512,68514-68515 via svnmerge from Georg Brandl <georg@python.org> parents: 49253 diff changeset	219 Exponential distribution. lambd is 1.0 divided by the desired
2d453b221bec Merged revisions 68292,68344,68361,68378,68424,68426,68429-68430,68450,68457,68480-68481,68493,68495,68499,68501,68512,68514-68515 via svnmerge from Georg Brandl <georg@python.org> parents: 49253 diff changeset	220 mean. It should be nonzero. (The parameter would be called
2d453b221bec Merged revisions 68292,68344,68361,68378,68424,68426,68429-68430,68450,68457,68480-68481,68493,68495,68499,68501,68512,68514-68515 via svnmerge from Georg Brandl <georg@python.org> parents: 49253 diff changeset	221 "lambda", but that is a reserved word in Python.) Returned values
2d453b221bec Merged revisions 68292,68344,68361,68378,68424,68426,68429-68430,68450,68457,68480-68481,68493,68495,68499,68501,68512,68514-68515 via svnmerge from Georg Brandl <georg@python.org> parents: 49253 diff changeset	222 range from 0 to positive infinity if lambd is positive, and from
2d453b221bec Merged revisions 68292,68344,68361,68378,68424,68426,68429-68430,68450,68457,68480-68481,68493,68495,68499,68501,68512,68514-68515 via svnmerge from Georg Brandl <georg@python.org> parents: 49253 diff changeset	223 negative infinity to 0 if lambd is negative.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 .. function:: gammavariate(alpha, beta)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	228 Gamma distribution. (Not the gamma function!) Conditions on the
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	229 parameters are ``alpha > 0`` and ``beta > 0``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
72395 169e07315ba5 Add info from the docstring for random.gammavariate() to the docs. Georg Brandl <georg@python.org> parents: 71952 diff changeset	231 The probability distribution function is::
169e07315ba5 Add info from the docstring for random.gammavariate() to the docs. Georg Brandl <georg@python.org> parents: 71952 diff changeset	232
169e07315ba5 Add info from the docstring for random.gammavariate() to the docs. Georg Brandl <georg@python.org> parents: 71952 diff changeset	233 x ** (alpha - 1) * math.exp(-x / beta)
169e07315ba5 Add info from the docstring for random.gammavariate() to the docs. Georg Brandl <georg@python.org> parents: 71952 diff changeset	234 pdf(x) = --------------------------------------
169e07315ba5 Add info from the docstring for random.gammavariate() to the docs. Georg Brandl <georg@python.org> parents: 71952 diff changeset	235 math.gamma(alpha) * beta ** alpha
169e07315ba5 Add info from the docstring for random.gammavariate() to the docs. Georg Brandl <georg@python.org> parents: 71952 diff changeset	236
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 .. function:: gauss(mu, sigma)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	240 Gaussian distribution. mu is the mean, and sigma is the standard
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	241 deviation. This is slightly faster than the :func:`normalvariate` function
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50786 diff changeset	242 defined below.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 .. function:: lognormvariate(mu, sigma)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 Log normal distribution. If you take the natural logarithm of this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 distribution, you'll get a normal distribution with mean mu and standard
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 deviation sigma. mu can have any value, and sigma must be greater than
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 zero.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 .. function:: normalvariate(mu, sigma)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 Normal distribution. mu is the mean, and sigma is the standard deviation.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 .. function:: vonmisesvariate(mu, kappa)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 mu is the mean angle, expressed in radians between 0 and 2\\ pi, and kappa*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 is the concentration parameter, which must be greater than or equal to zero. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 kappa is equal to zero, this distribution reduces to a uniform random angle
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 over the range 0 to 2\\ pi*.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 .. function:: paretovariate(alpha)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 Pareto distribution. alpha is the shape parameter.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 .. function:: weibullvariate(alpha, beta)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273 Weibull distribution. alpha is the scale parameter and beta is the shape
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 parameter.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 Alternative Generators:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 .. class:: WichmannHill([seed])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 Class that implements the Wichmann-Hill algorithm as the core generator. Has all
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 of the same methods as :class:`Random` plus the :meth:`whseed` method described
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 below. Because this class is implemented in pure Python, it is not threadsafe
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 and may require locks between calls. The period of the generator is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 6,953,607,871,644 which is small enough to require care that two independent
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 random sequences do not overlap.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 .. function:: whseed([x])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 This is obsolete, supplied for bit-level compatibility with versions of Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 prior to 2.1. See :func:`seed` for details. :func:`whseed` does not guarantee
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 that distinct integer arguments yield distinct internal states, and can yield no
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 more than about 2\\24 distinct internal states in all.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 .. class:: SystemRandom([seed])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 Class that uses the :func:`os.urandom` function for generating random numbers
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 from sources provided by the operating system. Not available on all systems.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 Does not rely on software state and sequences are not reproducible. Accordingly,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 the :meth:`seed` and :meth:`jumpahead` methods have no effect and are ignored.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 The :meth:`getstate` and :meth:`setstate` methods raise
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 :exc:`NotImplementedError` if called.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 Examples of basic usage::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 >>> random.random() # Random float x, 0.0 <= x < 1.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 0.37444887175646646
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 >>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 1.1800146073117523
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 >>> random.randint(1, 10) # Integer from 1 to 10, endpoints included
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 7
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 >>> random.randrange(0, 101, 2) # Even integer from 0 to 100
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 26
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 >>> random.choice('abcdefghij') # Choose a random element
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 'c'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 >>> items = [1, 2, 3, 4, 5, 6, 7]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 >>> random.shuffle(items)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 >>> items
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 [7, 3, 2, 5, 6, 4, 1]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 >>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 [4, 1, 5]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 equidistributed uniform pseudorandom number generator", ACM Transactions on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 Modeling and Computer Simulation Vol. 8, No. 1, January pp.3-30 1998.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 Wichmann, B. A. & Hill, I. D., "Algorithm AS 183: An efficient and portable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 pseudo-random number generator", Applied Statistics 31 (1982) 188-190.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339
52679 f942893fa4d8 Add link to an alternative generator with a long-period. Raymond Hettinger <python@rcn.com> parents: 51809 diff changeset	340 `Complementary-Multiply-with-Carry recipe
52762 2a27f9ada8e3 Fix typo. Raymond Hettinger <python@rcn.com> parents: 52679 diff changeset	341 <http://code.activestate.com/recipes/576707/>`_ for a compatible alternative
2a27f9ada8e3 Fix typo. Raymond Hettinger <python@rcn.com> parents: 52679 diff changeset	342 random number generator with a long period and comparatively simple update
52679 f942893fa4d8 Add link to an alternative generator with a long-period. Raymond Hettinger <python@rcn.com> parents: 51809 diff changeset	343 operations.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/random.rst @ 79675:c0a2294de787 2.7