This module implements pseudorandom number generators for different needs.

- For integers, there is a selection of one from the range.
- For sequences, there is a random element selection, a random list sort function, and a function to randomly select multiple elements from a sequence.
- There are functions for calculating uniform, normal (Gaussian), lognormal, negative exponential, gamma and beta distributions.
- The von Mises distribution is available for generating angle distributions.

Almost all functions of the module depend on the main function `random()`

, which generates random floating point numbers (hereafter float) uniformly in the semi-open range [0.0, 1.0). Python uses Mersenne Twister as its main generator. It produces 53-bit exact floats and has a period of 2**19937-1. Its main implementation in C is fast and multi-threaded. Mersenne Twister is one of the most widely tested random number generators. However, being fully deterministic, it is not suitable for all purposes, especially for cryptographic ones. The `random`

module also provides a class of `SystemRandom`

. This class uses the system function `os.urandom()`

to generate random numbers from sources provided by the operating system. The pseudorandom generators of this module should not be used for security reasons. For security or cryptographic use, see the `secrets`

module.

Table of Contents

## Functions for integers

random.randrange(stop) random.randrange(start, stop[, step]) Returns a randomly chosen element from `range(start, stop, step)`

. This is equivalent to `choice(range(start, stop, step)),`

but does not create a range object.

```
>>> random.randrange(0, 101, 2)
26
```

The positional argument pattern is the same as the `range()`

pattern. Arguments should not be used as keyword(start, stop, step) because the function may use them in unexpected ways. random.randint(a, b) Returns a random integer `N`

such that `a <= N <= b`

.

```
>>> random.randint(0, 101)
44
```

## Functions for sequences

random.choice(seq) Returns a random element from the non-empty sequence `seq`

. If `seq`

is empty, an `IndexError`

occurs.

```
>>> choice(['win', 'lose', 'draw'])
'draw'
```

random.choices(population, weights=None, *, cum_weights=None, k=1) Returns a list of elements of size `k`

, chosen from `the population`

with replacement. If `the population`

is empty, an `IndexError`

occurs.

```
>>> random.choices(['apples', 'bananas', 'cherries'], weights = [10, 1, 1], k = 5)
['apples', 'cherry', 'apples', 'apples', 'apples']
```

If a sequence of `weights`

is given, the selection is made according to the relative weights. Alternatively, if the sequence `cum_weights`

is given, the selection is made according to cumulative weights (possibly calculated using `itertools.accumulate()`

). For example, relative weights `[10, 5, 30, 5]`

are equivalent to cumulative weights `[10, 15, 45, 50]`

. Internally, relative weights are converted to cumulative weights before selection, so supplying a cumulative weight saves time. If neither `weights`

nor `cum_weights`

are specified, selection is made with equal probability. If a weights sequence is specified, it must be the same as the `population`

sequence. `TypeError`

occurs if the `weights`

or `cum_weights`

argument is not specified correctly. `Weights`

or `cum_weights`

can use any type of number that interacts with the `float`

value returned by `random()`

(which includes integers, floats, and fractions, but excludes decimal numbers). random.shuffle(x[, random]) Shuffles the sequence of `x`

in place. The optional argument `of random`

is a 0-argument function that returns a random float value in [0.0, 1.0]; the default is `random()`

.

```
>>> fruits = ['apples', 'bananas', 'cherries']
>>> random.shuffle(fruits)
>>> fruits
['bananas', 'cherries', 'apples']
```

To shuffle an immutable sequence and return a new shuffled list, use `sample(x, k=len(x)).`

Note that even for a small `len(x)`

, the total number of permutations `of x`

can increase more than the period of most random number generators. This means that most permutations of a long sequence can never be performed. For example, a sequence 2080 elements long is the largest sequence that can fit into the period of a Mersin Twister random number generator. random.sample(population, k) Returns a list of length `k`

of unique elements selected from a sequence or set. It is used for random sampling without replacement.

