/gdata/apps/groups/service.py

  1#!/usr/bin/python
  2#
  3# Copyright (C) 2008 Google, Inc.
  4#
  5# Licensed under the Apache License, Version 2.0 (the "License");
  6# you may not use this file except in compliance with the License.
  7# You may obtain a copy of the License at
  8#
  9#      http://www.apache.org/licenses/LICENSE-2.0
 10#
 11# Unless required by applicable law or agreed to in writing, software
 12# distributed under the License is distributed on an "AS IS" BASIS,
 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14# See the License for the specific language governing permissions and
 15# limitations under the License.
 16
 17"""Allow Google Apps domain administrators to manage groups, group members and group owners.
 18
 19  GroupsService: Provides methods to manage groups, members and owners.
 20"""
 21
 22__author__ = 'google-apps-apis@googlegroups.com'
 23
 24
 25import urllib
 26import gdata.apps
 27import gdata.apps.service
 28import gdata.service
 29
 30
 31API_VER = '2.0'
 32BASE_URL = '/a/feeds/group/' + API_VER + '/%s'
 33GROUP_MEMBER_URL = BASE_URL + '?member=%s'
 34GROUP_MEMBER_DIRECT_URL = GROUP_MEMBER_URL + '&directOnly=%s'
 35GROUP_ID_URL = BASE_URL + '/%s'
 36MEMBER_URL = BASE_URL + '/%s/member'
 37MEMBER_WITH_SUSPENDED_URL = MEMBER_URL + '?includeSuspendedUsers=%s'
 38MEMBER_ID_URL = MEMBER_URL + '/%s'
 39OWNER_URL = BASE_URL + '/%s/owner'
 40OWNER_WITH_SUSPENDED_URL = OWNER_URL + '?includeSuspendedUsers=%s'
 41OWNER_ID_URL = OWNER_URL + '/%s'
 42
 43PERMISSION_OWNER = 'Owner'
 44PERMISSION_MEMBER = 'Member'
 45PERMISSION_DOMAIN = 'Domain'
 46PERMISSION_ANYONE = 'Anyone'
 47
 48
 49class GroupsService(gdata.apps.service.PropertyService):
 50  """Client for the Google Apps Groups service."""
 51
 52  def _ServiceUrl(self, service_type, is_existed, group_id, member_id, owner_email,
 53                  direct_only=False, domain=None, suspended_users=False):
 54    if domain is None:
 55      domain = self.domain
 56
 57    if service_type == 'group':
 58      if group_id != '' and is_existed:
 59        return GROUP_ID_URL % (domain, group_id)
 60      elif member_id != '':
 61        if direct_only:
 62          return GROUP_MEMBER_DIRECT_URL % (domain, urllib.quote_plus(member_id),
 63                                            self._Bool2Str(direct_only))
 64        else:
 65          return GROUP_MEMBER_URL % (domain, urllib.quote_plus(member_id))
 66      else:
 67        return BASE_URL % (domain)
 68
 69    if service_type == 'member':
 70      if member_id != '' and is_existed:
 71        return MEMBER_ID_URL % (domain, group_id, urllib.quote_plus(member_id))
 72      elif suspended_users:
 73        return MEMBER_WITH_SUSPENDED_URL % (domain, group_id,
 74                                            self._Bool2Str(suspended_users))
 75      else:
 76        return MEMBER_URL % (domain, group_id)
 77
 78    if service_type == 'owner':
 79      if owner_email != '' and is_existed:
 80        return OWNER_ID_URL % (domain, group_id, urllib.quote_plus(owner_email))
 81      elif suspended_users:
 82        return OWNER_WITH_SUSPENDED_URL % (domain, group_id,
 83                                           self._Bool2Str(suspended_users))
 84      else:
 85        return OWNER_URL % (domain, group_id)
 86
 87  def _Bool2Str(self, b):
 88    if b is None:
 89      return None
 90    return str(b is True).lower()
 91
 92  def _IsExisted(self, uri):
 93    try:
 94      self._GetProperties(uri)
 95      return True
 96    except gdata.apps.service.AppsForYourDomainException, e:
 97      if e.error_code == gdata.apps.service.ENTITY_DOES_NOT_EXIST:
 98        return False
 99      else:
