imapIO 0.9.5
Convenience classes and methods for processing IMAP mailboxes
License: MIT
Keywords: imap

imapIO
======
Here are some convenience classes and methods for processing IMAP mailboxes.  Since the classes are derived from the ``imaplib`` classes, all methods available in the ``imaplib`` classes are directly usable.


Installation
------------
::

    easy_install -U imapIO


Usage
-----
::

    # Connect to IMAP server
    import imapIO
    server = imapIO.connect(host, port, user, password)

    # Select folder
    import random
    emailCount = server.cd(random.choice(server.folders))

    # Walk emails in inbox sorted by arrival time
    for email in server.walk('inbox', sortCriterion='ARRIVAL'):
        # Show information
        print
        print 'Date: %s' % email.whenUTC
        print 'Subject: %s' % email.subject.encode('utf-8')
        print 'From: %s' % email.fromWhom.encode('utf-8')
        print 'From (nickname): %s' % imapIO.clean_nickname(email.fromWhom)
        print 'To: %s' % email.toWhom.encode('utf-8')
        print 'CC: %s' % email.ccWhom.encode('utf-8')
        print 'BCC: %s' % email.bccWhom.encode('utf-8')
        # Set flags
        email.seen = False
        email.deleted = False

    # Walk emails satisfying search criterion
    emailCriterion = 'BEFORE 23-JAN-2005'
    emailGenerator = server.walk(lambda folder: folder not in ['public', 'trash'], searchCriterion=emailCriterion)
    for emailIndex, email in enumerate(emailGenerator):
        # Show flags
        print
        print email.flags
        # Save email in compressed format on hard drive
        emailPath = '%s.gz' % emailIndex
        partPacks = email.save(emailPath)
        # Extract attachments from email on hard drive
        for partIndex, filename, contentType, payload in imapIO.extract(emailPath):
            print len(payload), filename.encode('utf-8')

    # Create an email in the inbox
    import datetime
    server.revive('inbox', imapIO.build_message(
        whenUTC=datetime.datetime(2005, 1, 23, 1, 0),
        subject='Subject',
        fromWhom='from@example.com',
        toWhom='to@example.com',
        ccWhom='cc@example.com',
        bccWhom='bcc@example.com',
        bodyText=u'text',
        bodyHTML=u'<html>text</html>',
        attachmentPaths=[
            'CHANGES.rst',
            'README.rst',
        ]))
    # Load email
    email = server.walk('inbox', searchCriterion='FROM from@example.com TO to@example.com').next()
    # Browse attachments in email
    partPacks = email.extract(
        include=lambda index, name, type: name.lower().endswith('.rst'),
        peek=True)
    for partIndex, filename, contentType in partPacks:
        print filename
    # Delete email
    email.deleted = True
    server.expunge()

    # Duplicate an email from one server to another
    server1 = imapIO.connect(host1, port1, user1, password1)
    server2 = imapIO.connect(host2, port2, user2, password2)
    server2.revive('inbox', server1.walk().next())


0.9.5
-----
- Added examples to _IMAPExtension.walk() docstring
- Added Email.extract() for getting attachments directly from an email message
- Cached Email.as_string()
- Changed error formatting
- Fixed bug in Email.flags() so it handles messages with no flags
- Fixed bug in extract() so that it does not try to decode non-text into unicode
- Modified extract() to filter attachments using a lambda function

0.9.4
-----
- Modified _IMAPExtension.walk() to accept a generic function to filter folders
- Modified Email.__init__() to apply _decode() to both parts of an email address
- Removed clean_tag(), parse_tags, format_tags()
- Added utf-7-imap4 codec to parse folder names
- Increased test coverage to 100%

0.9.3
-----
- Fixed revive() to handle messages that lack a date
- Modified Email so an email from _IMAPExtension.walk() can be sent to revive()
- Modified Email so we can access its parent folder
- Modified flags.setter so that it does not try to set flag "\Recent"

0.9.2
-----
- Reverted to set() for versions of Python < 2.7 that lack set literal syntax
- Removed keyword arguments from decode() to support versions of Python < 2.7
- Fixed tests for servers like Lotus Domino that do not update search indices

0.9.1
-----
- Changed _IMAPExtension.walk() to use UID directly
- Added support for sortCriterion using UID SORT
- Improved test coverage to 80%

0.9.0
-----
- Extracted code from imap-search-scout
- Made API more user-friendly
- Improved test coverage to 79%