Apply suggestions from last round of comments

pep-0247.txt

@@ -30,31 +30,42 @@ Specification
         and can ask for the hash value at any time by calling its
         digest() method.
 
-        The 'string' parameter, if supplied, will be immediately hashed
-        into the object's starting state.  For keyed hashes such as
-        HMAC, 'key' is a string containing the starting key.
+        The 'string' parameter, if supplied, will be immediately
+        hashed into the object's starting state; an empty string or
+        None.  For keyed hashes such as HMAC, 'key' is a string
+        containing the starting key.  
+
+        Arbitrary additional keyword arguments can be added to this
+        function, but if they're not supplied, sensible default values
+        should be used.  For example, 'rounds' and 'digestsize' could
+        be added for a hash function which supports a different output
+        size and a different number of rounds.  
 
     Hash function modules define one variable:
 
-    digest_size
+    digestsize
 
         An integer value; the size of the digest produced by the
-        hashing objects, measured in bytes.  You could also obtain
-        this value by creating a sample object, and taking the length
-        of the digest string it returns, but using digest_size is
-        faster.
+        hashing objects created by this module, measured in bytes.
+        You could also obtain this value by creating a sample object
+        and accessing its 'digestsize' attribute, but it can be
+        convenient to have this value available from the module.
+        Hashes with a variable output size will set this variable to 0.
+
+    The attributes of a hashing object are:
+
+    digestsize
+
+        An integer value; the size of the digest produced by the
+        hashing object, measured in bytes.  If the hash has a variable
+        output size, this output size must be chosen when the
+        hashing object is created, and this attribute must contain the
+        selected size.  Therefore 0 is *not* a legal value for this
+        attribute.
+                
 
     The methods for hashing objects are always the following:
 
-    clear()
-
-        Reset this hashing object to its initial state, as if the
-        object was created from new(key=<initially specified key>)
-        (XXX what should this do for a keyed hash?  A proposed
-        semantic follows:).  There is no way to supply a starting
-        string as there is for the new() function, and there's no way
-        to change the key specified for a keyed hash.
-
     copy()
 
         Return a separate copy of this hashing object.  An update to
@@ -62,14 +73,30 @@ Specification
 
     digest()
 
-        Return the hash value of this hashing object, as a string
+        Return the hash value of this hashing object as a string
         containing 8-bit data.  The object is not altered in any way
         by this function; you can continue updating the object after
         calling this function.
 
+    hexdigest()
+
+        Return the hash value of this hashing object as a string
+        containing hexadecimal digits.  Lowercase letters should be used 
+        for the digits 'a' through 'f'.  Like the .digest() method, this
+        method mustn't alter the object.
+        
+    reset()
+
+        Reset this hashing object to its initial state, as if the
+        object was created from new(key=<initially specified key>)
+        (XXX what should this do for a keyed hash?  A proposed
+        semantic follows:).  There is no way to supply a starting
+        string as there is for the new() function, and there's no way
+        to change the key specified for a keyed hash.
+
     update(arg)
 
-        Update this hashing object with the string arg.
+        Update this hashing object with the string 'arg'.
 
     For convenience, hashing objects also have a digest_size
     attribute, measuring the size of the resulting digest in bytes.
@@ -79,14 +106,29 @@ Specification
 
         >>> from Crypto.Hash import MD5
         >>> m = MD5.new()
+        >>> m.digestsize
+        16
         >>> m.update('abc')
         >>> m.digest()
-        '\220\001P\230<\322O\260\326\226?@}(\341\177r'
-
+        '\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'    
+        >>> m.hexdigest()
+        '900150983cd24fb0d6963f7d28e17f72' 
     Or, more compactly:
 
         >>> MD5.new('abc').digest()
-        '\220\001P\230<\322O\260\326\226?@}(\341\177r'
+        '\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'    
+
+
+Changes
+
+    2001-09-17: Renamed clear() to reset; added digestsize attribute
+    to objects; added .hexdigest() method.
+
+
+Acknowledgements
+
+    Thanks to Andrew Archibald, Rich Salz, and the readers of the
+    python-crypto list for their comments on this PEP.
 
 
 Copyright