This module implements pseudo-random number generators

for various distributions.

For integers, there is uniform selection from a range. For

sequences, there is uniform selection of a random element, a
function to generate a random permutation of a list in-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 generating distributions of angles,
the von Mises distribution is available.

Almost all module functions depend on the basic

function random(), which generates a random float uniformly
in the semi-open range [0.0, 1.0). Python uses the Mersenne
Twister as the core generator. It produces 53-bit precision
floats and has a period of 2**19937-1. The underlying
implementation in C is both fast and threadsafe. The
Mersenne Twister is one of the most extensively tested
random number generators in existence. However, being
completely deterministic, it is not suitable for all purposes,
and is completely unsuitable for cryptographic purposes.

The functions supplied by this module are actually bound

methods of a hidden instance of the   random.Random   class.
You can instantiate your own instances of   Random   to get
generators that don’t share state.

Class   Random   can also be subclassed if you want to use a

different basic generator of your own devising: in that case,
override the   random(),   seed(),   getstate(),
and   setstate()   methods. Optionally, a new generator can
supply a   getrandbits()   method — this
allows  randrange()  to produce selections over an arbitrarily
large range.

The   random   module also provides the   SystemRandom   class

which uses the system function   os.urandom()   to generate
random numbers from sources provided by the operating
system.

Warning The pseudo-random generators of this module

should not be used for security purposes. For security or
cryptographic uses, see the secrets module.
See also M. Matsumoto and T. Nishimura, “Mersenne Twister:
A 623-dimensionally equidistributed uniform pseudorandom
number generator”, ACM Transactions on Modeling and
Computer Simulation Vol. 8, No. 1, January pp.3–30 1998.
Complementary-Multiply-with-Carry recipe for a compatible
alternative random number generator with a long period and
comparatively simple update operations.

Bookkeeping functions
random.seed(a=None, version=2)
Initialize the random number generator.

If a is omitted or  None, the current system time is used. If

randomness sources are provided by the operating system,
they are used instead of the system time (see
the os.urandom() function for details on availability).

If a is an int, it is used directly.

With version 2 (the default), a   str,   bytes,

or  bytearray  object gets converted to an  int  and all of its
bits are used.
With version 1 (provided for reproducing random sequences
from older versions of Python), the algorithm
for str and bytes generates a narrower range of seeds.

Changed in version 3.2:   Moved to the version 2 scheme

which uses all of the bits in a string seed.

Deprecated since version 3.9: In the future, the seed must be

one of the following
types: NoneType, int, float, str, bytes, or bytearray.

random.getstate()
Return an object capturing the current internal state of the
generator. This object can be passed to   setstate()   to
restore the state.

random.setstate(state)
state   should have been obtained from a previous call
to getstate(), and setstate() restores the internal state of
the generator to what it was at the time   getstate()   was
called.

Functions for bytes

random.randbytes(n)
Generate n random bytes.

This method should not be used for generating security

tokens. Use secrets.token_bytes() instead.

New in version 3.9.

Functions for integers

random.randrange(stop)
random.randrange(start, stop[, step])
Return a randomly selected element
from   range(start, stop, step). This is equivalent
to choice(range(start, stop, step)), but doesn’t actually
build a range object.

The positional argument pattern matches that of   range().

Keyword arguments should not be used because the function
may use them in unexpected ways.

Changed in version 3.2:  randrange()  is more sophisticated

about producing equally distributed values. Formerly it used
a style like   int(random()*n)   which could produce slightly
uneven distributions.

random.randint(a, b)
Return a random integer   N   such that   a <= N <= b. Alias
for randrange(a, b+1).

random.getrandbits(k)
Returns a non-negative Python integer with k random bits.
This method is supplied with the MersenneTwister generator
and some other generators may also provide it as an optional
part of the API. When
available,   getrandbits()   enables   randrange()   to handle
arbitrarily large ranges.

Changed in version 3.9: This method now accepts zero for k.

Functions for sequences

random.choice(seq)
Return a random element from the non-empty sequence seq.
If seq is empty, raises IndexError.
random.choices(population, weights=None, *, cum_weig
hts=None, k=1)
Return a   k   sized list of elements chosen from
the population with replacement. If the population is empty,
raises IndexError.

If a   weights   sequence is specified, selections are made

according to the relative weights. Alternatively, if
a   cum_weights   sequence is given, the selections are made
according to the cumulative weights (perhaps computed
using   itertools.accumulate()). For example, the relative
weights   [10, 5, 30, 5]   are equivalent to the cumulative
weights   [10, 15, 45, 50]. Internally, the relative weights
are converted to cumulative weights before making
selections, so supplying the cumulative weights saves work.

If neither weights nor cum_weights are specified, selections

are made with equal probability. If a weights sequence is
supplied, it must be the same length as
the   population   sequence. It is a   TypeError   to specify
both weights and cum_weights.

The weights or cum_weights can use any numeric type that

interoperates with the   float   values returned
by  random()  (that includes integers, floats, and fractions but
excludes decimals). Behavior is undefined if any weight is
negative. A ValueError is raised if all weights are zero.

For a given seed, the   choices()   function with equal

weighting typically produces a different sequence than
repeated calls to   choice(). The algorithm used
by   choices()   uses floating point arithmetic for internal
consistency and speed. The algorithm used
by   choice()   defaults to integer arithmetic with repeated
selections to avoid small biases from round-off error.

New in version 3.6.

Changed in version 3.9: Raises a  ValueError  if all weights

are zero.

random.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 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.

Deprecated since version 3.9, will be removed in version

3.11: The optional parameter random.

random.sample(population, k, *, counts=None)
Return a   k   length list of unique elements chosen from the
population sequence or set. Used for random sampling
without replacement.
Returns a new list containing elements from the population
while leaving the original population unchanged. The
resulting list is in selection order so that all sub-slices will
also be valid random samples. This allows raffle winners (the
sample) to be partitioned into grand prize and second place
winners (the subslices).

Members of the population need not be hashable or unique.

If the population contains repeats, then each occurrence is a
possible selection in the sample.

Repeated elements can be specified one at a time or with the

optional keyword-only   counts   parameter. For
example,   sample(['red', 'blue'], counts=[4, 2], k=5) 
is equivalent
to   sample(['red', 'red', 'red', 'red', 'blue', 'blue
'], k=5).

To choose a sample from a range of integers, use

a  range()  object as an argument. This is especially fast and
space efficient for sampling from a large
population: sample(range(10000000), k=60).

If the sample size is larger than the population size,

a ValueError is raised.

Changed in version 3.9: Added the counts parameter.

Deprecated since version 3.9:   In the future,

the population must be a sequence. Instances of  set  are no
longer supported. The set must first be converted to
a  list  or  tuple, preferably in a deterministic order so that
the sample is reproducible.
Real-valued distributions
The following functions generate specific real-valued
distributions. Function parameters are named after the
corresponding variables in the distribution’s equation, as
used in common mathematical practice; most of these
equations can be 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)¶