Merging in several refactorings, and a REST API change.

Backward Incompatible REST API Changes:
* The JSON representation for subscription holds now no longer contains the
  `password` key.  Also, the `address` key has been renamed to `email` for
  consistency with established terminology and other usage.

Other Internal API Changes:
* IUserManager has grown a `make_user()` method.

Refactorings:
* Most uses in the test suite of add_member() have been replaced with a new
  version of the subscribe() helper.  This reduces the surface area of this
  ancient internal API.  Eventually add_member() will have to go away or
  significantly change with the subscription policy workflow.
* hold_subscription() as well as the remaining instances of add_member() now
  use a namedtuple in their arguments, to keep the signatures manageable.

2 files changed, 32 insertions, 0 deletions

diff --git a/src/mailman/interfaces/subscriptions.py b/src/mailman/interfaces/subscriptions.py
index c72a902cb..677f591ef 100644
--- a/src/mailman/interfaces/subscriptions.py
+++ b/src/mailman/interfaces/subscriptions.py
@@ -19,9 +19,12 @@
 
 __all__ = [
     'ISubscriptionService',
+    'RequestRecord',
     ]
 
 
+from collections import namedtuple
+
 from mailman.interfaces.errors import MailmanError
 from mailman.interfaces.member import DeliveryMode, MemberRole
 from zope.interface import Interface
@@ -40,6 +43,19 @@ class MissingUserError(MailmanError):
 
 
 
+_RequestRecord = namedtuple(
+    'RequestRecord',
+    'email display_name delivery_mode, language')
+def RequestRecord(email, display_name='',
+                  delivery_mode=DeliveryMode.regular,
+                  language=None):
+    if language is None:
+        from mailman.core.constants import system_preferences
+        language = system_preferences.preferred_language
+    return _RequestRecord(email, display_name, delivery_mode, language)
+
+
+
 class ISubscriptionService(Interface):
     """General Subscription services."""
 
diff --git a/src/mailman/interfaces/usermanager.py b/src/mailman/interfaces/usermanager.py
index 798d1d127..5f3a324cc 100644
--- a/src/mailman/interfaces/usermanager.py
+++ b/src/mailman/interfaces/usermanager.py
@@ -43,6 +43,22 @@ class IUserManager(Interface):
             registered.
         """
 
+    def make_user(email, display_name=None):
+        """Create a new user linked to an address object.
+
+        If ``email`` is already associated with an existing `IAddress`
+        object, use that, otherwise create a new `IAddress`.  If the
+        address object already points to an `IUser` return it.  If a new
+        `IUser` is created, link the address to the user.
+
+        :param email: The email address.
+        :type email: str
+        :param display_name: The display name.
+        :type display_name: str
+        :return: the IUser object that exists or was created.
+        :rtype: IUser
+        """
+
     def delete_user(user):
         """Delete the given user.