bpo-33729: Fix issues with arguments parsing in hashlib. (GH-8346)

* help(hashlib) didn't work because of incorrect module name in blake2b and
  blake2s classes.
* Constructors blake2*(), sha3_*(), shake_*() and keccak_*() incorrectly
  accepted keyword argument "string" for binary data, but documented as
  accepting the "data" keyword argument. Now this parameter is positional-only.
* Keyword-only parameters in blake2b() and blake2s() were not documented as
  keyword-only.
* Default value for some parameters of blake2b() and blake2s() was None,
  which is not acceptable value.
* The length argument for shake_*.digest() was wrapped out to 32 bits.
* The argument for shake_128.digest() and shake_128.hexdigest() was not
  positional-only as intended.
* TypeError messages for incorrect arguments in all constructors sha3_*(),
  shake_*() and keccak_*() incorrectly referred to sha3_224.

Also made the following enhancements:

* More accurately specified input and result types for strings, bytes and
  bytes-like objects.
* Unified positional parameter names for update() and constructors.
* Improved formatting.

1 files changed, 14 insertions, 13 deletions

diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index da941e5..baf6b0a 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -101,7 +101,7 @@ More condensed:
 
 .. function:: new(name[, data])
 
-   Is a generic constructor that takes the string name of the desired
+   Is a generic constructor that takes the string *name* of the desired
    algorithm as its first parameter.  It also exists to allow access to the
    above listed hashes as well as any other algorithms that your OpenSSL
    library may offer.  The named constructors are much faster than :func:`new`
@@ -162,10 +162,10 @@ A hash object has the following attributes:
 A hash object has the following methods:
 
 
-.. method:: hash.update(arg)
+.. method:: hash.update(data)
 
-   Update the hash object with the object *arg*, which must be interpretable as
-   a buffer of bytes.  Repeated calls are equivalent to a single call with the
+   Update the hash object with the :term:`bytes-like object`.
+   Repeated calls are equivalent to a single call with the
    concatenation of all the arguments: ``m.update(a); m.update(b)`` is
    equivalent to ``m.update(a+b)``.
 
@@ -206,7 +206,7 @@ by the SHAKE algorithm.
 .. method:: shake.digest(length)
 
    Return the digest of the data passed to the :meth:`update` method so far.
-   This is a bytes object of size ``length`` which may contain bytes in
+   This is a bytes object of size *length* which may contain bytes in
    the whole range from 0 to 255.
 
 
@@ -262,9 +262,10 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
    The function provides scrypt password-based key derivation function as
    defined in :rfc:`7914`.
 
-   *password* and *salt* must be bytes-like objects. Applications and
-   libraries should limit *password* to a sensible length (e.g. 1024). *salt*
-   should be about 16 or more bytes from a proper source, e.g. :func:`os.urandom`.
+   *password* and *salt* must be :term:`bytes-like objects
+   <bytes-like object>`.  Applications and libraries should limit *password*
+   to a sensible length (e.g. 1024).  *salt* should be about 16 or more
+   bytes from a proper source, e.g. :func:`os.urandom`.
 
    *n* is the CPU/Memory cost factor, *r* the block size, *p* parallelization
    factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
@@ -305,11 +306,11 @@ Creating hash objects
 New hash objects are created by calling constructor functions:
 
 
-.. function:: blake2b(data=b'', digest_size=64, key=b'', salt=b'', \
+.. function:: blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', \
                 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0,  \
                 node_depth=0, inner_size=0, last_node=False)
 
-.. function:: blake2s(data=b'', digest_size=32, key=b'', salt=b'', \
+.. function:: blake2s(data=b'', *, digest_size=32, key=b'', salt=b'', \
                 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0,  \
                 node_depth=0, inner_size=0, last_node=False)
 
@@ -317,8 +318,8 @@ New hash objects are created by calling constructor functions:
 These functions return the corresponding hash objects for calculating
 BLAKE2b or BLAKE2s. They optionally take these general parameters:
 
-* *data*: initial chunk of data to hash, which must be interpretable as buffer
-  of bytes.
+* *data*: initial chunk of data to hash, which must be
+  :term:`bytes-like object`.  It can be passed only as positional argument.
 
 * *digest_size*: size of output digest in bytes.
 
@@ -427,7 +428,7 @@ object, and, finally, get the digest out of the object by calling
 
 
 As a shortcut, you can pass the first chunk of data to update directly to the
-constructor as the first argument (or as *data* keyword argument):
+constructor as the positional argument:
 
     >>> from hashlib import blake2b
     >>> blake2b(b'Hello world').hexdigest()