9.6.random — Generate pseudo-random numbers¶

Source code:Lib/random.py

This module implements pseudo-random number generators for variousdistributions.

For integers, there is uniform selection from a range. For sequences, there isuniform selection of a random element, a function to generate a randompermutation of a list in-place, and a function for random sampling withoutreplacement.

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.

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

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,version=2)¶

Initialize the random number generator.

Ifa is omitted orNone, the current system time is used. Ifrandomness sources are provided by the operating system, they are usedinstead of the system time (see theos.urandom() function for detailson availability).

Ifa is an int, it is used directly.

With version 2 (the default), astr,bytes, orbytearrayobject gets converted to anint and all of its bits are used.

With version 1 (provided for reproducing random sequences from older versionsof Python), the algorithm forstr andbytes generates anarrower range of seeds.

Changed in version 3.2:Moved to the version 2 scheme which uses all of the bits in a string seed.

random.getstate()¶

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

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.

random.getrandbits(k)¶

Returns a Python integer withk random bits. This method is supplied withthe 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.

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.

The positional argument pattern matches that ofrange(). Keyword argumentsshould not be used because the function may use them in unexpected ways.

Changed in version 3.2:randrange() is more sophisticated about producing equally distributedvalues. Formerly it used a style likeint(random()*n) which could produceslightly uneven distributions.

random.randint(a,b)¶

Return a random integerN such thata<=N<=b. Alias forrandrange(a,b+1).

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 sequenceor set. Used for random sampling without replacement.

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 anrange() object as anargument. This is especially fast and space efficient for sampling from a largepopulation:sample(range(10000000),60).

If the sample size is larger than the population size, aValueErroris raised.

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.

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 Generator:

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() method has no effect and is ignored.Thegetstate() andsetstate() methods raiseNotImplementedError if called.

>>>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.randrange(10)# Integer from 0 to 97>>>random.randrange(0,101,2)# Even integer from 0 to 10026>>>random.choice('abcdefghij')# Single 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)# Three samples without replacement[4, 1, 5]

>>>weighted_choices=[('Red',3),('Blue',2),('Yellow',1),('Green',4)]>>>population=[valforval,cntinweighted_choicesforiinrange(cnt)]>>>population['Red', 'Red', 'Red', 'Blue', 'Blue', 'Yellow', 'Green', 'Green', 'Green', 'Green']>>>random.choice(population)'Green'

>>>choices,weights=zip(*weighted_choices)>>>cumdist=list(itertools.accumulate(weights))>>>cumdist# [3, 3+2, 3+2+1, 3+2+1+4][3, 5, 6, 10]>>>x=random.random()*cumdist[-1]>>>choices[bisect.bisect(cumdist,x)]'Blue'