Automated merge with ssh://hg.python.org/cpython

Steven D'Aprano · Steven D'Aprano · commit 5562563dd4a7 · 2016-04-17T13:14:48.000+10:00
diff --git a/Doc/library/secrets.rst b/Doc/library/secrets.rst
@@ -88,7 +88,7 @@ hard-to-guess URLs, and similar.
 .. function:: token_urlsafe([nbytes=None])
 
    Return a random URL-safe text string, containing *nbytes* random
-   bytes.  The text is Base64 encoded, so on average, each byte results
+   bytes.  The text is Base64 encoded, so on average each byte results
    in approximately 1.3 characters.  If *nbytes* is ``None`` or not
    supplied, a reasonable default is used.
 
@@ -106,7 +106,7 @@ To be secure against
 tokens need to have sufficient randomness.  Unfortunately, what is
 considered sufficient will necessarily increase as computers get more
 powerful and able to make more guesses in a shorter period.  As of 2015,
-it is believed that 64 bytes (512 bits) of randomness is sufficient for
+it is believed that 32 bytes (256 bits) of randomness is sufficient for
 the typical use-case expected for the :mod:`secrets` module.
 
 For those who want to manage their own token length, you can explicitly
@@ -129,8 +129,8 @@ Other functions
 .. function:: compare_digest(a, b)
 
    Return ``True`` if strings *a* and *b* are equal, otherwise ``False``,
-   in such a way as to redice the risk of
-   `timing attacks <http://codahale.com/a-lesson-in-timing-attacks/>`_ .
+   in such a way as to reduce the risk of
+   `timing attacks <http://codahale.com/a-lesson-in-timing-attacks/>`_.
    See :func:`hmac.compare_digest` for additional details.
 
 
@@ -151,11 +151,10 @@ Generate an eight-character alphanumeric password:
 
 .. note::
 
-   Applications should
-   `not store passwords in a recoverable format <http://cwe.mitre.org/data/definitions/257.html>`_ ,
-   whether plain text or encrypted.  They should always be salted and
-   hashed using a cryptographically-strong one-way (irreversible) hash
-   function.
+   Applications should not
+   `store passwords in a recoverable format <http://cwe.mitre.org/data/definitions/257.html>`_,
+   whether plain text or encrypted.  They should be salted and hashed
+   using a cryptographically-strong one-way (irreversible) hash function.
 
 
 Generate a ten-character alphanumeric password with at least one
@@ -174,7 +173,7 @@ three digits:
            break
 
 
-Generate an `XKCD-style passphrase <http://xkcd.com/936/>`_ :
+Generate an `XKCD-style passphrase <http://xkcd.com/936/>`_:
 
 .. testcode::
 
diff --git a/Lib/secrets.py b/Lib/secrets.py
@@ -1,84 +1,9 @@
 """Generate cryptographically strong pseudo-random numbers suitable for
 managing secrets such as account authentication, tokens, and similar.
-See PEP 506 for more information.
 
+See PEP 506 for more information.
 https://www.python.org/dev/peps/pep-0506/
 
-
-Random numbers
-==============
-
-The ``secrets`` module provides the following pseudo-random functions, based
-on SystemRandom, which in turn uses the most secure source of randomness your
-operating system provides.
-
-
-    choice(sequence)
-        Choose a random element from a non-empty sequence.
-
-    randbelow(n)
-        Return a random int in the range [0, n).
-
-    randbits(k)
-        Generates an int with k random bits.
-
-    SystemRandom
-        Class for generating random numbers using sources provided by
-        the operating system. See the ``random`` module for documentation.
-
-
-Token functions
-===============
-
-The ``secrets`` module provides a number of functions for generating secure
-tokens, suitable for applications such as password resets, hard-to-guess
-URLs, and similar. All the ``token_*`` functions take an optional single
-argument specifying the number of bytes of randomness to use. If that is
-not given, or is ``None``, a reasonable default is used. That default is
-subject to change at any time, including during maintenance releases.
-
-
-    token_bytes(nbytes=None)
-        Return a random byte-string containing ``nbytes`` number of bytes.
-
-        >>> secrets.token_bytes(16)  #doctest:+SKIP
-        b'\\xebr\\x17D*t\\xae\\xd4\\xe3S\\xb6\\xe2\\xebP1\\x8b'
-
-
-    token_hex(nbytes=None)
-        Return a random text-string, in hexadecimal. The string has ``nbytes``
-        random bytes, each byte converted to two hex digits.
-
-        >>> secrets.token_hex(16)  #doctest:+SKIP
-        'f9bf78b9a18ce6d46a0cd2b0b86df9da'
-
-    token_urlsafe(nbytes=None)
-        Return a random URL-safe text-string, containing ``nbytes`` random
-        bytes. On average, each byte results in approximately 1.3 characters
-        in the final result.
-
-        >>> secrets.token_urlsafe(16)  #doctest:+SKIP
-        'Drmhze6EPcv0fN_81Bj-nA'
-
-
-(The examples above assume Python 3. In Python 2, byte-strings will display
-using regular quotes ``''`` with no prefix, and text-strings will have a
-``u`` prefix.)
-
-
-Other functions
-===============
-
-    compare_digest(a, b)
-        Return True if strings a and b are equal, otherwise False.
-        Performs the equality comparison in such a way as to reduce the
-        risk of timing attacks.
-
-        See http://codahale.com/a-lesson-in-timing-attacks/ for a
-        discussion on how timing attacks against ``==`` can reveal
-        secrets from your application.
-
-
 """
 
 __all__ = ['choice', 'randbelow', 'randbits', 'SystemRandom',
@@ -100,18 +25,47 @@
 choice = _sysrand.choice
 
 def randbelow(exclusive_upper_bound):
+    """Return a random int in the range [0, n)."""
     return _sysrand._randbelow(exclusive_upper_bound)
 
 DEFAULT_ENTROPY = 32  # number of bytes to return by default
 
 def token_bytes(nbytes=None):
+    """Return a random byte string containing *nbytes* bytes.
+
+    If *nbytes* is ``None`` or not supplied, a reasonable
+    default is used.
+
+    >>> token_bytes(16)  #doctest:+SKIP
+    b'\\xebr\\x17D*t\\xae\\xd4\\xe3S\\xb6\\xe2\\xebP1\\x8b'
+
+    """
     if nbytes is None:
         nbytes = DEFAULT_ENTROPY
     return os.urandom(nbytes)
 
 def token_hex(nbytes=None):
+    """Return a random text string, in hexadecimal.
+
+    The string has *nbytes* random bytes, each byte converted to two
+    hex digits.  If *nbytes* is ``None`` or not supplied, a reasonable
+    default is used.
+
+    >>> token_hex(16)  #doctest:+SKIP
+    'f9bf78b9a18ce6d46a0cd2b0b86df9da'
+
+    """
     return binascii.hexlify(token_bytes(nbytes)).decode('ascii')
 
 def token_urlsafe(nbytes=None):
+    """Return a random URL-safe text string, in Base64 encoding.
+
+    The string has *nbytes* random bytes.  If *nbytes* is ``None``
+    or not supplied, a reasonable default is used.
+
+    >>> token_urlsafe(16)  #doctest:+SKIP
+    'Drmhze6EPcv0fN_81Bj-nA'
+
+    """
     tok = token_bytes(nbytes)
     return base64.urlsafe_b64encode(tok).rstrip(b'=').decode('ascii')
