* User and Member ids are now proper UUIDs. The UUIDs are pended as unicodes,

  and exposed to the REST API as their integer equivalents.  They are stored
  in the database using Storm's UUID type.
  - ISubscriptionService.get_member() now takes a UUID
  - IUserManager.get_user_by_id() now takes a UUID
* Moderators and owners can be added via REST (LP: #834130).  Given by
  Stephen A. Goss.
  - add_member() grows a `role` parameter.
  - ISubscriptionService.join() grows a `role` parameter.
* InvalidEmailAddressError no longer repr()'s its value.
* `address` -> `email` for consistency
  - delete_member()
  - ISubscriptionService.leave()
* Fixed typo in app/subscriptions.py __all__
* AlreadySubscribedError: attributes are now public.
* More .txt -> .rst renames.

2 files changed, 72 insertions, 20 deletions

diff --git a/src/mailman/app/docs/lifecycle.txt b/src/mailman/app/docs/lifecycle.txt
index b421d1800..4a8b732e1 100644
--- a/src/mailman/app/docs/lifecycle.txt
+++ b/src/mailman/app/docs/lifecycle.txt
@@ -27,7 +27,7 @@ bogus posting address, you get an exception.
     >>> create_list('not a valid address')
     Traceback (most recent call last):
     ...
-    InvalidEmailAddressError: u'not a valid address'
+    InvalidEmailAddressError: not a valid address
 
 If the posting address is valid, but the domain has not been registered with
 Mailman yet, you get an exception.
diff --git a/src/mailman/app/docs/subscriptions.rst b/src/mailman/app/docs/subscriptions.rst
index 8291132ce..f897d219e 100644
--- a/src/mailman/app/docs/subscriptions.rst
+++ b/src/mailman/app/docs/subscriptions.rst
@@ -17,10 +17,15 @@ membership role.  At first, there are no memberships.
     []
     >>> sum(1 for member in service)
     0
-    >>> print service.get_member(801)
+    >>> from uuid import UUID
+    >>> print service.get_member(UUID(int=801))
     None
 
-The service can be used to subscribe new members, but only with the `member`
+
+Adding new members
+==================
+
+The service can be used to subscribe new members, by default with the `member`
 role.  At a minimum, a mailing list and an address for the new user is
 required.
 
@@ -37,14 +42,13 @@ The real name of the new member can be given.
     <Member: Bart Person <bart@example.com>
              on test@example.com as MemberRole.member>
 
-Other roles can be subscribed using the more traditional interfaces.
+Other roles can also be subscribed.
 
     >>> from mailman.interfaces.member import MemberRole
-    >>> from mailman.utilities.datetime import now
-    >>> address = list(anne.user.addresses)[0]
-    >>> address.verified_on = now()
-    >>> anne.user.preferred_address = address
-    >>> anne_owner = mlist.subscribe(anne.user, MemberRole.owner)
+    >>> anne_owner = service.join('test@example.com', 'anne@example.com',
+    ...                           role=MemberRole.owner)
+    >>> anne_owner
+    <Member: anne <anne@example.com> on test@example.com as MemberRole.owner>
 
 And all the subscribed members can now be displayed.
 
@@ -56,18 +60,61 @@ And all the subscribed members can now be displayed.
               as MemberRole.member>]
     >>> sum(1 for member in service)
     3
-    >>> print service.get_member(3)
+    >>> print service.get_member(UUID(int=3))
     <Member: anne <anne@example.com> on test@example.com as MemberRole.owner>
 
+New members can also be added by providing an existing user id instead of an
+email address.  However, the user must have a preferred email address.
+::
+
+    >>> service.join('test@example.com', bart.user.user_id,
+    ...              role=MemberRole.owner)
+    Traceback (most recent call last):
+    ...
+    MissingPreferredAddressError: User must have a preferred address:
+        <User "Bart Person" (2) at ...>
+
+    >>> from mailman.utilities.datetime import now
+    >>> address = list(bart.user.addresses)[0]
+    >>> address.verified_on = now()
+    >>> bart.user.preferred_address = address
+    >>> service.join('test@example.com', bart.user.user_id,
+    ...              role=MemberRole.owner)
+    <Member: Bart Person <bart@example.com>
+             on test@example.com as MemberRole.owner>
+
+
+Removing members
+================
+
 Regular members can also be removed.
 
