15.3 The random Module

The random module generates pseudo-random numbers with various distributions. The underlying uniform pseudo-random generator uses the Whichmann-Hill algorithm, with a period of length 6,953,607,871,644. The resulting pseudo-random numbers, while quite good, are not of cryptographic quality. If you want physically generated random numbers rather than algorithmically generated pseudo-random numbers, you may use /dev/random or /dev/urandom on platforms that support such pseudo-devices (such as recent Linux releases). For an alternative, see http://www.fourmilab.ch/hotbits.

All functions of module random are methods of a hidden instance of class random.Random. You can instantiate Random explicitly to get multiple generators that do not share state. Explicit instantiation is advisable if you require random numbers in multiple threads (threads are covered in Chapter 14). This section documents the most frequently used functions exposed by module random.

choice(seq)

Returns a random item from non-empty sequence seq.

getstate(  )

Returns an object S that represents the current state of the generator. You can later pass S to function setstate in order to restore the generator's state.

jumpahead(n)

Advances the generator state as if n random numbers had been generated. Computing the new state is faster than generating n random numbers would be.

random(  )

Returns a random floating-point number r from a uniform distribution, such that 0<=r<1.

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

Like choice(range(start,stop,step)), but faster, since randrange does not need to build the list that range would create.

seed(x=None)

Initializes the generator state. x can be any hashable object. When x is None, and also automatically when module random is first loaded, seed uses the current system time to get a seed. x is normally a long integer up to 27814431486575L. Larger x values are accepted, but may produce the same generator states as smaller ones.

setstate(S)

Restores the generator state. S must be the result of a previous call to getstate.

shuffle(alist)

Shuffles, in place, mutable sequence alist.

uniform(a,b)

Returns a random floating-point number r from a uniform distribution, such that a<=r<b.

Module random also supplies functions that generate pseudo-random floating-point numbers from many other probability distributions (Beta, Gamma, exponential, Gauss, Pareto, etc.). All of these functions internally call random.random as their source of randomness.