[IMP] make fetch_mail's refactoring more useful by returning the ids of

mails creates/objects matched
[ADD] preliminary docstrings

fetchmail_attach_from_folder/match_algorithm/openerp_standard.py

@@ -48,4 +48,4 @@ class openerp_standard(base):
         if folder.delete_matching:
             connection.store(msgid, '+FLAGS', '\\DELETED')
 
-        return result
+        return [result]

fetchmail_attach_from_folder/model/fetchmail_server.py

@@ -83,6 +83,10 @@ class fetchmail_server(Model):
             cr, uid, check_original, context)
 
     def handle_folder(self, cr, uid, ids, connection, folder, context=None):
+        '''Return ids of objects matched'''
+
+        matched_object_ids = []
+
         for this in self.browse(cr, uid, ids, context=context):
             logger.info('start checking for emails in %s server %s',
                         folder.path, this.name)
@@ -103,16 +107,23 @@ class fetchmail_server(Model):
                 continue
 
             for msgid in msgids[0].split():
-                this.apply_matching(connection, folder, msgid, match_algorithm)
+                matched_object_ids += this.apply_matching(
+                        connection, folder, msgid, match_algorithm)
 
             logger.info('finished checking for emails in %s server %s',
                         folder.path, this.name)
 
+        return matched_object_ids
+
     def get_msgids(self, cr, uid, ids, connection, context=None):
+        '''Return imap ids of messages to process'''
         return connection.search(None, 'UNDELETED')
 
     def apply_matching(self, cr, uid, ids, connection, folder, msgid,
                        match_algorithm, context=None):
+        '''Return ids of objects matched'''
+
+        matched_object_ids = []
 
         for this in self.browse(cr, uid, ids, context=context):
             result, msgdata = connection.fetch(msgid, '(RFC822)')
@@ -142,6 +153,7 @@ class fetchmail_server(Model):
                         found_ids[0], folder, mail_message,
                         msgdata[0][1], msgid, context)
                     cr.commit()
+                    matched_object_ids += found_ids[:1]
                 except Exception, e:
                     cr.rollback()
                     logger.exception(
@@ -150,9 +162,15 @@ class fetchmail_server(Model):
             elif folder.flag_nonmatching:
                 connection.store(msgid, '+FLAGS', '\\FLAGGED')
 
+        return matched_object_ids
+
     def attach_mail(
             self, cr, uid, ids, connection, object_id, folder,
             mail_message, msgid, context=None):
+        '''Return ids of messages created'''
+
+        mail_message_ids = []
+
         for this in self.browse(cr, uid, ids, context):
             partner_id = None
             if folder.model_id.model == 'res.partner':
@@ -181,6 +199,7 @@ class fetchmail_server(Model):
                         self.pool.get('ir.attachment').create(
                             cr, uid, data_attach, context=context))
 
+            mail_message_ids.append(
                     self.pool.get('mail.message').create(
                         cr, uid,
                         {
@@ -201,10 +220,11 @@ class fetchmail_server(Model):
                             'state': folder.msg_state,
                             'attachment_ids': [(6, 0, attachments)],
                         },
-                context)
+                        context))
 
             if folder.delete_matching:
                 connection.store(msgid, '+FLAGS', '\\DELETED')
+        return mail_message_ids
 
     def button_confirm_login(self, cr, uid, ids, context=None):
         retval = super(fetchmail_server, self).button_confirm_login(cr, uid,