The user manager
================

The IUserManager is how you create, delete, and manage users.  The Mailman
system instantiates an IUserManager for you based on the configuration
variable MANAGERS_INIT_FUNCTION.  The instance is accessible on the global
config object.

    >>> from mailman.configuration import config
    >>> from mailman.interfaces import IUserManager
    >>> from zope.interface.verify import verifyObject
    >>> usermgr = config.db.user_manager
    >>> verifyObject(IUserManager, usermgr)
    True


Creating users
--------------

There are several ways you can create a user object.  The simplest is to
create a 'blank' user by not providing an address or real name at creation
time.  This user will have an empty string as their real name, but will not
have a password.

    >>> from mailman.interfaces import IUser
    >>> user = usermgr.create_user()
    >>> verifyObject(IUser, user)
    True
    >>> sorted(address.address for address in user.addresses)
    []
    >>> user.real_name
    u''
    >>> print user.password
    None

The user has preferences, but none of them will be specified.

    >>> print user.preferences
    <Preferences ...>

A user can be assigned a real name.

    >>> user.real_name = u'Anne Person'
    >>> sorted(user.real_name for user in usermgr.users)
    [u'Anne Person']

A user can be assigned a password.

    >>> user.password = u'secret'
    >>> sorted(user.password for user in usermgr.users)
    [u'secret']

You can also create a user with an address to start out with.

    >>> user_2 = usermgr.create_user(u'bperson@example.com')
    >>> verifyObject(IUser, user_2)
    True
    >>> sorted(address.address for address in user_2.addresses)
    [u'bperson@example.com']
    >>> sorted(user.real_name for user in usermgr.users)
    [u'', u'Anne Person']

As above, you can assign a real name to such users.

    >>> user_2.real_name = u'Ben Person'
    >>> sorted(user.real_name for user in usermgr.users)
    [u'Anne Person', u'Ben Person']

You can also create a user with just a real name.

    >>> user_3 = usermgr.create_user(real_name=u'Claire Person')
    >>> verifyObject(IUser, user_3)
    True
    >>> sorted(address.address for address in user.addresses)
    []
    >>> sorted(user.real_name for user in usermgr.users)
    [u'Anne Person', u'Ben Person', u'Claire Person']

Finally, you can create a user with both an address and a real name.

    >>> user_4 = usermgr.create_user(u'dperson@example.com', u'Dan Person')
    >>> verifyObject(IUser, user_3)
    True
    >>> sorted(address.address for address in user_4.addresses)
    [u'dperson@example.com']
    >>> sorted(address.real_name for address in user_4.addresses)
    [u'Dan Person']
    >>> sorted(user.real_name for user in usermgr.users)
    [u'Anne Person', u'Ben Person', u'Claire Person', u'Dan Person']


Deleting users
--------------

You delete users by going through the user manager.  The deleted user is no
longer available through the user manager iterator.

    >>> usermgr.delete_user(user)
    >>> sorted(user.real_name for user in usermgr.users)
    [u'Ben Person', u'Claire Person', u'Dan Person']


Finding users
-------------

You can ask the user manager to find the IUser that controls a particular
email address.  You'll get back the original user object if it's found.  Note
that the .get_user() method takes a string email address, not an IAddress
object.

    >>> address = list(user_4.addresses)[0]
    >>> found_user = usermgr.get_user(address.address)
    >>> found_user
    <User "Dan Person" at ...>
    >>> found_user is user_4
    True

If the address is not in the user database or does not have a user associated
with it, you will get None back.

    >>> print usermgr.get_user(u'zperson@example.com')
    None
    >>> user_4.unlink(address)
    >>> print usermgr.get_user(address.address)
    None
