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://peps.python.org/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 16 17from hmac import compare_digest 18from random import SystemRandom 19 20_sysrand = SystemRandom() 21 22randbits = _sysrand.getrandbits 23choice = _sysrand.choice 24 25def randbelow(exclusive_upper_bound): 26 """Return a random int in the range [0, n).""" 27 if exclusive_upper_bound <= 0: 28 raise ValueError("Upper bound must be positive.") 29 return _sysrand._randbelow(exclusive_upper_bound) 30 31DEFAULT_ENTROPY = 32 # number of bytes to return by default 32 33def token_bytes(nbytes=None): 34 """Return a random byte string containing *nbytes* bytes. 35 36 If *nbytes* is ``None`` or not supplied, a reasonable 37 default is used. 38 39 >>> token_bytes(16) #doctest:+SKIP 40 b'\\xebr\\x17D*t\\xae\\xd4\\xe3S\\xb6\\xe2\\xebP1\\x8b' 41 42 """ 43 if nbytes is None: 44 nbytes = DEFAULT_ENTROPY 45 return _sysrand.randbytes(nbytes) 46 47def token_hex(nbytes=None): 48 """Return a random text string, in hexadecimal. 49 50 The string has *nbytes* random bytes, each byte converted to two 51 hex digits. If *nbytes* is ``None`` or not supplied, a reasonable 52 default is used. 53 54 >>> token_hex(16) #doctest:+SKIP 55 'f9bf78b9a18ce6d46a0cd2b0b86df9da' 56 57 """ 58 return token_bytes(nbytes).hex() 59 60def token_urlsafe(nbytes=None): 61 """Return a random URL-safe text string, in Base64 encoding. 62 63 The string has *nbytes* random bytes. If *nbytes* is ``None`` 64 or not supplied, a reasonable default is used. 65 66 >>> token_urlsafe(16) #doctest:+SKIP 67 'Drmhze6EPcv0fN_81Bj-nA' 68 69 """ 70 tok = token_bytes(nbytes) 71 return base64.urlsafe_b64encode(tok).rstrip(b'=').decode('ascii') 72