1"""Generate cryptographically strong pseudo-random numbers suitable for
2managing secrets such as account authentication, tokens, and similar.
3
4See PEP 506 for more information.
5https://www.python.org/dev/peps/pep-0506/
6
7"""
8
9__all__ = ['choice', 'randbelow', 'randbits', 'SystemRandom',
10           'token_bytes', 'token_hex', 'token_urlsafe',
11           'compare_digest',
12           ]
13
14
15import base64
16import binascii
17
18from hmac import compare_digest
19from random import SystemRandom
20
21_sysrand = SystemRandom()
22
23randbits = _sysrand.getrandbits
24choice = _sysrand.choice
25
26def randbelow(exclusive_upper_bound):
27    """Return a random int in the range [0, n)."""
28    if exclusive_upper_bound <= 0:
29        raise ValueError("Upper bound must be positive.")
30    return _sysrand._randbelow(exclusive_upper_bound)
31
32DEFAULT_ENTROPY = 32  # number of bytes to return by default
33
34def token_bytes(nbytes=None):
35    """Return a random byte string containing *nbytes* bytes.
36
37    If *nbytes* is ``None`` or not supplied, a reasonable
38    default is used.
39
40    >>> token_bytes(16)  #doctest:+SKIP
41    b'\\xebr\\x17D*t\\xae\\xd4\\xe3S\\xb6\\xe2\\xebP1\\x8b'
42
43    """
44    if nbytes is None:
45        nbytes = DEFAULT_ENTROPY
46    return _sysrand.randbytes(nbytes)
47
48def token_hex(nbytes=None):
49    """Return a random text string, in hexadecimal.
50
51    The string has *nbytes* random bytes, each byte converted to two
52    hex digits.  If *nbytes* is ``None`` or not supplied, a reasonable
53    default is used.
54
55    >>> token_hex(16)  #doctest:+SKIP
56    'f9bf78b9a18ce6d46a0cd2b0b86df9da'
57
58    """
59    return binascii.hexlify(token_bytes(nbytes)).decode('ascii')
60
61def token_urlsafe(nbytes=None):
62    """Return a random URL-safe text string, in Base64 encoding.
63
64    The string has *nbytes* random bytes.  If *nbytes* is ``None``
65    or not supplied, a reasonable default is used.
66
67    >>> token_urlsafe(16)  #doctest:+SKIP
68    'Drmhze6EPcv0fN_81Bj-nA'
69
70    """
71    tok = token_bytes(nbytes)
72    return base64.urlsafe_b64encode(tok).rstrip(b'=').decode('ascii')
73