Minor fixes for mail_utils

- update module description
- add missing docu
- add link to MailValidator and ImapMailbox docu
- correct comment
- fix wrapping of 3 lines
- remove one useless else

diff --git a/src/mail_utils.py b/src/mail_utils.py
index b3a0b50..9efc632 100644 (file)
--- a/src/mail_utils.py
+++ b/src/mail_utils.py
@@ -24,8 +24,10 @@
 
 SUMMARY
 ------------------------------------------------------
-Guest utility for fetchmail, spamassassin, horde and other email functionality
-tests.
+Utilities for dealing with email
+
+.. seealso:: :py:mod:`pyi2ncommon.mail_validator`,
+             :py:mod:`pyi2ncommon.imap_mailbox`
 
 Copyright: Intra2net AG
 
@@ -198,16 +200,19 @@ def parse_mail_date(message):
 
 def get_user_mail_files(user, mailbox='INBOX'):
     """
-    Iterate over mails in given folder of given user; yields file names
+    Iterate over mails in given folder of given user; yields file names.
+
+    Works on local cyrus file system, not on imap server.
 
-    :param str mailbox: name of mailbox to use, INBOX (default) for base folder;
-                        name is modified using :py:func:`cyrus_escape`
+    :param str user: Name of user whose mailbox is analyzed
+    :param str mailbox: name of mailbox to use, INBOX (default) for base
+                        folder; name is modified using :py:func:`cyrus_escape`
     :returns: nothing; but yields full path to messages on disc
     """
     # base folder of user mail
     folder = os.path.join('/datastore', 'imap-mails', 'user', user)
 
-    # adapt paths like "INBOX/sub/dir" need to "sub/dir"
+    # adapt paths like "INBOX/sub/dir" to "sub/dir"
     subdirs = mailbox.split('/')
     if subdirs[0].upper() == 'INBOX':
         subdirs = subdirs[1:]
@@ -225,8 +230,8 @@ def get_user_mail(user, mailbox='INBOX', **kwargs):
     """
     Iterate over mails in given folder of given user; yields parsed mails.
 
-    :param str mailbox: name of mailbox to use, INBOX (default) for base folder;
-                        name is modified using :py:func:`cyrus_escape`
+    :param str user: see :py:func:`get_user_mail_files`
+    :param str mailbox: see :py:func:`get_user_mail_files`
     :param dict kwargs: all other args are forwarded to
                         :py:func:`parse_mail_file`
     :returns: nothing; but yields 2-tuples (path, email_msg) where first is the
@@ -262,6 +267,8 @@ def get_message_text(filename, fallback_encoding='iso8859-1',
     being the first.
 
     :param str filename: complete path of message file in filesystem
+    :param str fallback_encoding: Encoding of email text if none is specified
+                                  in mail.
     :param bool include_all_text: include all "text/*" parts in returned text
     :returns: text(s) of message
     :rtype: [str] if include_all_text else str
@@ -336,8 +343,7 @@ def cyrus_escape(user_or_folder, keep_path=False, regex=False):
     if regex:
         return temp.replace('^', r'\^').replace('&', r'\&') \
                    .replace('.', r'\.').replace('$', r'\$')
-    else:
-        return temp
+    return temp
 
 
 def cyrus_unescape(user_or_folder):
@@ -359,9 +365,9 @@ def get_filename(message, failobj=None, do_unwrap=True):
     Get filename of a message part, even if it is base64-encoded.
 
     For attachments with base64-encoded file name, the
-    :py:func:`email.message.Message.get_filename()` does not work. This function
-    tries that first and if it fails tries to interprete the Content-Disposition
-    of the message part. If all fails, returns `failobj`.
+    :py:func:`email.message.Message.get_filename()` does not work. This
+    function tries that first and if it fails tries to interprete the
+    Content-Disposition of the message part. If all fails, returns `failobj`.
 
     Only for ascii filenames: also unwraps file names if they are line-wrapped.
     But note that this may remove too much whitespace from the filename if
@@ -400,7 +406,7 @@ def get_filename(message, failobj=None, do_unwrap=True):
     # '5YWs5byA6K++6K6h5YiS6KGoLnhsc3gi?='
 
     # This may be a re-implementation of email.utils.collapse_rfc2231_value()
-    # as mentioned in email.message.get_param()
+    # as mentioned in email.message.Message.get_param()
 
     # The form is: "=?charset?encoding?encoded text?="
     SPLIT_REGEX = '\r?\n *'    # should be CRNL but some files miss the \r