```
>>> random.sample([0, 1, 2, 3, 4, 5, 6], 3)
[5, 6, 4]
```

This is a new list containing elements from the sequence, leaving the original sequence unchanged. The new list is in selection order, so that all sub-samples will also be random sequences. This allows the winners of the draws (when sampled) to share the grand prize, second place, and beyond. Participants do not have to be hashable or unique. If the sequence contains repeats, each occurrence is a possible choice in the sample. To select a single number from a range of numbers, use the `range()`

object as an argument. This is a simple solution for sampling from a large sequence: `sample(range(10000000), k=60)`

. If the sample size is larger than the length of the sequence, a `ValueError`

occurs.

## The generator’s control functions

random.seed(a=None, version=2) Initializes (starts) the random number generator. If `a`

is not specified or `None`

, the current system time is used. If random sources are provided by the operating system, they are used instead of the system time (see `os.urandom()`

for details). The value of `a`

is used if it is `int`

(an integer).

```
>>> random.seed(10)
>>> random.random()
0.5714025946899135
```

If `version=2`

(default), `str`

, `bytes`

, or `bytearray`

objects are converted to `int`

and all its bits are used. When `version=1`

(to reproduce random sequences from older versions of Python), the algorithm for `str`

and `bytes`

produces a narrower seed range. random.getstate() Returns an object capturing the current internal state of the generator. This object can be passed to `setstate()`

to resume the state.

```
>>> random.getstate()
(3, (2910518045, 2919558713, 592432859, 1634426085,
....
2194693540, 2), None)
```

random.setstate(state) the`state`

should be obtained from a previous call to `getstate()`

. And `setstate()`

will restore the internal state of the generator to the one obtained from the `getstate()`

call. random.getrandbits(k) Returns a Python `int`

with random bits `k`

. This method comes with the MersenneTwister generator, while other generators may also provide it as an optional part of the API.

```
>>> random.getrandbits(8)
109
```

If possible, `getrandbits()`

includes `randrange()`

to handle ranges of magnitude.

## Other functions for generating distributions

Functional parameters appear after the corresponding variables in the distribution equation that are used in general mathematical practice; most of these equations can be found in any statistical text. random.random() Returns a random floating-point number in the range [0.0, 1.0).

```
>>> random.random()
0.48256167455085586
```

random.uniform(a, b) Returns a random floating-point number `N`

such that `a <= N <= b`

for `a <= b`

and `b <= N <= a`

for `b < a`

.

```
>>> random.uniform(2.5, 10.0)
2.611243345184153
```

The final value of `b`

will or will not be included in the range, depending on the float rounding in the equation `a + (b-a) * random()`

. random.triangular(low, high, mode) Returns a random floating-point number `N`

, such that `low <= N <= high`

and with the specified `mode`

between those bounds. The default `low`

and `high`

bounds are 0 and 1.

```
>>> random.triangular(20, 60, 30)
34.605051874664895
```

The default `mode`

argument coincides with the middle between the bounds, giving a symmetric distribution. random.betavariate(alpha, beta) Beta distribution. The conditions for the arguments are `alpha > 0`

and `beta > 0`

. The returned values range from 0 to 1.

```
>>> random.betavariate(5, 10)
0.33277653214797026
```

random.expovariate(lambd) Exponential distribution. `lambd`

is 1.0 divided by the desired mean value. It must be different from zero (The parameter will be called “lambd”, but this is a reserved word in Python). The returned values range from 0 to positive infinity if `lambd`

is positive, and from negative infinity to 0 if `lambd`

is negative.

```
>>> random.expovariate(1.5)
2.0299375769298558
```

random.gammavariate(alpha, beta) Gamma distribution (Not a gamma function!). The conditions for the parameters are `alpha > 0`

and `beta > 0`

.

```
>>> random.gammavariate(5, 10)
71.54713670428183
```

The probability distribution function:

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

