1 files changed, 124 insertions, 0 deletions
diff --git a/src/mailman/docs/usermanager.txt b/src/mailman/docs/usermanager.txt
new file mode 100644
index 000000000..f8cbfeef2
--- /dev/null
+++ b/src/mailman/docs/usermanager.txt
@@ -0,0 +1,124 @@
+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.interfaces.usermanager 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.user 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