[Python-checkins] CVS: python/nondist/peps pep-0247.txt,1.3,1.4

[A.M. Kuchling]

Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv20727

Modified Files:
	pep-0247.txt 
Log Message:
Apply suggestions from last round of comments


Index: pep-0247.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0247.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0247.txt	2001/07/09 03:57:09	1.3
--- pep-0247.txt	2001/09/17 15:09:37	1.4
***************
*** 31,58 ****
          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.
  
      Hash function modules define one variable:
  
!     digest_size
  
          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.
  
!     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()
--- 31,69 ----
          digest() method.
  
!         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:
  
!     digestsize
  
          An integer value; the size of the digest produced by the
!         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:
  
      copy()
***************
*** 63,74 ****
      digest()
  
!         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.
  
      update(arg)
  
!         Update this hashing object with the string arg.
  
      For convenience, hashing objects also have a digest_size
--- 74,101 ----
      digest()
  
!         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'.
  
      For convenience, hashing objects also have a digest_size
***************
*** 80,91 ****
          >>> from Crypto.Hash import MD5
          >>> m = MD5.new()
          >>> m.update('abc')
          >>> m.digest()
!         '\220\001P\230<\322O\260\326\226?@}(\341\177r'
! 
      Or, more compactly:
  
          >>> MD5.new('abc').digest()
!         '\220\001P\230<\322O\260\326\226?@}(\341\177r'
  
  
--- 107,133 ----
          >>> from Crypto.Hash import MD5
          >>> m = MD5.new()
+         >>> m.digestsize
+         16
          >>> m.update('abc')
          >>> m.digest()
!         '\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'    
!         >>> m.hexdigest()
!         '900150983cd24fb0d6963f7d28e17f72' 
      Or, more compactly:
  
          >>> MD5.new('abc').digest()
!         '\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.