random.gauss(mu, sigma) Gaussian distribution. the `mu`

is the mean value, and `sigma`

is the standard deviation. It is slightly faster than the `normalvariate()`

function labeled below.

```
>>> random.gauss(100, 50)
76.0247266799225
```

random.lognormvariate(mu, sigma) The normal distribution of the logarithm. If you take the natural logarithm of this distribution, you get a normal distribution with mean `mu`

and standard deviation `sigma`

. `the mu`

can have any value, and `the sigma`

must be greater than zero.

```
>>> random.lognormvariate(0, 0.5)
0.8067122423139358
```

random.normalvariate(mu, sigma) Normal distribution. `mu`

is the mean value, and `sigma`

is the standard deviation.

```
>>> random.normalvariate(100, 50)
138.00550761929435
```

random.vonmisesvariate(mu, kappa) `mu`

is the average angle, expressed in radians from 0 to 2pi, and `kappa`

is the concentration parameter, which must be greater than or equal to zero.

```
>>> random.vonmisesvariate(1, 4)
0.8597679422468718
```

If `kappa`

is zero, this distribution reduces to a uniform random angle between 0 and 2pi. random.paretovariate(alpha) The Pareto distribution. `alpha`

is the shape parameter.

```
>>> random.paretovariate(3)
1.2256909386811103
```

random.weibullvariate(alpha, beta) Weibull distribution. `alpha`

is the scale parameter, and `beta`

is the shape parameter.

```
>>> random.weibullvariate(1, 1.5)
1.56960602898881
```

## Alternative generator

random.Random([seed]) A class that implements the default pseudorandom number generator used by the random number module. Available since python 3.9: In the future `seed`

must be one of the following types: None, int, float, str, bytes, or bytearray. random.SystemRandom([seed]) A class that uses the `os.urandom()`

function to generate random numbers from sources provided by the operating system. Not available on all OSes. Does not rely on software state, sequences are not reproducible. Hence the `seed()`

method has no effect and is ignored. When calling `getstate()`

and `setstate()`

methods, get `NotImplementedError`

.

## Examples and Instructions

Basic Examples:

```
>>> free random inport *
>>> random() # random float: 0.0 <= x >> uniform(2.5, 10.0) # random float: 2.5 <= x >> expovariate(1 / 5) # Interval between arrivals averages 5 seconds
5.148957571865031
>>> randrange(10) # Integer from 0 to 9 inclusive
7
>>> randrange(0, 101, 2) # Even integer from 0 to 100 inclusive
26
>>> choice(['win', 'loss', 'draw']) # Random element from the sequence
'draw'
>>> deck = 'one two three four'.split()
>>> shuffle(deck) # Shuffle the list
>>> deck
['four', 'two', 'one', 'three']
>>> sample([10, 20, 30, 40, 50], k=4) # Four elements without replacement
[40, 10, 50, 30]
```

Simulations:

```
>>> # Six roulette results (weighted sample with replacement)
>>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
['red', 'green', 'black', 'black', 'red', 'black']
>>> # Draw 20 cards without replacing a deck of 52 playing cards
>>> # and determine the proportion of cards with a ten-digit value
>>> # (ten, jack, queen, or king).
>>> deck = collections.Counter(tens=16, low_cards=36)
>>> seen = sample(list(deck.elements()), k=20)
>>> seen.count('tens') / 20
0.15
>>> # estimate probability of getting 5 or more wins out of 7 spins
>>> # offset coin, which is on top 60% of the time.
>>> trial = lambda: choices('HT', cum_weights=(0.60, 1.00), k=7).count('H') >= 5
>>> sum(trial() for i in range(10000)) / 10000
0.4169
>>> # Probability of median of 5 samples in the middle two quartiles
>>> trial = lambda : 2500 <= sorted(choices(range(10000), k=5))[2] >> sum(trial() for i in range(10000)) / 10000
0.7958
```