=============
IMAP accounts
=============

The `Account` class is an object-oriented representation of an IMAP account on
a server.

An account requires information about the server on which it is located and
the user credentials to allow logging in:

>>> from gocept.imapapi.account import Account
>>> account = Account('localhost', 10143, 'test', 'bsdf')

Note that the account object provides the IAccount interface:

>>> from gocept.imapapi.interfaces import IAccount
>>> IAccount.providedBy(account)
True
>>> account.host
'localhost'
>>> account.port
10143
>>> account.user
'test'
>>> account.password
'bsdf'
>>> account.ssl
False


Retrieving folder structure
===========================

An account contains folders, but does not contain messages by itself:

>>> from pprint import pprint
>>> pprint(dict(account.folders))
{u'Bar': <gocept.imapapi.folder.Folder object u'Bar' at 0x2615309>,
 u'F\xf6': <gocept.imapapi.folder.Folder object u'F\xf6' at 0x2623456>,
 u'INBOX': <gocept.imapapi.folder.Folder object u'INBOX' at 0x2631278>}

>>> account.messages
Traceback (most recent call last):
AttributeError: 'Account' object has no attribute 'messages'

Individual folders can be retrieved by specifying their name:

>>> account.folders[u'INBOX']
<gocept.imapapi.folder.Folder object u'INBOX' at 0x2176287>

>>> account.folders[u'nofolder']
Traceback (most recent call last):
KeyError: u'nofolder'


Failing logins
==============

If an unknown host is given, the account object will not be created:

>>> account = Account('foo', 143, 'test', 'foo')
Traceback (most recent call last):
IMAPServerError: (..., '...')

If the connection can not be established, the account object will not be
created, too:

>>> account = Account('localhost', 10143, 'test', 'foo')
Traceback (most recent call last):
IMAPConnectionError: Authentication failed.

>>> account = Account('localhost', 10144, 'test', 'bsdf')
Traceback (most recent call last):
IMAPServerError: (..., 'Connection refused')
