Merge lp:~flo-fuchs/mailman.client/settings into lp:mailman.client

[Florian Fuchs]

Hi,

I have added methods to delete mailing lists as well as a _Settings class to read and write list settings. Please feel free to make any changes you want (...and, of course, tell me if you feel this should be done completely differently... ;-)

Cheers
Florian

[Barry Warsaw (barry)]

This looks good, thanks! I have just two minor suggestions.

* Where you're returning a unicode string object in the doctests, it would be better to use 'print' so you don't get the ugly u'' prefixes. E.g., instead of:

>>> settings_new['description']
u'A very meaningful description.'

use:

>>> print settings_new['description']
A very meaningful description.

* You should not need to use the u'' strings in your doctests. Mailman does a 'from __future__ import unicode_literals' in all its .py files to force literals to be unicodes (in the absence of explicit b'' prefixes). mailman.client should do the same. To make this work in doctests, you need to set the testobj's globs in the doctest's setUp(). See src/mailman/tests/test_documentation.py down about line 183 for an example.

Other than that, it looks great, and please do merge it after consideration of the above. Thanks!

review: Approve

[lp:~flo-fuchs/mailman.client/settings]

15. By Florian Fuchs on 2011-05-30

* added email address lookup to get_member and unsubscribe methods to reflect changes in mailman 3a7
* added missing print statements in doctest

[Florian Fuchs (flo-fuchs)]

Hi,

I've added a few changes to make the client compatible with the current Mailman3 alpha7.

Member resources now use IDs instead of email adresses (on the API side). The client doesn't know this ID when provided with an email adress (for example to get membership information or to unsubscribe an email address from a list). In order to find the right ID, the client needs to iterate over the existing member roster. This probably isn't ideal, especially when lists have a large number of members. But it's probably not an issue that the client lib can solve differently...

Thanks!
Florian

review: Needs Resubmitting

[Barry Warsaw (barry)]

This looks great; a couple of comments:

* See above for recommendations against u'' strings and for using print instead of returning strings directly in doctests.

* Could you please open a bug (tagged with 'mailman3') on the need to expose an API call to look up a member-id given an email address? I'll make sure to expose that in a8.

With the above consideration, I'll approve this change. Thanks! And feel free to land it.

review: Approve

[lp:~flo-fuchs/mailman.client/settings]

16. By Florian Fuchs on 2011-06-20

use print instead of returning strings directly in doctests

[Florian Fuchs (flo-fuchs)]

Hi,

after merging the changes locally LP doesn't let me push to lp:mailman.client ("readonly transport"). Maybe that's because the approved revision is 14 while the branch is currently at rev. 16?

Thanks!
Florian

review: Needs Information

[Barry Warsaw (barry)]

I think this is Launchpad's way of saying you didn't have push permissions. Have you ever been able to push to this branch? Anyway, I added ~flo-fuchs to ~mailman-coders, which owns the trunk, so please try again. (P.S. I first accidentally added your doppleganger :)

=== modified file 'mailman/client/_client.py'
--- mailman/client/_client.py	2010-12-26 21:11:54 +0000
+++ mailman/client/_client.py	2011-06-20 06:58:35 +0000
@@ -189,6 +189,10 @@
             'lists/{0}'.format(fqdn_listname))
         return _List(self._connection, content['self_link'])
 
+    def delete_list(self, fqdn_listname):
+        response, content = self._connection.call(
+            'lists/{0}'.format(fqdn_listname), None, 'DELETE')
+
 
 

 class _Domain:
@@ -282,15 +286,26 @@
                 for entry in sorted(content['entries'],
                                     key=itemgetter('address'))]
 
+    @property
+    def settings(self):
+        return _Settings(self._connection,
+            'lists/{0}/config'.format(self.fqdn_listname))
+
     def get_member(self, address):
         """Get a membership.
 
         :param address: The email address of the member for this list.
         :return: A member proxy object.
         """
-        response, content = self._connection.call(
-            'lists/{0}/member/{1}'.format(self.fqdn_listname, address))
-        return _Member(self._connection, content['self_link'])
+        # In order to get the member object we need to
+        # iterate over the existing member list
+        for member in self.members:
+            if member.address == address:
+                return member
+                break
+        else:
+            raise ValueError('%s is not a member address of %s' %
+                             (address, self.fqdn_listname))
 
     def subscribe(self, address, real_name=None):
         """Subscribe an email address to a mailing list.
@@ -303,7 +318,7 @@
         """
         data = dict(
             fqdn_listname=self.fqdn_listname,
-            address=address,
+            subscriber=address,
             real_name=real_name,
             )
         response, content = self._connection.call('members', data)
