Mailing-List: contact commits-help@ponymail.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@ponymail.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: sebb@apache.org
To: commits@ponymail.incubator.apache.org
Message-Id: <9fcccd4e7e064a7c9e287478248dc3c2@git.apache.org>
Subject: incubator-ponymail git commit: Add some documentation
Date: Mon,  5 Jun 2017 23:31:26 +0000 (UTC)
archived-at: Mon, 05 Jun 2017 23:31:31 -0000

Repository: incubator-ponymail
Updated Branches:
  refs/heads/master 15c355442 -> 0a8e8b8ff


Add some documentation

Project: http://git-wip-us.apache.org/repos/asf/incubator-ponymail/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ponymail/commit/0a8e8b8f
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ponymail/tree/0a8e8b8f
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ponymail/diff/0a8e8b8f

Branch: refs/heads/master
Commit: 0a8e8b8ffba08ff262579a99c16dbe08c1bde2d3
Parents: 15c3554
Author: Sebb <sebb@apache.org>
Authored: Tue Jun 6 00:31:00 2017 +0100
Committer: Sebb <sebb@apache.org>
Committed: Tue Jun 6 00:31:00 2017 +0100

----------------------------------------------------------------------
 tools/generators.py | 45 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-ponymail/blob/0a8e8b8f/tools/generators.py
----------------------------------------------------------------------
diff --git a/tools/generators.py b/tools/generators.py
index b1d8e28..2ac2ca8 100644
--- a/tools/generators.py
+++ b/tools/generators.py
@@ -26,12 +26,34 @@ import time
 # Full generator: uses the entire email (including server-dependent data)
 # This is the recommended generator for single-node setups.
 def full(msg, body, lid, attachments):
+    """
+    Full generator: uses the entire email
+    (including server-dependent data)
+    The id is almost certainly unique,
+    but different copies of the message are likely to have different headers, thus ids
+    
+    Parameters:
+    msg - the parsed message
+    body - the parsed text content (not used)
+    lid - list id
+    attachments - list of attachments (not used)
+    """
     mid = "%s@%s" % (hashlib.sha224(msg.as_bytes()).hexdigest(), lid)
     return mid
 
 # Medium: Standard 0.9 generator - Not recommended for future installations.
 # See 'full' or 'redundant' generators instead.
 def medium(msg, body, lid, attachments):
+    """
+    Standard 0.9 generator - Not recommended for future installations.
+    (does not generate sufficiently unique ids)
+    
+    Parameters:
+    msg - the parsed message (used to get the date)
+    body - the parsed text content
+    lid - list id
+    attachments - list of attachments (not used)
+    """
     # Use text body
     xbody = body if type(body) is bytes else body.encode('ascii', 'ignore')
     # Use List ID
@@ -61,6 +83,16 @@ def medium(msg, body, lid, attachments):
 # Unlike 'medium', this only makes use of the Date: header and not the archived-at,
 # as the archived-at may change from node to node (and will change if not in the raw mbox file)
 def redundant(msg, body, lid, attachments):
+    """
+    Use data that is guaranteed to be the same across redundant setups
+    (does not guarantee to create unique ids)
+    
+    Parameters:
+    msg - the parsed message (used to get the date)
+    body - the parsed text content
+    lid - list id
+    attachments - list of attachments (uses the hashes)
+    """
     # Use text body
     xbody = body if type(body) is bytes else body.encode('ascii', 'ignore')
     # Use List ID
@@ -92,6 +124,16 @@ def redundant(msg, body, lid, attachments):
 
 # Old school way of making IDs
 def legacy(msg, body, lid, attachments):
+    """
+    Original generator - DO NOT USE
+    (does not generate unique ids)
+    
+    Parameters:
+    msg - the parsed message (used to get the date)
+    body - the parsed text content
+    lid - list id
+    attachments - list of attachments (not used)
+    """
     uid_mdate = 0 # Default if no date found
     try:
         mdate = email.utils.parsedate_tz(msg.get('date'))
@@ -100,6 +142,3 @@ def legacy(msg, body, lid, attachments):
         pass
     mid = "%s@%s@%s" % (hashlib.sha224(body if type(body) is bytes else body.encode('ascii', 'ignore')).hexdigest(), uid_mdate, lid)
     return mid
-
-
-