/gdata/calendar_resource/client.py

  1#!/usr/bin/python
  2#
  3# Copyright 2009 Google Inc. All Rights Reserved.
  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"""CalendarResourceClient simplifies Calendar Resources API calls.
 18
 19CalendarResourceClient extends gdata.client.GDClient to ease interaction with
 20the Google Apps Calendar Resources API.  These interactions include the ability
 21to create, retrieve, update, and delete calendar resources in a Google Apps
 22domain.
 23"""
 24
 25
 26__author__ = 'Vic Fryzel <vf@google.com>'
 27
 28
 29import urllib
 30import atom.data
 31import gdata.client
 32import gdata.calendar_resource.data
 33
 34
 35# Feed URI template.  This must end with a /
 36RESOURCE_FEED_TEMPLATE = '/a/feeds/calendar/resource/%s/%s/'
 37
 38
 39class CalendarResourceClient(gdata.client.GDClient):
 40  """Client extension for the Google Calendar Resource API service.
 41  
 42  Attributes:
 43    host: string The hostname for the Calendar Resouce API service.
 44    api_version: string The version of the Calendar Resource API.
 45  """
 46
 47  host = 'apps-apis.google.com'
 48  api_version = '2.0'
 49  auth_service = 'apps'
 50  auth_scopes = gdata.gauth.AUTH_SCOPES['apps']
 51
 52  def __init__(self, domain, auth_token=None, **kwargs):
 53    """Constructs a new client for the Calendar Resource API.
 54
 55    Args:
 56      domain: string The Google Apps domain with Calendar Resources.
 57      auth_token: (optional) gdata.gauth.ClientLoginToken, AuthSubToken, or 
 58        OAuthToken which authorizes this client to edit the calendar resource 
 59        data.
 60      kwargs: The other parameters to pass to gdata.client.GDClient constructor.
 61    """
 62    gdata.client.GDClient.__init__(self, auth_token=auth_token, **kwargs)
 63    self.domain = domain
 64
 65  def make_resource_feed_uri(self, resource_id=None, params=None):
 66    """Creates a resource feed URI for the Calendar Resource API.
 67
 68    Using this client's Google Apps domain, create a feed URI for calendar
 69    resources in that domain. If a resource_id is provided, return a URI
 70    for that specific resource.  If params are provided, append them as GET
 71    params.
 72
 73    Args:
 74      resource_id: string (optional) The ID of the calendar resource for which
 75        to make a feed URI.
 76      params: dict (optional) key -> value params to append as GET vars to the
 77        URI. Example: params={'start': 'my-resource-id'}
 78    Returns:
 79      A string giving the URI for calendar resources for this client's Google
 80      Apps domain.
 81    """
 82    uri = RESOURCE_FEED_TEMPLATE % (self.api_version, self.domain)
 83    if resource_id:
 84      uri += resource_id
 85    if params:
 86      uri += '?' + urllib.urlencode(params)
 87    return uri
 88
 89  MakeResourceFeedUri = make_resource_feed_uri
 90
 91  def get_resource_feed(self, uri=None, **kwargs):
 92    """Fetches a ResourceFeed of calendar resources at the given URI.
 93
 94    Args:
 95      uri: string The URI of the feed to pull.
 96
 97    Returns:
 98      A ResourceFeed object representing the feed at the given URI.
 99    """
100
101    if uri is None:
102      uri = self.MakeResourceFeedUri()
103    return self.get_feed(uri,
104      desired_class=gdata.calendar_resource.data.CalendarResourceFeed,
105      **kwargs)
106
107  GetResourceFeed = get_resource_feed
108  
109  def get_resource(self, uri=None, resource_id=None, **kwargs):
110    """Fetches a single calendar resource by resource ID.
111
112    Args:
113      uri: string The base URI of the feed from which to fetch the resource.
114      resource_id: string The string ID of the Resource to fetch.
115    
116    Returns:
117      A Resource object representing the calendar resource with the given 
118      base URI and resource ID.
119    """
120
121    if uri is None:
122      uri = self.MakeResourceUri(resource_id)
123    return self.get_entry(uri,
124      desired_class=gdata.calendar_resource.data.CalendarResourceEntry,
125      **kwargs)
126
127  GetResource = get_resource
128
129  def create_resource(self, resource_id, resource_common_name=None,
130    resource_description=None, resource_type=None, **kwargs):
131    """Creates a calendar resource with the given properties.
132
133    Args:
134      resource_id: string The resource ID of the calendar resource.
135      resource_common_name: string (optional) The common name of the resource.
136      resource_description: string (optional) The description of the resource.
137      resource_type: string (optional) The type of the resource.
138
139    Returns:
140      gdata.calendar_resource.data.CalendarResourceEntry of the new resource.
141    """
142    new_resource = gdata.calendar_resource.data.CalendarResourceEntry(
143        resource_id=resource_id, resource_common_name=resource_common_name,
144        resource_description=resource_description, resource_type=resource_type)
145    return self.post(new_resource, self.MakeResourceFeedUri(), **kwargs)
146
147  CreateResource = create_resource
148  
149  def update_resource(self, resource_id, resource_common_name=None,
150    resource_description=None, resource_type=None, **kwargs):
151    """Updates the calendar resource with the given resource ID.
152
153    Args:
154      resource_id: string The resource ID of the calendar resource to update.
155      resource_common_name: string (optional) The common name to give the
156                            resource.
157      resource_description: string (optional) The description to give the
158                            resource.
159      resource_type: string (optional) The type to give the resource.
160
161    Returns:
162      gdata.calendar_resource.data.CalendarResourceEntry of the updated resource.
163    """
164    new_resource = gdata.calendar_resource.data.CalendarResourceEntry(
165      resource_id=resource_id, resource_common_name=resource_common_name,
166      resource_description=resource_description, resource_type=resource_type)
167    return self.update(new_resource,
168      self.MakeResourceFeedUri(resource_id), **kwargs)
169
170  UpdateResource = update_resource
171
172  def delete_resource(self, resource_id, **kwargs):
173    """Deletes the calendar resource with the given resource ID.
174
175    Args:
176      resource_id: string The resource ID of the calendar resource to delete.
177      kwargs: Other parameters to pass to gdata.client.delete()
178    
179    Returns:
180      An HTTP response object.  See gdata.client.request().
181    """
182
183    return self.delete(self.MakeResourceFeedUri(resource_id),
184      **kwargs)
185
186  DeleteResource = delete_resource