9.6.random — Generate pseudo-random numbers¶

Source code:Lib/random.py

This module implements pseudo-random number generators for variousdistributions.

For integers, uniform selection from a range. For sequences, uniform selectionof a random element, a function to generate a random permutation of a listin-place, and a function for random sampling without replacement.

On the real line, there are functions to compute uniform, normal (Gaussian),lognormal, negative exponential, gamma, and beta distributions. For generatingdistributions of angles, the von Mises distribution is available.

Almost all module functions depend on the basic functionrandom(), whichgenerates a random float uniformly in the semi-open range [0.0, 1.0). Pythonuses the Mersenne Twister as the core generator. It produces 53-bit precisionfloats and has a period of 2**19937-1. The underlying implementation in C isboth fast and threadsafe. The Mersenne Twister is one of the most extensivelytested random number generators in existence. However, being completelydeterministic, it is not suitable for all purposes, and is completely unsuitablefor cryptographic purposes.

The functions supplied by this module are actually bound methods of a hiddeninstance of therandom.Random class. You can instantiate your owninstances ofRandom to get generators that don’t share state. This isespecially useful for multi-threaded programs, creating a different instance ofRandom for each thread, and using thejumpahead() method to makeit likely that the generated sequences seen by each thread don’t overlap.

ClassRandom can also be subclassed if you want to use a differentbasic generator of your own devising: in that case, override therandom(),seed(),getstate(),setstate() andjumpahead() methods. Optionally, a new generator can supply agetrandbits() method — thisallowsrandrange() to produce selections over an arbitrarily large range.

As an example of subclassing, therandom module provides theWichmannHill class that implements an alternative generator in purePython. The class provides a backward compatible way to reproduce results fromearlier versions of Python, which used the Wichmann-Hill algorithm as the coregenerator. Note that this Wichmann-Hill generator can no longer be recommended:its period is too short by contemporary standards, and the sequence generated isknown to fail some stringent randomness tests. See the references below for arecent variant that repairs these flaws.

Therandom module also provides theSystemRandom class whichuses the system functionos.urandom() to generate random numbersfrom sources provided by the operating system.

Bookkeeping functions:

random.seed(a=None)¶

Initialize internal state of the random number generator.

None or no argument seeds from current time or from an operatingsystem specific randomness source if available (see theos.urandom()function for details on availability).

Ifa is notNone or anint or along, thenhash(a) is used instead. Note that the hash values for some typesare nondeterministic whenPYTHONHASHSEED is enabled.

Changed in version 2.4:formerly, operating system resources were not used.

random.getstate()¶

Return an object capturing the current internal state of the generator. Thisobject can be passed tosetstate() to restore the state.

New in version 2.1.

Changed in version 2.6:State values produced in Python 2.6 cannot be loaded into earlier versions.

random.setstate(state)¶

state should have been obtained from a previous call togetstate(), andsetstate() restores the internal state of the generator to what it was atthe timegetstate() was called.

New in version 2.1.

random.jumpahead(n)¶

Change the internal state to one different from and likely far away from thecurrent state.n is a non-negative integer which is used to scramble thecurrent state vector. This is most useful in multi-threaded programs, inconjunction with multiple instances of theRandom class:setstate() orseed() can be used to force all instances into thesame internal state, and thenjumpahead() can be used to force theinstances’ states far apart.

New in version 2.1.

Changed in version 2.3:Instead of jumping to a specific state,n steps ahead,jumpahead(n)jumps to another state likely to be separated by many steps.

random.getrandbits(k)¶

Returns a pythonlong int withk random bits. This method is suppliedwith the MersenneTwister generator and some other generators may also provide itas an optional part of the API. When available,getrandbits() enablesrandrange() to handle arbitrarily large ranges.

New in version 2.4.

Functions for integers:

random.randrange(stop)¶

random.randrange(start,stop[,step])

Return a randomly selected element fromrange(start,stop,step). This isequivalent tochoice(range(start,stop,step)), but doesn’t actually build arange object.

New in version 1.5.2.

random.randint(a,b)¶

Return a random integerN such thata<=N<=b.

Functions for sequences:

random.choice(seq)¶

Return a random element from the non-empty sequenceseq. Ifseq is empty,raisesIndexError.

random.shuffle(x[,random])¶

Shuffle the sequencex in place. The optional argumentrandom is a0-argument function returning a random float in [0.0, 1.0); by default, this isthe functionrandom().

Note that for even rather smalllen(x), the total number of permutations ofx is larger than the period of most random number generators; this impliesthat most permutations of a long sequence can never be generated.

random.sample(population,k)¶

Return ak length list of unique elements chosen from the population sequence.Used for random sampling without replacement.

New in version 2.3.

