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

[A.M. Kuchling]

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

Modified Files:
	pep-0247.txt 
Log Message:
Finalize interface for keyed hashes, and add a paragraph to the rationale
    section describing the reasoning behind using (key, [string]) as the 
    signature.

This PEP is ready to be marked Final.


Index: pep-0247.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0247.txt,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** pep-0247.txt	2001/10/22 02:10:29	1.8
--- pep-0247.txt	2001/10/31 02:26:25	1.9
***************
*** 24,36 ****
      Hash function modules define one function:
  
!     new([string])
!     new([key] , [string])
  
          Create a new hashing object and return it.  The first form is
!         for hashes that are unkeyed; most hashes such as MD5 or SHA
!         are unkeyed.  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, as if obj.update(string) was called.
          
          After creating a hashing object, arbitrary strings can be fed
--- 24,37 ----
      Hash function modules define one function:
  
!     new([string])            (unkeyed hashes)
!     new([key] , [string])    (keyed hashes)
  
          Create a new hashing object and return it.  The first form is
!         for hashes that are unkeyed, such as MD5 or SHA.  For keyed
!         hashes such as HMAC, 'key' is a required parameter containing
!         a string giving the key to use.  In both cases, the optional
!         'string' parameter, if supplied, will be immediately hashed
!         into the object's starting state, as if obj.update(string) was
!         called.
          
          After creating a hashing object, arbitrary strings can be fed
***************
*** 132,135 ****
--- 133,146 ----
      used by the md5 and sha modules included with Python, so it seems
      simplest to leave the name update() alone.
+ 
+     The order of the constructor's arguments for keyed hashes was a
+     sticky issue.  It wasn't clear whether the key should come first
+     or second.  It's a required parameter, and the usual convention is
+     to place required parameters first, but that also means that the
+     'string' parameter moves from the first position to the second.
+     It would be possible to get confused and pass a single argument to
+     a keyed hash, thinking that you're passing an initial string to an 
+     unkeyed hash, but it doesn't seem worth making the interface 
+     for keyed hashes more obscure to avoid this potential error.