[PATCHv2 1/4] Simplify & document savemessage_getnewheader

[Sebastian Spaeth]

savemessage_getnewheader was an undocmented, cryptic and overengineered
function. It generates a new unique value that can be used as a mail
header to be inserted. For this it used LOTS of randomness sources: hash
of the mail content, hash of the folder name, hash of the repository
name, the current time, a random() value, and the offlineimap version string.
All we need is something random. So reduce this to hash of content
appended by a random integer. Sufficient and somewhat faster to calculate.

Rename the function to actually describe accurately what it does or
would you have guessed that savemessage_getnewheader() did nothing more
than returning ('X-OfllineIMAP', <randomstring> )? Rename to
generate_randomheader() to make it clearer what this is all about.

Also document the function, describing what it does, and what it returns.

Signed-off-by: Sebastian Spaeth <Sebastian at SSpaeth.de>
--- 

v2 withh added code comment per Nicolas' suggestion. I know its ironic to triple the lines
of code while speaking of doing away with overengineering, but I like
code comments. And that is all that it is, comments. :-)

 offlineimap/folder/IMAP.py |   33 +++++++++++++++++++++++++--------
 1 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py
index be96d5f..869ec5c 100644
--- a/offlineimap/folder/IMAP.py
+++ b/offlineimap/folder/IMAP.py
@@ -226,16 +226,33 @@ class IMAPFolder(BaseFolder):
     def getmessageflags(self, uid):
         return self.messagelist[uid]['flags']
 
-    def savemessage_getnewheader(self, content):
+    def generate_randomheader(self, content):
+        """Returns a unique X-OfflineIMAP header
+
+        Generate an 'X-OfflineIMAP' mail header which contains a random
+        unique value (which is based on the mail content, and a random
+        number). This header allows us to fetch a mail after APPENDing
+        it to an IMAP server and thus find out the UID that the server
+        assigned it.
+
+        :returns: (headername, headervalue) tuple, consisting of strings
+                  headername == 'X-OfflineIMAP' and headervalue will be a
+                  random string
+        """
         headername = 'X-OfflineIMAP'
-        headervalue = '%s-' % str(binascii.crc32(content)).replace('-', 'x')
-        headervalue += binascii.hexlify(self.repository.getname()) + '-'
-        headervalue += binascii.hexlify(self.getname())
-        headervalue += '-%d-' % long(time.time())
-        headervalue += str(self.randomgenerator.random()).replace('.', '')
-        headervalue += '-v' + versionstr
+        # We need a random component too. If we ever upload the same
+        # mail twice (e.g. in different folders), we would still need to
+        # get the UID for the correct one. As we won't have too many
+        # mails with identical content in one folder, the randomness
+        # requirements are not extremly critial though.
+
+        # Compute unsigned crc32 of 'content' as unique hash
+        # NB: crc32 returns unsigned only starting with python 3.0
+        headervalue  = str(binascii.crc32(content) & 0xffffffff) + '-'
+        headervalue += str(self.randomgenerator.randint(0,99999999999))
         return (headername, headervalue)
 
+
     def savemessage_addheader(self, content, headername, headervalue):
         ui = UIBase.getglobalui()
         ui.debug('imap',
@@ -335,7 +352,7 @@ class IMAPFolder(BaseFolder):
             content = re.sub("(?<!\r)\n", "\r\n", content)
             ui.debug('imap', 'savemessage: initial content is: ' + repr(content))
 
-            (headername, headervalue) = self.savemessage_getnewheader(content)
+            (headername, headervalue) = self.generate_randomheader(content)
             ui.debug('imap', 'savemessage: new headers are: %s: %s' % \
                      (headername, headervalue))
             content = self.savemessage_addheader(content, headername,
-- 
1.7.1