merge trunk and fix merge conflicts

3 files changed, 35 insertions, 49 deletions

diff --git a/src/mailman/interfaces/pending.py b/src/mailman/interfaces/pending.py
index 222f0dfbf..c921123de 100644
--- a/src/mailman/interfaces/pending.py
+++ b/src/mailman/interfaces/pending.py
@@ -95,4 +95,10 @@ class IPendings(Interface):
     def evict():
         """Remove all pended items whose lifetime has expired."""
 
+    def __iter__():
+        """An iterator over all pendables.
+
+        Each element is a 2-tuple of the form (token, dict).
+        """
+
     count = Attribute('The number of pendables in the pendings database.')
diff --git a/src/mailman/interfaces/registrar.py b/src/mailman/interfaces/registrar.py
index ff3f26898..959e0bf6a 100644
--- a/src/mailman/interfaces/registrar.py
+++ b/src/mailman/interfaces/registrar.py
@@ -52,9 +52,11 @@ class IRegistrar(Interface):
     This is a higher level interface to user registration, email address
     confirmation, etc. than the IUserManager.  The latter does no validation,
     syntax checking, or confirmation, while this interface does.
+
+    To use this, adapt an ``IMailingList`` to this interface.
     """
 
-    def register(mlist, subscriber=None, *,
+    def register(subscriber=None, *,
                  pre_verified=False, pre_confirmed=False, pre_approved=False):
         """Subscribe an address or user according to subscription policies.
 
@@ -71,13 +73,15 @@ class IRegistrar(Interface):
         approve the subscription.  Use the ``confirm(token)`` method to
         resume the workflow.
 
-        :param mlist: The mailing list to subscribe to.
-        :type mlist: `IMailingList`
         :param subscriber: The user or address to subscribe.
         :type email: ``IUser`` or ``IAddress``
-        :return: The confirmation token string, or None if the workflow
-            completes (i.e. the member has been subscribed).
-        :rtype: str or None
+        :return: A 3-tuple is returned where the first element is the token
+            hash, the second element is a ``TokenOwner`, and the third element
+            is the subscribed member.  If the subscriber got subscribed
+            immediately, the token will be None and the member will be
+            an ``IMember``.  If the subscription got held, the token
+            will be a hash and the member will be None.
+        :rtype: (str-or-None, ``TokenOwner``, ``IMember``-or-None)
         :raises MembershipIsBannedError: when the address being subscribed
             appears in the global or list-centric bans.
         """
@@ -91,9 +95,13 @@ class IRegistrar(Interface):
 
         :param token: A token matching a workflow.
         :type token: string
-        :return: The new token for any follow up confirmation, or None if the
-            user was subscribed.
-        :rtype: str or None
+        :return: A 3-tuple is returned where the first element is the token
+            hash, the second element is a ``TokenOwner`, and the third element
+            is the subscribed member.  If the subscriber got subscribed
+            immediately, the token will be None and the member will be
+            an ``IMember``.  If the subscription is still being held, the token
+            will be a hash and the member will be None.
+        :rtype: (str-or-None, ``TokenOwner``, ``IMember``-or-None)
         :raises LookupError: when no workflow is associated with the token.
         """
 
diff --git a/src/mailman/interfaces/subscriptions.py b/src/mailman/interfaces/subscriptions.py
index 677f591ef..e6ffd29ce 100644
--- a/src/mailman/interfaces/subscriptions.py
+++ b/src/mailman/interfaces/subscriptions.py
@@ -19,14 +19,16 @@
 
 __all__ = [
     'ISubscriptionService',
+    'MissingUserError',
     'RequestRecord',
+    'TokenOwner',
     ]
 
 
 from collections import namedtuple
-
+from enum import Enum
 from mailman.interfaces.errors import MailmanError
-from mailman.interfaces.member import DeliveryMode, MemberRole
+from mailman.interfaces.member import DeliveryMode
 from zope.interface import Interface
 
 
@@ -56,6 +58,14 @@ def RequestRecord(email, display_name='',
 
 
 
+class TokenOwner(Enum):
+    """Who 'owns' the token returned from the registrar?"""
+    no_one = 0
+    subscriber = 1
+    moderator = 2
+
+
+
 class ISubscriptionService(Interface):
     """General Subscription services."""
 
@@ -104,44 +114,6 @@ class ISubscriptionService(Interface):
     def __iter__():
         """See `get_members()`."""
 
-    def join(list_id, subscriber, display_name=None,
-             delivery_mode=DeliveryMode.regular,
-             role=MemberRole.member):
-        """Subscribe to a mailing list.
-
-        A user for the address is created if it is not yet known to Mailman,
-        however newly registered addresses will not yet be validated.  No
-        confirmation message will be sent to the address, and the approval of
-        the subscription request is still dependent on the policy of the
-        mailing list.
-
-        :param list_id: The list id of the mailing list the user is
-            subscribing to.
-        :type list_id: string
-        :param subscriber: The email address or user id of the user getting
-            subscribed.
-        :type subscriber: string or int
-        :param display_name: The name of the user.  This is only used if a new
-            user is created, and it defaults to the local part of the email
-            address if not given.
-        :type display_name: string
-        :param delivery_mode: The delivery mode for this subscription.  This
-            can be one of the enum values of `DeliveryMode`.  If not given,
-            regular delivery is assumed.
-        :type delivery_mode: string
-        :param role: The membership role for this subscription.
-        :type role: `MemberRole`
-        :return: The just created member.
-        :rtype: `IMember`
-        :raises AlreadySubscribedError: if the user is already subscribed to
-            the mailing list.
-        :raises InvalidEmailAddressError: if the email address is not valid.
-        :raises MembershipIsBannedError: if the membership is not allowed.
-        :raises MissingUserError: when a bogus user id is given.
-        :raises NoSuchListError: if the named mailing list does not exist.
-        :raises ValueError: when `delivery_mode` is invalid.
-        """
-
     def leave(list_id, email):
         """Unsubscribe from a mailing list.