2 files changed, 113 insertions, 1 deletions
diff --git a/src/mailman/rest/docs/users.txt b/src/mailman/rest/docs/users.txt
index 7a5b07254..c3aa4e362 100644
--- a/src/mailman/rest/docs/users.txt
+++ b/src/mailman/rest/docs/users.txt
@@ -63,7 +63,8 @@ email address for the user, and optionally the user's full name and password.
 The user exists in the database.
 ::
 
-    >>> user_manager.get_user('bart@example.com')
+    >>> bart = user_manager.get_user('bart@example.com')
+    >>> bart
     <User "Bart Person" (2) at ...>
 
 It is also available via the location given in the response.
@@ -128,3 +129,78 @@ user id...
     Traceback (most recent call last):
     ...
     HTTPError: HTTP Error 404: 404 Not Found
+
+
+User addresses
+==============
+
+Bart may have any number of email addresses associated with their user
+account.  We can find out all of these through the API.  The addresses are
+sorted in lexical order by original (i.e. case-preserved) email address.
+::
+
+    >>> bart.register('bperson@example.com')
+    <Address: bperson@example.com [not verified] at ...>
+    >>> bart.register('bart.person@example.com')
+    <Address: bart.person@example.com [not verified] at ...>
+    >>> bart.register('Bart.Q.Person@example.com')
+    <Address: Bart.Q.Person@example.com [not verified]
+              key: bart.q.person@example.com at ...>
+    >>> transaction.commit()
+
+    >>> dump_json('http://localhost:9001/3.0/users/2/addresses')
+     entry 0:
+         email: bart.q.person@example.com
+         http_etag: "..."
+         original_email: Bart.Q.Person@example.com
+         real_name:
+         registered_on: None
+         verified_on: None
+     entry 1:
+         email: bart.person@example.com
+         http_etag: "..."
+         original_email: bart.person@example.com
+         real_name:
+         registered_on: None
+         verified_on: None
+     entry 2:
+         email: bart@example.com
+         http_etag: "..."
+         original_email: bart@example.com
+         real_name: Bart Person
+         registered_on: None
+         verified_on: None
+     entry 3:
+         email: bperson@example.com
+         http_etag: "..."
+         original_email: bperson@example.com
+         real_name:
+         registered_on: None
+         verified_on: None
+     http_etag: "..."
+     start: 0
+     total_size: 4
+
+In fact, any of these addresses can be used to look up Bart's user record.
+::
+
+    >>> dump_json('http://localhost:9001/3.0/users/bart@example.com')
+    created_on: 2005-08-01T07:49:23
+    http_etag: "..."
+    password: {CLEARTEXT}bbb
+    real_name: Bart Person
+    user_id: 2
+
+    >>> dump_json('http://localhost:9001/3.0/users/bart.person@example.com')
+    created_on: 2005-08-01T07:49:23
+    http_etag: "..."
+    password: {CLEARTEXT}bbb
+    real_name: Bart Person
+    user_id: 2
+
+    >>> dump_json('http://localhost:9001/3.0/users/bperson@example.com')
+    created_on: 2005-08-01T07:49:23
+    http_etag: "..."
+    password: {CLEARTEXT}bbb
+    real_name: Bart Person
+    user_id: 2
diff --git a/src/mailman/rest/users.py b/src/mailman/rest/users.py
index 7413a8e19..54402096f 100644
--- a/src/mailman/rest/users.py
+++ b/src/mailman/rest/users.py
@@ -26,6 +26,7 @@ __all__ = [
     ]
 
 
+from operator import attrgetter
 from restish import http, resource
 from zope.component import getUtility
 
@@ -122,3 +123,38 @@ class AUser(_UserBase):
         if self._user is None:
             return http.not_found()
         return http.ok([], self._resource_as_json(self._user))
+
+    @resource.child()
+    def addresses(self, request, segments):
+        """/users/<uid>/addresses"""
+        return _AllUserAddresses(self._user)
+
+
+
+class _AllUserAddresses(resource.Resource, CollectionMixin):
+    """All addresses that a user controls."""
+
+    def __init__(self, user):
+        self._user = user
+        super(_AllUserAddresses, self).__init__()
+
+    def _resource_as_dict(self, address):
+        """See `CollectionMixin`."""
+        return dict(
+            email=address.email,
+            original_email=address.original_email,
+            real_name=address.real_name,
+            registered_on=address.registered_on,
+            verified_on=address.verified_on,
+            )
+
+    def _get_collection(self, request):
+        """See `CollectionMixin`."""
+        return sorted(self._user.addresses,
+                      key=attrgetter('original_email'))
+
+    @resource.GET()
+    def collection(self, request):
+        """/addresses"""
+        resource = self._make_collection(request)
+        return http.ok([], etag(resource))