[Python-checkins] peps: Make API And Implementation section less wishy-washy.

[steven.daprano]

https://hg.python.org/peps/rev/c14c62e1f6d6
changeset:   6278:c14c62e1f6d6
user:        Steven D'Aprano <steve at pearwood.info>
date:        Tue Apr 12 03:26:55 2016 +1000
summary:
  Make API And Implementation section less wishy-washy.

Per GvR's request, be more specific about what is included.

files:
  pep-0506.txt |  42 +++++++++++++++++----------------------
  1 files changed, 18 insertions(+), 24 deletions(-)


diff --git a/pep-0506.txt b/pep-0506.txt
--- a/pep-0506.txt
+++ b/pep-0506.txt
@@ -113,13 +113,14 @@
 API and Implementation
 ======================
 
-The contents of the ``secrets`` module is expected to evolve over time, and
-likely will evolve between the time of writing this PEP and actual release
-in the standard library [#]_.  At the time of writing, the following functions
-have been suggested:
+This PEP proposes the following functions for the ``secrets`` module:
 
-* A high-level function for generating secure tokens suitable for use
-  in (e.g.) password recovery, as session keys, etc.
+* Functions for generating tokens suitable for use in (e.g.) password
+  recovery, as session keys, etc., in the following formats:
+
+  - as bytes, ``secrets.token_bytes``;
+  - as text, using hexadecimal digits, ``secrets.token_hex``;
+  - as text, using URL-safe base-64 encoding, ``secrets.token_urlsafe``.
 
 * A limited interface to the system CSPRNG, using either ``os.urandom``
   directly or ``random.SystemRandom``.  Unlike the ``random`` module, this
@@ -128,13 +129,13 @@
   following:
 
   - A function for choosing items from a sequence, ``secrets.choice``.
-  - A function for generating an integer within some range, such as
-    ``secrets.randrange`` or ``secrets.randint`` [#]_.
   - A function for generating a given number of random bits and/or bytes
-    as an integer.
-  - A similar function which returns the value as a hex digit string.
+    as an integer, ``secrets.randbits``.
+  - A function for returning a random integer in the half-open range
+    0 to the given upper limit, ``secrets.randbelow`` [#]_.
 
-* ``hmac.compare_digest`` under the name ``equal``.
+* A function for comparing text or bytes digests for equality while being
+  resistent to timing attacks, ``secrets.compare_digest``.
 
 The consensus appears to be that there is no need to add a new CSPRNG to
 the ``random`` module to support these uses, ``SystemRandom`` will be
@@ -143,16 +144,14 @@
 Some illustrative implementations have been given by Nick Coghlan [#]_
 and a minimalist API by Tim Peters [#]_. This idea has also been discussed
 on the issue tracker for the "cryptography" module [#]_.  The following
-pseudo-code can be taken as a possible starting point for the real
+pseudo-code should be taken as the starting point for the real
 implementation::
 
     from random import SystemRandom
-    from hmac import compare_digest as equal
+    from hmac import compare_digest
 
     _sysrand = SystemRandom()
 
-    randrange = _sysrand.randrange
-    randint = _sysrand.randint
     randbits = _sysrand.getrandbits
     choice = _sysrand.choice
 
@@ -169,7 +168,7 @@
     def token_hex(nbytes=None):
         return binascii.hexlify(token_bytes(nbytes)).decode('ascii')
 
-    def token_url(nbytes=None):
+    def token_urlsafe(nbytes=None):
         tok = token_bytes(nbytes)
         return base64.urlsafe_b64encode(tok).rstrip(b'=').decode('ascii')
 
@@ -372,14 +371,9 @@
 
 .. [#] At least those who are motivated to read the source code and documentation.
 
-.. [#] Tim Peters suggests that bike-shedding the contents of the module will
-       be 10000 times more time consuming than actually implementing the
-       module.  Words do not begin to express how much I am looking forward to
-       this.
-
-.. [#] After considerable discussion, Guido ruled that the module will instead
-       provide a function, ``randbelow``. See
-       http://code.activestate.com/lists/python-dev/138375/
+.. [#] After considerable discussion, Guido ruled that the module need only
+       provide ``randbelow``, and not similar functions ``randrange`` or
+       ``randint``.  http://code.activestate.com/lists/python-dev/138375/
 
 .. [#] https://mail.python.org/pipermail/python-ideas/2015-September/036271.html
 

-- 
Repository URL: https://hg.python.org/peps