============
IMAP folders
============

Accessing IMAP folders
======================

IMAP accounts provide access to the folder structure by exposing a list of
top-level folders:

>>> from gocept.imapapi.account import Account
>>> from pprint import pprint
>>> account = Account('localhost', 10143, 'test', 'bsdf')
>>> pprint(account.folders)
{'Bar': <gocept.imapapi.folder.Folder object 'Bar' at 0x...>,
 'INBOX': <gocept.imapapi.folder.Folder object 'INBOX' at 0x...>}

A folder knows about its name, path, separator, and depth in the hierarchy:

>>> INBOX = account.folders['INBOX']
>>> INBOX.name
'INBOX'
>>> INBOX.path
'INBOX'
>>> INBOX.separator
'/'
>>> INBOX.depth
1

Folders also provide access to their direct sub-folders:

>>> INBOX.folders
{'Baz': <gocept.imapapi.folder.Folder object 'INBOX/Baz' at 0x...>}

Here's a folder that's a bit deeper in the hierarchy:

>>> baz = INBOX.folders['Baz']
>>> baz.name
'Baz'
>>> baz.path
'INBOX/Baz'
>>> baz.separator
'/'
>>> baz.depth
2

Creating folders
================

Folders may be created as top-level folders of an account or within existing
folders.

>>> from gocept.imapapi.folder import Folder
>>> account.folders['Top level'] = Folder()
>>> pprint(dict(account.folders))
{'Bar': <gocept.imapapi.folder.Folder object 'Bar' at 0x...>,
 'INBOX': <gocept.imapapi.folder.Folder object 'INBOX' at 0x...>,
 'Top level': <gocept.imapapi.folder.Folder object 'Top level' at 0x...>}
>>> top_level = account.folders['Top level']
>>> top_level.name
'Top level'
>>> top_level.path
'Top level'

>>> top_level.folders['Subfolder'] = subfolder = Folder()
>>> top_level.folders
{'Subfolder': <gocept.imapapi.folder.Folder object 'Top level/Subfolder' at 0x...>}
>>> subfolder.name
'Subfolder'
>>> subfolder.path
'Top level/Subfolder'


Accessing messages
==================

Messages can be retrieved from a folder using its `messages` attribute:

>>> pprint(dict(INBOX.messages))
{'...-...': <gocept.imapapi.message.Message object 'INBOX/...-...' at 0x...>,
 '...-...': <gocept.imapapi.message.Message object 'INBOX/...-...' at 0x...>}

Individual messages have a name attribute which can be used to uniquely
identify a message within a folder. We can use it to retrieve an individual
message:

>>> mail1 = INBOX.messages.values()[0]
>>> mail1.headers['X-IMAPAPI-Test']
u'1'
>>> INBOX.messages[mail1.name].headers['X-IMAPAPI-Test']
u'1'
