* Add REST interface for joining a mailing list.

* add_member() now returns the newly created IMember.
* Reorganized several exceptions and exposed them to the REST API.
* Added NoSuchListError.

6 files changed, 86 insertions, 6 deletions

diff --git a/src/mailman/interfaces/address.py b/src/mailman/interfaces/address.py
index 968ded3ee..4b82c13db 100644
--- a/src/mailman/interfaces/address.py
+++ b/src/mailman/interfaces/address.py
@@ -26,10 +26,13 @@ __all__ = [
     'AddressNotLinkedError',
     'ExistingAddressError',
     'IAddress',
+    'InvalidEmailAddressError',
     ]
 
 
+from lazr.restful.declarations import error_status
 from zope.interface import Interface, Attribute
+
 from mailman.interfaces.errors import MailmanError
 
 
@@ -50,6 +53,10 @@ class AddressNotLinkedError(AddressError):
     """The address is not linked to the user."""
 
 
+@error_status(400)
+class InvalidEmailAddressError(AddressError):
+    """Email address is invalid."""
+
 
 
 class IAddress(Interface):
diff --git a/src/mailman/interfaces/listmanager.py b/src/mailman/interfaces/listmanager.py
index 8a058eaa5..b707df7e7 100644
--- a/src/mailman/interfaces/listmanager.py
+++ b/src/mailman/interfaces/listmanager.py
@@ -23,6 +23,7 @@ __metaclass__ = type
 __all__ = [
     'IListManager',
     'ListAlreadyExistsError',
+    'NoSuchListError',
     ]
 
 
@@ -45,6 +46,18 @@ class ListAlreadyExistsError(MailmanError):
     """
 
 
+@error_status(400)
+class NoSuchListError(MailmanError):
+    """Attempt to access a mailing list that does not exist."""
+
+    def __init__(self, fqdn_listname):
+        self.fqdn_listname = fqdn_listname
+
+    def __str__(self):
+        return 'No such mailing list: {0.fqdn_listname}'.format(self)
+
+
+
 
 class IListManager(Interface):
     """The interface of the global list manager.
diff --git a/src/mailman/interfaces/member.py b/src/mailman/interfaces/member.py
index e5a82060a..87ad19c83 100644
--- a/src/mailman/interfaces/member.py
+++ b/src/mailman/interfaces/member.py
@@ -26,15 +26,17 @@ __all__ = [
     'DeliveryStatus',
     'IMember',
     'MemberRole',
+    'MembershipError',
+    'MembershipIsBannedError',
     ]
 
 
 from lazr.restful.declarations import (
-    export_as_webservice_entry, exported)
+    error_status, export_as_webservice_entry, exported)
 from munepy import Enum
 from zope.interface import Interface, Attribute
 
-from mailman.core.errors import SubscriptionError
+from mailman.core.errors import MailmanError
 
 
 
@@ -71,7 +73,11 @@ class MemberRole(Enum):
 
 
 
-class AlreadySubscribedError(SubscriptionError):
+class MembershipError(MailmanError):
+    """Base exception for all membership errors."""
+
+
+class AlreadySubscribedError(MembershipError):
     """The member is already subscribed to the mailing list with this role."""
 
     def __init__(self, fqdn_listname, address, role):
@@ -85,6 +91,20 @@ class AlreadySubscribedError(SubscriptionError):
             self._address, self._role, self._fqdn_listname)
 
 
+@error_status(400)
+class MembershipIsBannedError(MembershipError):
+    """The address is not allowed to subscribe to the mailing list."""
+
+    def __init__(self, mlist, address):
+        super(MembershipIsBanned, self).__init__()
+        self._mlist = mlist
+        self._address = address
+
+    def __str__(self):
+        return '{0} is not allowed to subscribe to {1.fqdn_listname}'.format(
+            self._address, self._mlist)
+
+
 
 class IMember(Interface):
     """A member of a mailing list."""
diff --git a/src/mailman/interfaces/membership.py b/src/mailman/interfaces/membership.py
index 0a04ff630..51e36c6e5 100644
--- a/src/mailman/interfaces/membership.py
+++ b/src/mailman/interfaces/membership.py
@@ -27,8 +27,9 @@ __all__ = [
 
 from lazr.restful.declarations import (
     collection_default_content, export_as_webservice_collection,
-    export_factory_operation)
+    export_write_operation, operation_parameters)
 from zope.interface import Interface
+from zope.schema import TextLine
 
 from mailman.core.i18n import _
 from mailman.interfaces.member import IMember
@@ -53,3 +54,42 @@ class ISubscriptionService(Interface):
         :return: The list of all members.
         :rtype: list of `IMember`
         """
+
+    @operation_parameters(
+        fqdn_listname=TextLine(),
+        address=TextLine(),
+        real_name=TextLine(),
+        delivery_mode=TextLine(),
+        )
+    @export_write_operation()
+    def join(fqdn_listname, address, real_name=None, delivery_mode=None):
+        """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 fqdn_listname: The posting address of the mailing list to
+            subscribe the user to.
+        :type fqdn_listname: string
+        :param address: The address of the user getting subscribed.
+        :type address: string
+        :param real_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 real_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
+        :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 NoSuchListError: if the named mailing list does not exist.
+        :raises ValueError: when `delivery_mode` is invalid.
+        """
diff --git a/src/mailman/interfaces/registrar.py b/src/mailman/interfaces/registrar.py
index dae4d53a8..d7eac1072 100644
--- a/src/mailman/interfaces/registrar.py
+++ b/src/mailman/interfaces/registrar.py
@@ -61,7 +61,7 @@ class IRegistrar(Interface):
         :type real_name: str
         :return: The confirmation token string.
         :rtype: str
-        :raises InvalidEmailAddress: if the address is not allowed.
+        :raises InvalidEmailAddressError: if the address is not allowed.
         """
 
     def confirm(token):
diff --git a/src/mailman/interfaces/user.py b/src/mailman/interfaces/user.py
index 5c3ff58cd..2892b44d2 100644
--- a/src/mailman/interfaces/user.py
+++ b/src/mailman/interfaces/user.py
@@ -42,7 +42,7 @@ class IUser(Interface):
         """An iterator over all the IAddresses controlled by this user.""")
 
     memberships = Attribute(
-        """A roster of this user's membership.""")
+        """A roster of this user's memberships.""")
 
     def register(address, real_name=None):
         """Register the given email address and link it to this user.