Rev 209: Added docstrings, as per jml's review. in http://bzr.daniel-watkins.co.uk/pqm/xmlrpc

[Daniel Watkins]

At http://bzr.daniel-watkins.co.uk/pqm/xmlrpc

------------------------------------------------------------
revno: 209
revision-id: daniel at daniel-watkins.co.uk-20080807020420-6seg494lf57h9yuo
parent: daniel at daniel-watkins.co.uk-20080807014409-e2c7qy30w93zfeqe
committer: Daniel Watkins <daniel at daniel-watkins.co.uk>
branch nick: xmlrpc
timestamp: Thu 2008-08-07 03:04:20 +0100
message:
  Added docstrings, as per jml's review.
-------------- next part --------------
=== modified file 'pqm/script.py'
--- a/pqm/script.py	2008-08-07 01:32:06 +0000
+++ b/pqm/script.py	2008-08-07 02:04:20 +0000
@@ -37,7 +37,16 @@
 
 
 def get_email_structure(logger, msg):
-    """Read an email and check it has the required structure for commands."""
+    """Read an email and check it has the required structure for commands.
+
+    :param logger: The logger to which messages should be sent.
+    :param msg: A Message to be checked.
+
+    :return: A tuple consisting of ( message sender, message subject, message
+        text, message signature ).  The message signature will be None unless it
+        the message is multipart and the second part of the message is a PGP
+        signature.
+    """
     sender = msg['From']
     logger.info("recieved email from %s", sender)
     subject = msg['Subject']
@@ -70,6 +79,20 @@
 
 
 def read_email_from_file(logger, file=None):
+    """Read an email from a file, check for the structure for commands.
+
+    This is a convenience wrapper around get_email_structure, so that callers
+    don't have to worry about using the email module correctly.
+
+    :param logger: The logger to which messages should be sent.
+    :param file: An open file-like object containing an email message.  If not
+        specified, defaults to sys.stdin.
+
+    :return: A tuple consisting of ( message sender, message subject, message
+        text, message signature ).  The message signature will be None unless it
+        the message is multipart and the second part of the message is a PGP
+        signature.
+    """
     if not file:
         file = sys.stdin
     msg = email.message_from_file(file)
@@ -77,11 +100,36 @@
 
 
 def read_email_from_string(logger, string):
+    """Read an email from a string, check for the structure for commands.
+
+    This is a convenience wrapper around get_email_structure, so that callers
+    don't have to worry about using the email module correctly.
+
+    :param logger: The logger to which messages should be sent.
+    :param string: A string containing an email message.
+
+    :return: A tuple consisting of ( message sender, message subject, message
+        text, message signature ).  The message signature will be None unless it
+        the message is multipart and the second part of the message is a PGP
+        signature.
+    """
     msg = email.message_from_string(string)
     return get_email_structure(logger, msg)
 
 
 def get_email_string(logger, options, email):
+    """Get the string for an email, checking it is signed correctly.
+
+    :param logger: The logger to which messages should be sent.
+    :param options: An object containing the options which should be used for
+        signing.
+    :param email: A tuple consisting of ( message sender, message subject,
+        message text, message signature ).  The message signature should be None
+        if either there is no signature for the email or the signature was not
+        in its own part of a multipart email.
+
+    :return: A string representing the given email tuple.
+    """
     (sender, subject, msg, sig) = email
     if options.verify_sigs:
         # TODO: Daniel Watkins, 2008-07-31