Repair the usermanager.txt and listmanager.txt doc tests. These repairs were

necessary to deal with the simplified user model.  Eradicate more references
to rosters and roster sets.

Give Users a repr.  Also give them a belongs_to() link to Preferences, but
change the user manager to not give a user preferences by default (the lookup
schema should properly handle users with no preferences now).

Also, when creating a user, set their real_name to the empty string if no
real_name argument was given to create_user().  Update the IUserManager
interface's create_user() method to match the implementation.

2 files changed, 103 insertions, 67 deletions

diff --git a/Mailman/docs/listmanager.txt b/Mailman/docs/listmanager.txt
index 9e237f02f..03943a237 100644
--- a/Mailman/docs/listmanager.txt
+++ b/Mailman/docs/listmanager.txt
@@ -54,17 +54,12 @@ you will get an exception.
 Deleting a mailing list
 -----------------------
 
-Deleting an existing mailing list also deletes its rosters and roster sets.
-
-    >>> sorted(r.name for r in config.user_manager.rosters)
-    ['', '_xtest@example.com moderators', '_xtest@example.com owners']
+Use the list manager to delete a mailing list.
 
     >>> mgr.delete(mlist)
     >>> flush()
     >>> sorted(mgr.names)
     []
-    >>> sorted(r.name for r in config.user_manager.rosters)
-    ['']
 
 Attempting to access attributes of the deleted mailing list raises an
 exception:
diff --git a/Mailman/docs/usermanager.txt b/Mailman/docs/usermanager.txt
index f79bff8c6..389c68956 100644
--- a/Mailman/docs/usermanager.txt
+++ b/Mailman/docs/usermanager.txt
@@ -1,100 +1,141 @@
-The user manager and rosters
-============================
+The user manager
+================
 
-The IUserManager is how you create, delete, and roster objects.  Rosters
-manage collections of 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.
+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.database import flush
     >>> from Mailman.interfaces import IUserManager
     >>> mgr = config.user_manager
     >>> IUserManager.providedBy(mgr)
     True
 
 
-The default roster
-------------------
+Creating users
+--------------
 
-The user manager always contains at least one roster, the 'null' roster or
-'all inclusive roster'.
+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 or preferences.
 
-    >>> sorted(roster.name for roster in mgr.rosters)
-    ['']
+    >>> from Mailman.interfaces import IUser
+    >>> user = mgr.create_user()
+    >>> flush()
+    >>> IUser.providedBy(user)
+    True
+    >>> sorted(address.address for address in user.addresses)
+    []
+    >>> user.real_name
+    ''
+    >>> print user.preferences
+    None
+    >>> print user.password
+    None
 
+A user can be assigned a real name.
 
-Adding rosters
---------------
+    >>> user.real_name = 'Anne Person'
+    >>> flush()
+    >>> sorted(user.real_name for user in mgr.users)
+    ['Anne Person']
 
-You create a roster to hold users.  The only thing a roster needs is a name,
-basically just an identifying string.
+A user can be assigned a password.
 
-    >>> from Mailman.database import flush
-    >>> from Mailman.interfaces import IRoster
-    >>> roster = mgr.create_roster('roster-1')
-    >>> IRoster.providedBy(roster)
-    True
-    >>> roster.name
-    'roster-1'
+    >>> user.password = 'secret'
     >>> flush()
+    >>> sorted(user.password for user in mgr.users)
+    ['secret']
 
-If you try to create a roster with the same name as an existing roster, you
-will get an exception.
+You can also create a user with an address to start out with.
 
-    >>> roster_dup = mgr.create_roster('roster-1')
-    Traceback (most recent call last):
-    ...
-    RosterExistsError: roster-1
+    >>> user_2 = mgr.create_user('bperson@example.com')
+    >>> flush()
+    >>> IUser.providedBy(user_2)
+    True
+    >>> sorted(address.address for address in user_2.addresses)
+    ['bperson@example.com']
+    >>> sorted(user.real_name for user in mgr.users)
+    ['', 'Anne Person']
 
+As above, you can assign a real name to such users.
 
-Deleting a roster
------------------
+    >>> user_2.real_name = 'Ben Person'
+    >>> flush()
+    >>> sorted(user.real_name for user in mgr.users)
+    ['Anne Person', 'Ben Person']
 
-Delete the roster, and you can then create it again.
+You can also create a user with just a real name.
 
-    >>> mgr.delete_roster(roster)
+    >>> user_3 = mgr.create_user(real_name='Claire Person')
     >>> flush()
-    >>> roster = mgr.create_roster('roster-1')
+    >>> IUser.providedBy(user_3)
+    True
+    >>> sorted(address.address for address in user.addresses)
+    []
+    >>> sorted(user.real_name for user in mgr.users)
+    ['Anne Person', 'Ben Person', 'Claire Person']
+
+Finally, you can create a user with both an address and a real name.
+
+    >>> user_4 = mgr.create_user('dperson@example.com', 'Dan Person')
     >>> flush()
-    >>> roster.name
-    'roster-1'
+    >>> IUser.providedBy(user_3)
+    True
+    >>> sorted(address.address for address in user_4.addresses)
+    ['dperson@example.com']
+    >>> sorted(address.real_name for address in user_4.addresses)
+    ['Dan Person']
+    >>> sorted(user.real_name for user in mgr.users)
+    ['Anne Person', 'Ben Person', 'Claire Person', 'Dan Person']
 
 
-Retrieving a roster
--------------------
+Deleting users
+--------------
 
-When a roster exists, you can ask the user manager for it and you will always
-get the same object back.
+You delete users by going through the user manager.  The deleted user is no
+longer available through the user manager iterator.
 
-    >>> roster_2 = mgr.get_roster('roster-1')
-    >>> roster_2.name
-    'roster-1'
-    >>> roster is roster_2
-    True
+    >>> mgr.delete_user(user)
+    >>> flush()
+    >>> sorted(user.real_name for user in mgr.users)
+    ['Ben Person', 'Claire Person', 'Dan Person']
 
-Trying to get a roster that does not yet exist returns None.
 
-    >>> print mgr.get_roster('no roster')
-    None
+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.
 
-Iterating over all the rosters
-------------------------------
+    >>> address = list(user_4.addresses)[0]
+    >>> found_user = mgr.get_user(address.address)
+    >>> found_user
+    <User "Dan Person" at ...>
+    >>> found_user is user_4
+    True
 
-Once you've created a bunch of rosters, you can use the user manager to
-iterate over all the rosters.
+If the address is not in the user database or does not have a user associated
+with it, you will get None back.
 
-    >>> roster_2 = mgr.create_roster('roster-2')
-    >>> roster_3 = mgr.create_roster('roster-3')
-    >>> roster_4 = mgr.create_roster('roster-4')
+    >>> print mgr.get_user('zperson@example.com')
+    None
+    >>> user_4.unlink(address)
     >>> flush()
-    >>> sorted(roster.name for roster in mgr.rosters)
-    ['', 'roster-1', 'roster-2', 'roster-3', 'roster-4']
+    >>> print mgr.get_user(address.address)
+    None
 
 
-Cleaning up
------------
+Clean up
+--------
 
-    >>> for roster in mgr.rosters:
-    ...     mgr.delete_roster(roster)
+    >>> for user in mgr.users:
+    ...     mgr.delete_user(user)
     >>> flush()
+    >>> list(mgr.users)
+    []