#!/usr/bin/python
#
# Copyright (C) 2008 Google, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Allow Google Apps domain administrators to manage groups, group members and group owners.

  GroupsService: Provides methods to manage groups, members and owners.
"""

__author__ = 'google-apps-apis@googlegroups.com'


import urllib
import gdata.apps
import gdata.apps.service
import gdata.service


API_VER = '2.0'
BASE_URL = '/a/feeds/group/' + API_VER + '/%s'
GROUP_MEMBER_URL = BASE_URL + '?member=%s'
GROUP_MEMBER_DIRECT_URL = GROUP_MEMBER_URL + '&directOnly=%s'
GROUP_ID_URL = BASE_URL + '/%s'
MEMBER_URL = BASE_URL + '/%s/member'
MEMBER_WITH_SUSPENDED_URL = MEMBER_URL + '?includeSuspendedUsers=%s'
MEMBER_ID_URL = MEMBER_URL + '/%s'
OWNER_URL = BASE_URL + '/%s/owner'
OWNER_WITH_SUSPENDED_URL = OWNER_URL + '?includeSuspendedUsers=%s'
OWNER_ID_URL = OWNER_URL + '/%s'

PERMISSION_OWNER = 'Owner'
PERMISSION_MEMBER = 'Member'
PERMISSION_DOMAIN = 'Domain'
PERMISSION_ANYONE = 'Anyone'


class GroupsService(gdata.apps.service.PropertyService):
  """Client for the Google Apps Groups service."""

  def _ServiceUrl(self, service_type, is_existed, group_id, member_id, owner_email,
                  direct_only=False, domain=None, suspended_users=False):
    if domain is None:
      domain = self.domain

    if service_type == 'group':
      if group_id != '' and is_existed:
        return GROUP_ID_URL % (domain, group_id)
      elif member_id != '':
        if direct_only:
          return GROUP_MEMBER_DIRECT_URL % (domain, urllib.quote_plus(member_id),
                                            self._Bool2Str(direct_only))
        else:
          return GROUP_MEMBER_URL % (domain, urllib.quote_plus(member_id))
      else:
        return BASE_URL % (domain)

    if service_type == 'member':
      if member_id != '' and is_existed:
        return MEMBER_ID_URL % (domain, group_id, urllib.quote_plus(member_id))
      elif suspended_users:
        return MEMBER_WITH_SUSPENDED_URL % (domain, group_id,
                                            self._Bool2Str(suspended_users))
      else:
        return MEMBER_URL % (domain, group_id)

    if service_type == 'owner':
      if owner_email != '' and is_existed:
        return OWNER_ID_URL % (domain, group_id, urllib.quote_plus(owner_email))
      elif suspended_users:
        return OWNER_WITH_SUSPENDED_URL % (domain, group_id,
                                           self._Bool2Str(suspended_users))
      else:
        return OWNER_URL % (domain, group_id)

  def _Bool2Str(self, b):
    if b is None:
      return None
    return str(b is True).lower()

  def _IsExisted(self, uri):
    try:
      self._GetProperties(uri)
      return True
    except gdata.apps.service.AppsForYourDomainException, e:
      if e.error_code == gdata.apps.service.ENTITY_DOES_NOT_EXIST:
        return False
      else:
        raise e

  def CreateGroup(self, group_id, group_name, description, email_permission):
    """Create a group.

    Args:
      group_id: The ID of the group (e.g. us-sales).
      group_name: The name of the group.
      description: A description of the group
      email_permission: The subscription permission of the group.

    Returns:
      A dict containing the result of the create operation.
    """
    uri = self._ServiceUrl('group', False, group_id, '', '')
    properties = {}
    properties['groupId'] = group_id
    properties['groupName'] = group_name
    properties['description'] = description
    properties['emailPermission'] = email_permission
    return self._PostProperties(uri, properties)

  def UpdateGroup(self, group_id, group_name, description, email_permission):
    """Update a group's name, description and/or permission.

    Args:
      group_id: The ID of the group (e.g. us-sales).
      group_name: The name of the group.
      description: A description of the group
      email_permission: The subscription permission of the group.

    Returns:
      A dict containing the result of the update operation.
    """
    uri = self._ServiceUrl('group', True, group_id, '', '')
    properties = {}
    properties['groupId'] = group_id
    properties['groupName'] = group_name
    properties['description'] = description
    properties['emailPermission'] = email_permission
    return self._PutProperties(uri, properties)

  def RetrieveGroup(self, group_id):
    """Retrieve a group based on its ID.

    Args:
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('group', True, group_id, '', '')
    return self._GetProperties(uri)

  def RetrieveAllGroups(self):
    """Retrieve all groups in the domain.

    Args:
      None

    Returns:
      A list containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('group', True, '', '', '')
    return self._GetPropertiesList(uri)

  def RetrievePageOfGroups(self, start_group=None):
    """Retrieve one page of groups in the domain.
    
    Args:
      start_group: The key to continue for pagination through all groups.
      
    Returns:
      A feed object containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('group', True, '', '', '')
    if start_group is not None:
      uri += "?start="+start_group
    property_feed = self._GetPropertyFeed(uri)
    return property_feed

  def RetrieveGroups(self, member_id, direct_only=False):
    """Retrieve all groups that belong to the given member_id.

    Args:
      member_id: The member's email address (e.g. member@example.com).
      direct_only: Boolean whether only return groups that this member directly belongs to.

    Returns:
      A list containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('group', True, '', member_id, '', direct_only=direct_only)
    return self._GetPropertiesList(uri)

  def DeleteGroup(self, group_id):
    """Delete a group based on its ID.

    Args:
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the delete operation.
    """
    uri = self._ServiceUrl('group', True, group_id, '', '')
    return self._DeleteProperties(uri)

  def AddMemberToGroup(self, member_id, group_id):
    """Add a member to a group.

    Args:
      member_id: The member's email address (e.g. member@example.com).
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the add operation.
    """
    uri = self._ServiceUrl('member', False, group_id, member_id, '')
    properties = {}
    properties['memberId'] = member_id
    return self._PostProperties(uri, properties)

  def IsMember(self, member_id, group_id):
    """Check whether the given member already exists in the given group.

    Args:
      member_id: The member's email address (e.g. member@example.com).
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      True if the member exists in the group.  False otherwise.
    """
    uri = self._ServiceUrl('member', True, group_id, member_id, '')
    return self._IsExisted(uri)

  def RetrieveMember(self, member_id, group_id):
    """Retrieve the given member in the given group.

    Args:
      member_id: The member's email address (e.g. member@example.com).
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('member', True, group_id, member_id, '')
    return self._GetProperties(uri)

  def RetrieveAllMembers(self, group_id, suspended_users=False):
    """Retrieve all members in the given group.

    Args:
      group_id: The ID of the group (e.g. us-sales).
      suspended_users: A boolean; should we include any suspended users in
        the membership list returned?

    Returns:
      A list containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('member', True, group_id, '', '',
                           suspended_users=suspended_users)
    return self._GetPropertiesList(uri)
    
  def RetrievePageOfMembers(self, group_id, suspended_users=False, start=None):
    """Retrieve one page of members of a given group.
    
    Args:
      group_id: The ID of the group (e.g. us-sales).
      suspended_users: A boolean; should we include any suspended users in
        the membership list returned?
      start: The key to continue for pagination through all members.

    Returns:
      A feed object containing the result of the retrieve operation.
    """
    
    uri = self._ServiceUrl('member', True, group_id, '', '',
                           suspended_users=suspended_users)
    if start is not None:
      if suspended_users:
        uri += "&start="+start
      else:
        uri += "?start="+start
    property_feed = self._GetPropertyFeed(uri)
    return property_feed

  def RemoveMemberFromGroup(self, member_id, group_id):
    """Remove the given member from the given group.

    Args:
      member_id: The member's email address (e.g. member@example.com).
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the remove operation.
    """
    uri = self._ServiceUrl('member', True, group_id, member_id, '')
    return self._DeleteProperties(uri)

  def AddOwnerToGroup(self, owner_email, group_id):
    """Add an owner to a group.

    Args:
      owner_email: The email address of a group owner.
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the add operation.
    """
    uri = self._ServiceUrl('owner', False, group_id, '', owner_email)
    properties = {}
    properties['email'] = owner_email
    return self._PostProperties(uri, properties)

  def IsOwner(self, owner_email, group_id):
    """Check whether the given member an owner of the given group.

    Args:
      owner_email: The email address of a group owner.
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      True if the member is an owner of the given group.  False otherwise.
    """
    uri = self._ServiceUrl('owner', True, group_id, '', owner_email)
    return self._IsExisted(uri)

  def RetrieveOwner(self, owner_email, group_id):
    """Retrieve the given owner in the given group.

    Args:
      owner_email: The email address of a group owner.
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('owner', True, group_id, '', owner_email)
    return self._GetProperties(uri)

  def RetrieveAllOwners(self, group_id, suspended_users=False):
    """Retrieve all owners of the given group.

    Args:
      group_id: The ID of the group (e.g. us-sales).
      suspended_users: A boolean; should we include any suspended users in
        the ownership list returned?

    Returns:
      A list containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('owner', True, group_id, '', '',
                           suspended_users=suspended_users)
    return self._GetPropertiesList(uri)
    
  def RetrievePageOfOwners(self, group_id, suspended_users=False, start=None):
    """Retrieve one page of owners of the given group.
    
    Args:
      group_id: The ID of the group (e.g. us-sales).
      suspended_users: A boolean; should we include any suspended users in
        the ownership list returned?
      start: The key to continue for pagination through all owners.

    Returns:
      A feed object containing the result of the retrieve operation.
    """
    uri = self._ServiceUrl('owner', True, group_id, '', '',
                           suspended_users=suspended_users)
    if start is not None:
      if suspended_users:
        uri += "&start="+start
      else:
        uri += "?start="+start
    property_feed = self._GetPropertyFeed(uri)
    return property_feed
        
  def RemoveOwnerFromGroup(self, owner_email, group_id):
    """Remove the given owner from the given group.

    Args:
      owner_email: The email address of a group owner.
      group_id: The ID of the group (e.g. us-sales).

    Returns:
      A dict containing the result of the remove operation.
    """
    uri = self._ServiceUrl('owner', True, group_id, '', owner_email)
    return self._DeleteProperties(uri)