Returns a new list containing elements from the population while leaving theoriginal population unchanged. The resulting list is in selection order so thatall sub-slices will also be valid random samples. This allows raffle winners(the sample) to be partitioned into grand prize and second place winners (thesubslices).

Members of the population need not behashable or unique. If the populationcontains repeats, then each occurrence is a possible selection in the sample.

To choose a sample from a range of integers, use anxrange() object as anargument. This is especially fast and space efficient for sampling from a largepopulation:sample(xrange(10000000),60).

The following functions generate specific real-valued distributions. Functionparameters are named after the corresponding variables in the distribution’sequation, as used in common mathematical practice; most of these equations canbe found in any statistics text.

random.random()¶

Return the next random floating point number in the range [0.0, 1.0).

random.uniform(a,b)¶

Return a random floating point numberN such thata<=N<=b fora<=b andb<=N<=a forb<a.

The end-point valueb may or may not be included in the rangedepending on floating-point rounding in the equationa+(b-a)*random().

random.triangular(low,high,mode)¶

Return a random floating point numberN such thatlow<=N<=high andwith the specifiedmode between those bounds. Thelow andhigh boundsdefault to zero and one. Themode argument defaults to the midpointbetween the bounds, giving a symmetric distribution.

New in version 2.6.

random.betavariate(alpha,beta)¶

Beta distribution. Conditions on the parameters arealpha>0 andbeta>0. Returned values range between 0 and 1.

random.expovariate(lambd)¶

Exponential distribution.lambd is 1.0 divided by the desiredmean. It should be nonzero. (The parameter would be called“lambda”, but that is a reserved word in Python.) Returned valuesrange from 0 to positive infinity iflambd is positive, and fromnegative infinity to 0 iflambd is negative.

random.gammavariate(alpha,beta)¶

Gamma distribution. (Not the gamma function!) Conditions on theparameters arealpha>0 andbeta>0.

The probability distribution function is:

x**(alpha-1)*math.exp(-x/beta)pdf(x)=--------------------------------------math.gamma(alpha)*beta**alpha

random.gauss(mu,sigma)¶

Gaussian distribution.mu is the mean, andsigma is the standarddeviation. This is slightly faster than thenormalvariate() functiondefined below.

random.lognormvariate(mu,sigma)¶

Log normal distribution. If you take the natural logarithm of thisdistribution, you’ll get a normal distribution with meanmu and standarddeviationsigma.mu can have any value, andsigma must be greater thanzero.

random.normalvariate(mu,sigma)¶

Normal distribution.mu is the mean, andsigma is the standard deviation.

random.vonmisesvariate(mu,kappa)¶

mu is the mean angle, expressed in radians between 0 and 2*pi, andkappais the concentration parameter, which must be greater than or equal to zero. Ifkappa is equal to zero, this distribution reduces to a uniform random angleover the range 0 to 2*pi.

random.paretovariate(alpha)¶

Pareto distribution.alpha is the shape parameter.

random.weibullvariate(alpha,beta)¶

Weibull distribution.alpha is the scale parameter andbeta is the shapeparameter.

Alternative Generators:

classrandom.WichmannHill([seed])¶

Class that implements the Wichmann-Hill algorithm as the core generator. Has allof the same methods asRandom plus thewhseed() method describedbelow. Because this class is implemented in pure Python, it is not threadsafeand may require locks between calls. The period of the generator is6,953,607,871,644 which is small enough to require care that two independentrandom sequences do not overlap.

random.whseed([x])¶

This is obsolete, supplied for bit-level compatibility with versions of Pythonprior to 2.1. Seeseed() for details.whseed() does not guaranteethat distinct integer arguments yield distinct internal states, and can yield nomore than about 2**24 distinct internal states in all.

classrandom.SystemRandom([seed])¶

Class that uses theos.urandom() function for generating random numbersfrom sources provided by the operating system. Not available on all systems.Does not rely on software state and sequences are not reproducible. Accordingly,theseed() andjumpahead() methods have no effect and are ignored.Thegetstate() andsetstate() methods raiseNotImplementedError if called.

New in version 2.4.

Examples of basic usage:

>>>random.random()# Random float x, 0.0 <= x < 1.00.37444887175646646>>>random.uniform(1,10)# Random float x, 1.0 <= x < 10.01.1800146073117523>>>random.randint(1,10)# Integer from 1 to 10, endpoints included7>>>random.randrange(0,101,2)# Even integer from 0 to 10026>>>random.choice('abcdefghij')# Choose a random element'c'>>>items=[1,2,3,4,5,6,7]>>>random.shuffle(items)>>>items[7, 3, 2, 5, 6, 4, 1]>>>random.sample([1,2,3,4,5],3)# Choose 3 elements[4, 1, 5]