100        raise e
101
102  def CreateGroup(self, group_id, group_name, description, email_permission):
103    """Create a group.
104
105    Args:
106      group_id: The ID of the group (e.g. us-sales).
107      group_name: The name of the group.
108      description: A description of the group
109      email_permission: The subscription permission of the group.
110
111    Returns:
112      A dict containing the result of the create operation.
113    """
114    uri = self._ServiceUrl('group', False, group_id, '', '')
115    properties = {}
116    properties['groupId'] = group_id
117    properties['groupName'] = group_name
118    properties['description'] = description
119    properties['emailPermission'] = email_permission
120    return self._PostProperties(uri, properties)
121
122  def UpdateGroup(self, group_id, group_name, description, email_permission):
123    """Update a group's name, description and/or permission.
124
125    Args:
126      group_id: The ID of the group (e.g. us-sales).
127      group_name: The name of the group.
128      description: A description of the group
129      email_permission: The subscription permission of the group.
130
131    Returns:
132      A dict containing the result of the update operation.
133    """
134    uri = self._ServiceUrl('group', True, group_id, '', '')
135    properties = {}
136    properties['groupId'] = group_id
137    properties['groupName'] = group_name
138    properties['description'] = description
139    properties['emailPermission'] = email_permission
140    return self._PutProperties(uri, properties)
141
142  def RetrieveGroup(self, group_id):
143    """Retrieve a group based on its ID.
144
145    Args:
146      group_id: The ID of the group (e.g. us-sales).
147
148    Returns:
149      A dict containing the result of the retrieve operation.
150    """
151    uri = self._ServiceUrl('group', True, group_id, '', '')
152    return self._GetProperties(uri)
153
154  def RetrieveAllGroups(self):
155    """Retrieve all groups in the domain.
156
157    Args:
158      None
159
160    Returns:
161      A list containing the result of the retrieve operation.
162    """
163    uri = self._ServiceUrl('group', True, '', '', '')
164    return self._GetPropertiesList(uri)
165
166  def RetrieveGroups(self, member_id, direct_only=False):
167    """Retrieve all groups that belong to the given member_id.
168
169    Args:
170      member_id: The member's email address (e.g. member@example.com).
171      direct_only: Boolean whether only return groups that this member directly belongs to.
172
173    Returns:
174      A list containing the result of the retrieve operation.
175    """
176    uri = self._ServiceUrl('group', True, '', member_id, '', direct_only=direct_only)
177    return self._GetPropertiesList(uri)
178
179  def DeleteGroup(self, group_id):
180    """Delete a group based on its ID.
181
182    Args:
183      group_id: The ID of the group (e.g. us-sales).
184
185    Returns:
186      A dict containing the result of the delete operation.
187    """
188    uri = self._ServiceUrl('group', True, group_id, '', '')
189    return self._DeleteProperties(uri)
190
191  def AddMemberToGroup(self, member_id, group_id):
192    """Add a member to a group.
193
194    Args:
195      member_id: The member's email address (e.g. member@example.com).
196      group_id: The ID of the group (e.g. us-sales).
197
198    Returns:
199      A dict containing the result of the add operation.
200    """
201    uri = self._ServiceUrl('member', False, group_id, member_id, '')
202    properties = {}
203    properties['memberId'] = member_id
204    return self._PostProperties(uri, properties)
205
206  def IsMember(self, member_id, group_id):
207    """Check whether the given member already exists in the given group.
208
209    Args:
210      member_id: The member's email address (e.g. member@example.com).
211      group_id: The ID of the group (e.g. us-sales).
212
213    Returns:
214      True if the member exists in the group.  False otherwise.
215    """
216    uri = self._ServiceUrl('member', True, group_id, member_id, '')
217    return self._IsExisted(uri)
218
219  def RetrieveMember(self, member_id, group_id):
220    """Retrieve the given member in the given group.
221
222    Args:
223      member_id: The member's email address (e.g. member@example.com).
224      group_id: The ID of the group (e.g. us-sales).
225
226    Returns:
227      A dict containing the result of the retrieve operation.
228    """
229    uri = self._ServiceUrl('member', True, group_id, member_id, '')
230    return self._GetProperties(uri)
231
232  def RetrieveAllMembers(self, group_id, suspended_users=False):
233    """Retrieve all members in the given group.
234
235    Args:
236      group_id: The ID of the group (e.g. us-sales).
237      suspended_users: A boolean; should we include any suspended users in
238        the membership list returned?
239
240    Returns:
241      A list containing the result of the retrieve operation.
242    """
243    uri = self._ServiceUrl('member', True, group_id, '', '',
244                           suspended_users=suspended_users)
245    return self._GetPropertiesList(uri)
246
247  def RemoveMemberFromGroup(self, member_id, group_id):
248    """Remove the given member from the given group.
249
250    Args:
251      member_id: The member's email address (e.g. member@example.com).
252      group_id: The ID of the group (e.g. us-sales).
253
254    Returns:
255      A dict containing the result of the remove operation.
256    """
257    uri = self._ServiceUrl('member', True, group_id, member_id, '')
258    return self._DeleteProperties(uri)
259
260  def AddOwnerToGroup(self, owner_email, group_id):
261    """Add an owner to a group.
262
263    Args:
264      owner_email: The email address of a group owner.
265      group_id: The ID of the group (e.g. us-sales).
266
267    Returns:
268      A dict containing the result of the add operation.
269    """
270    uri = self._ServiceUrl('owner', False, group_id, '', owner_email)
271    properties = {}
272    properties['email'] = owner_email
273    return self._PostProperties(uri, properties)
274
275  def IsOwner(self, owner_email, group_id):
276    """Check whether the given member an owner of the given group.
277
278    Args:
279      owner_email: The email address of a group owner.
280      group_id: The ID of the group (e.g. us-sales).
281
282    Returns:
283      True if the member is an owner of the given group.  False otherwise.
284    """
285    uri = self._ServiceUrl('owner', True, group_id, '', owner_email)
286    return self._IsExisted(uri)
287
288  def RetrieveOwner(self, owner_email, group_id):
289    """Retrieve the given owner in the given group.
290
291    Args:
292      owner_email: The email address of a group owner.
293      group_id: The ID of the group (e.g. us-sales).
294
295    Returns:
296      A dict containing the result of the retrieve operation.
297    """
298    uri = self._ServiceUrl('owner', True, group_id, '', owner_email)
299    return self._GetProperties(uri)
300
301  def RetrieveAllOwners(self, group_id, suspended_users=False):
302    """Retrieve all owners of the given group.
303
304    Args:
305      group_id: The ID of the group (e.g. us-sales).
306      suspended_users: A boolean; should we include any suspended users in
307        the ownership list returned?
308
309    Returns:
310      A list containing the result of the retrieve operation.
311    """
312    uri = self._ServiceUrl('owner', True, group_id, '', '',
313                           suspended_users=suspended_users)
314    return self._GetPropertiesList(uri)
315
316  def RemoveOwnerFromGroup(self, owner_email, group_id):
317    """Remove the given owner from the given group.
318
319    Args:
320      owner_email: The email address of a group owner.
321      group_id: The ID of the group (e.g. us-sales).
322
323    Returns:
324      A dict containing the result of the remove operation.
325    """
326    uri = self._ServiceUrl('owner', True, group_id, '', owner_email)
327    return self._DeleteProperties(uri)