-    >>> service.leave('test@example.com', 'anne@example.com')
+    >>> cris = service.join('test@example.com', 'cris@example.com')
     >>> service.get_members()
-    [<Member: anne <anne@example.com> on test@example.com as MemberRole.owner>,
+    [<Member: anne <anne@example.com> on test@example.com
+              as MemberRole.owner>,
+     <Member: Bart Person <bart@example.com> on test@example.com
+              as MemberRole.owner>,
+     <Member: anne <anne@example.com> on test@example.com
+              as MemberRole.member>,
+     <Member: Bart Person <bart@example.com> on test@example.com
+              as MemberRole.member>,
+     <Member: cris <cris@example.com> on test@example.com
+              as MemberRole.member>]
+    >>> sum(1 for member in service)
+    5
+    >>> service.leave('test@example.com', 'cris@example.com')
+    >>> service.get_members()
+    [<Member: anne <anne@example.com> on test@example.com
+              as MemberRole.owner>,
+     <Member: Bart Person <bart@example.com> on test@example.com
+              as MemberRole.owner>,
+     <Member: anne <anne@example.com> on test@example.com
+              as MemberRole.member>,
      <Member: Bart Person <bart@example.com> on test@example.com
               as MemberRole.member>]
     >>> sum(1 for member in service)
-    2
+    4
 
 
 Finding members
@@ -75,17 +122,18 @@ Finding members
 
 If you know the member id for a specific member, you can get that member.
 
-    >>> service.get_member(3)
+    >>> service.get_member(UUID(int=3))
     <Member: anne <anne@example.com> on test@example.com as MemberRole.owner>
 
 If you know the member's address, you can find all their memberships, based on
-specific search criteria.
-::
+specific search criteria.  We start by subscribing Anne to a couple of new
+mailing lists.
 
     >>> mlist2 = create_list('foo@example.com')
     >>> mlist3 = create_list('bar@example.com')
-    >>> mlist.subscribe(anne.user, MemberRole.member)
-    <Member: anne <anne@example.com> on test@example.com as MemberRole.member>
+    >>> address = list(anne.user.addresses)[0]
+    >>> address.verified_on = now()
+    >>> anne.user.preferred_address = address
     >>> mlist.subscribe(anne.user, MemberRole.moderator)
     <Member: anne <anne@example.com> on test@example.com
              as MemberRole.moderator>
@@ -94,6 +142,8 @@ specific search criteria.
     >>> mlist3.subscribe(anne.user, MemberRole.owner)
     <Member: anne <anne@example.com> on bar@example.com as MemberRole.owner>
 
+And now we can find all of Anne's memberships.
+
     >>> service.find_members('anne@example.com')
     [<Member: anne <anne@example.com> on bar@example.com as MemberRole.owner>,
      <Member: anne <anne@example.com> on foo@example.com as MemberRole.member>,
@@ -111,7 +161,7 @@ There may be no matching memberships.
 
 Memberships can also be searched for by user id.
 
-    >>> service.find_members(1)
+    >>> service.find_members(UUID(int=1))
     [<Member: anne <anne@example.com> on bar@example.com as MemberRole.owner>,
      <Member: anne <anne@example.com> on foo@example.com as MemberRole.member>,
      <Member: anne <anne@example.com> on test@example.com
@@ -130,7 +180,9 @@ You can find all the memberships for a specific mailing list.
      <Member: anne <anne@example.com> on test@example.com
               as MemberRole.moderator>,
      <Member: Bart Person <bart@example.com> on test@example.com
-              as MemberRole.member>]
+              as MemberRole.member>,
+     <Member: Bart Person <bart@example.com> on test@example.com
+              as MemberRole.owner>]
 
 You can find all the memberships for an address on a specific mailing list.