@@ -314,9 +329,21 @@
 
         :param address: The address to unsubscribe.
         """
-        self._connection.call(
-            'lists/{0}/member/{1}'.format(self.fqdn_listname, address),
-            method='DELETE')
+        # In order to get the member object we need to
+        # iterate over the existing member list
+
+        for member in self.members:
+            if member.address == address:
+                self._connection.call(member.self_link, method='DELETE')
+                break
+        else:
+            raise ValueError('%s is not a member address of %s' %
+                             (address, self.fqdn_listname))
+
+
+    def delete(self):
+        response, content = self._connection.call(
+            'lists/{0}'.format(self.fqdn_listname), None, 'DELETE')
 
 
 

@@ -345,11 +372,71 @@
         self._get_info()
         return self._info['address']
 
+    @property
+    def self_link(self):
+        self._get_info()
+        return self._info['self_link']
+
+    @property
+    def role(self):
+        self._get_info()
+        return self._info['role']
+
+    @property
+    def user(self):
+        self._get_info()
+        return self._info['user']
+
     def unsubscribe(self):
         """Unsubscribe the member from a mailing list.
 
-        :param address: The address to unsubscribe.
+        :param self_link: The REST resource to delete
         """
-        self._connection.call(
-            'lists/{0}/member/{1}'.format(self.fqdn_listname, self.address),
-            method='DELETE')
+        self._connection.call(self.self_link, method='DELETE')
+
+
+READ_ONLY_ATTRS = ('bounces_address', 'created_at', 'digest_last_sent_at',
+                   'fqdn_listname', 'http_etag', 'host_name', 'join_address',
+                   'last_post_at', 'leave_address', 'list_id', 'list_name',
+                   'next_digest_number', 'no_reply_address', 'owner_address',
+                   'post_id', 'posting_address', 'request_address', 'scheme',
+                   'volume', 'web_host',)
+
+
+class _Settings():
+    def __init__(self, connection, url):
+        self._connection = connection
+        self._url = url
+        self._info = None
+        self._get_info()
+
+    def __repr__(self):
+        return repr(self._info)
+
+    def _get_info(self):
+        if self._info is None:
+            response, content = self._connection.call(self._url)
+            self._info = content
+
+    def __iter__(self):
+        for key in self._info.keys():
+            yield key
+
+    def __getitem__(self, key):
+        return self._info[key]
+
+    def __setitem__(self, key, value):
+        self._info[key] = value
+
+    def __len__(self):
+        return len(self._info)
+
+    def save(self):
+        data = {}
+        for attribute, value in self._info.items():
+            if attribute not in READ_ONLY_ATTRS:
+                data[attribute] = value
+        response, content = self._connection.call(self._url, data, 'PATCH')
+
+
+

=== modified file 'mailman/client/docs/using.txt'
--- mailman/client/docs/using.txt	2010-12-26 21:11:54 +0000
+++ mailman/client/docs/using.txt	2011-06-20 06:58:35 +0000
@@ -119,6 +119,20 @@
     <List "[e-mail]">
     <List "[e-mail]">
 
+You can use a list instance to delete the list.
+
+    >>> test_three = client.get_list('[e-mail]')
+    >>> test_three.delete()
+
+You can also delete a list using the client instance's delete_list method.
+
+    >>> client.delete_list('[e-mail]')
+
+    >>> for mlist in client.lists:
+    ...     print mlist
+    <List "[e-mail]">
+    <List "[e-mail]">
+
 
 Membership
 ==========
@@ -170,6 +184,19 @@
     >>> cris = test_two.get_member('[e-mail]')
     >>> cris
     <Member "[e-mail]" on "[e-mail]">
+    >>> print cris.role
+    member
+    >>> print cris.self_link
+    http://localhost:8001/3.0/members/4
+    >>> print cris.user
+    http://localhost:8001/3.0/users/3
+
+If you use an address which is not a member of test_two `ValueError` is raised:
+
+    >>> test_two.unsubscribe('[e-mail]')
+    Traceback (most recent call last):
+    ...
+    ValueError: [e-mail] is not a member address of [e-mail]
 
 After a while, Anna decides to unsubscribe from the Test One mailing list,
 though she keeps her Test Two membership active.
@@ -188,3 +215,48 @@
     ...     print member
     <Member "[e-mail]" on "[e-mail]">
     <Member "[e-mail]" on "[e-mail]">
+
+If you try to unsubscribe an address which is not a member address `ValueError` is raised:
+
+    >>> test_one.unsubscribe('[e-mail]')
+    Traceback (most recent call last):
+    ...
+    ValueError: [e-mail] is not a member address of [e-mail]
+
+
+List Settings
+=============
+
+We can get all list settings via a lists settings attribute. A proxy object for the settings is returned which behaves much like a dictionary.
+
+    >>> settings = test_one.settings
+    >>> len(settings)
+    48
+
+    >>> for attr in sorted(settings):
+    ...     print attr + ': ' + str(settings[attr])
+    acceptable_aliases: []
+    ...
+    welcome_msg:
+
+    >>> print settings['real_name']
+    Test-one
+
+We can access all valid list settings as attributes.
+
+    >>> print settings['fqdn_listname']
+    [e-mail]
+    >>> print settings['description']
+
+    >>> settings['description'] = 'A very meaningful description.'
+    >>> settings['real_name'] = 'Test Numero Uno'
+
+    >>> settings.save()
+
+    >>> settings_new = test_one.settings
+    >>> print settings_new['description']
+    A very meaningful description.
+    >>> print settings_new['real_name']
+    Test Numero Uno
+
+