===================
Mailman REST Client
===================

    >>> from pprint import pprint

    # The test framework starts out with an example domain, so let's delete
    # that first.
    >>> from mailman.interfaces.domain import IDomainManager
    >>> from zope.component import getUtility
    >>> domain_manager = getUtility(IDomainManager)

    >>> domain_manager.remove('example.com')
    <Domain example.com...>
    >>> transaction.commit()

First let's get an instance of MailmanRESTClient.

    >>> from mailmanclient.rest import MailmanRESTClient, MailmanRESTClientError
    >>> client = MailmanRESTClient('localhost:8001')

So far there are no lists.

    >>> client.get_lists()
    []


Domains
=======

In order to add new lists first a new domain has to be added.

    >>> new_domain = client.create_domain('example.com')
    >>> pprint(new_domain.info)
    {u'base_url': u'http://example.com',
     u'contact_address': u'postmaster@example.com',
     u'description': None,
     u'email_host': u'example.com',
     u'http_etag': u'"6b1ccf042e8f76138a0bd37e8509f364da92a5c5"',
     u'self_link': u'http://localhost:8001/3.0/domains/example.com',
     u'url_host': u'example.com'}

Later the domain object can be instantiated using get_domain()

    >>> my_domain = client.get_domain('example.com')


Mailing lists
=============

Now let's add a mailing list called 'test-one'.

    >>> new_list = my_domain.create_list('test-one')

Let's add another list and get some information on the list.

    >>> another_list = my_domain.create_list('test-two')
    >>> pprint(another_list.info)
    {'advertised': True,
    ...
     'welcome_msg': 'Welcome message lorem ipsum dolor sit'}

Later the new list can be instantiated using get_list():

    >>> some_list = client.get_list('test-one@example.com')

The lists have been added and get_lists() returns a list of dicts, sorted
by fqdn_listname.

    >>> pprint(client.get_lists())
    [{u'fqdn_listname': u'test-one@example.com',
      u'host_name': u'example.com',
      u'http_etag': u'"5e99519ef1b823a52254b77e89bec54fbd17bef0"',
      u'list_name': u'test-one',
      u'real_name': u'Test-one',
      u'self_link': u'http://localhost:8001/3.0/lists/test-one@example.com'},
     {u'fqdn_listname': u'test-two@example.com',
      u'host_name': u'example.com',
      u'http_etag': u'"a05542c9faa07cbe2b8fdf8a1655a2361ab365f2"',
      u'list_name': u'test-two',
      u'real_name': u'Test-two',
      u'self_link': u'http://localhost:8001/3.0/lists/test-two@example.com'}]


Membership
==========

Since we now have a list we should add some members to it (.subscribe()
returns an HTTP status code, ideally 201)

    >>> new_list.subscribe('jack@example.com', 'Jack')
    201
    >>> new_list.subscribe('meg@example.com', 'Meg')
    201
    >>> another_list.subscribe('jack@example.com', 'Jack')
    201

We can get a list of all members:

    >>> pprint(client.get_members())
    [{u'http_etag': u'"320f9e380322cafbbf531c11eab1ec9d38b3bb99"',
      u'self_link': u'http://localhost:8001/3.0/lists/test-one@example.com/member/jack@example.com'},
     {u'http_etag': u'"cd75b7e93216a022573534d948511edfbfea06cd"',
      u'self_link': u'http://localhost:8001/3.0/lists/test-one@example.com/member/meg@example.com'},
     {u'http_etag': u'"13399f5ebbab8c474926a7ad0ccfda28d717e398"',
      u'self_link': u'http://localhost:8001/3.0/lists/test-two@example.com/member/jack@example.com'}]

Or just the members of a specific list:

    >>> pprint(new_list.get_members())
    [{u'http_etag': u'"320f9e380322cafbbf531c11eab1ec9d38b3bb99"',
      u'self_link': u'http://localhost:8001/3.0/lists/test-one@example.com/member/jack@example.com'},
     {u'http_etag': u'"cd75b7e93216a022573534d948511edfbfea06cd"',
      u'self_link': u'http://localhost:8001/3.0/lists/test-one@example.com/member/meg@example.com'}]

After a while Meg decides to unsubscribe from the mailing list (like
.subscribe() .unsubscribe() returns an HTTP status code, ideally 200).

    >>> new_list.unsubscribe('meg@example.com')
    200


Users
=====

Users and their settings can be accessed by using one of their email
addresses.

    >>> jack = client.get_user('jack@example.com')
    >>> print jack
    A user object for the user 'Jack'.
    >>> pprint(jack.info)
    {u'real_name': u'Jack'}

To update the User settings, change the info attribute and call update().

    >>> jack.info['real_name'] = 'Jack, Brother of Meg'
    >>> jack.update()
    204

You can get a list of all lists a user has subscribed and/or is an owner
or moderator of by using .get_lists().

    >>> pprint(jack.get_lists())
    [{u'email_address': u'jack@example.com',
      u'fqdn_listname': u'test-one@example.com',
      u'real_name': u'Test-one'},
     {u'email_address': u'jack@example.com',
      u'fqdn_listname': u'test-two@example.com',
      u'real_name': u'Test-two'}]

To see which email addresses jack has used to subscribe to the lists on
that domain, use get_email_addresses().

    >>> pprint(jack.get_email_addresses())
    [u'jack@example.com']


Membership
==========

To know more about the membership details of Jack's subscription, you
need an instance of a member. There are two ways to get a member object:
Either get it from the client object...

    >>> member = client.get_member('jack@example.com', 'test-one@example.com')

...or from a list object, providing only an email address as a parameter:

    >>> member = new_list.get_member('jack@example.com')
    >>> print member
    A member object for 'jack@example.com', subscribed to 'test-one@example.com'.
    >>> member_info = member.info
    >>> pprint(member_info)
    {'_original': 'Original lorem ipsum dolor sit',
     'acknowledge_posts': True,
     'address': 'Address lorem ipsum dolor sit',
     'address_id': 9,
     'delivery_mode': 'Delivery mode lorem ipsum dolor sit',
     'delivery_status': 'Delivery status lorem ipsum dolor sit',
     'hide_address': True,
     'id': 9,
     'is_moderated': True,
     'mailing_list': 'Mailing list lorem ipsum dolor sit',
     'password': 'Password lorem ipsum dolor sit',
     'preferences_id': 9,
     'preferred_language': 'Preferred language lorem ipsum dolor sit',
     'real_name': 'Real name lorem ipsum dolor sit',
     'receive_list_copy': True,
     'receive_own_postings': True,
     'registered_on': '2000-01-01 00:00:00',
     'role': 'Role lorem ipsum dolor sit',
     'user_id': 9,
     'verified_on': '2000-01-01 00:00:00'}

To change any of the membership settings just set the relevant values and use update_member().

    >>> member.info['password'] = 'someencryptednewpasswordstring'
    >>> member.update()
    204