diff --git a/restclient.txt b/restclient.txt new file mode 100644 index 0000000..75711a9 --- /dev/null +++ b/restclient.txt @@ -0,0 +1,202 @@ +=================== +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') + + >>> 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 + +