/gdata/contacts/service.py
http://radioappz.googlecode.com/ · Python · 427 lines · 343 code · 27 blank · 57 comment · 10 complexity · 34e41ced316941233a74fb17fc278eb1 MD5 · raw file
- #!/usr/bin/env python
- #
- # Copyright 2009 Google Inc. All Rights Reserved.
- #
- # 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.
- """ContactsService extends the GDataService for Google Contacts operations.
- ContactsService: Provides methods to query feeds and manipulate items.
- Extends GDataService.
- DictionaryToParamList: Function which converts a dictionary into a list of
- URL arguments (represented as strings). This is a
- utility function used in CRUD operations.
- """
- __author__ = 'dbrattli (Dag Brattli)'
- import gdata
- import gdata.calendar
- import gdata.service
- DEFAULT_BATCH_URL = ('http://www.google.com/m8/feeds/contacts/default/full'
- '/batch')
- DEFAULT_PROFILES_BATCH_URL = ('http://www.google.com'
- '/m8/feeds/profiles/default/full/batch')
- GDATA_VER_HEADER = 'GData-Version'
- class Error(Exception):
- pass
- class RequestError(Error):
- pass
- class ContactsService(gdata.service.GDataService):
- """Client for the Google Contacts service."""
- def __init__(self, email=None, password=None, source=None,
- server='www.google.com', additional_headers=None,
- contact_list='default', **kwargs):
- """Creates a client for the Contacts service.
- Args:
- email: string (optional) The user's email address, used for
- authentication.
- password: string (optional) The user's password.
- source: string (optional) The name of the user's application.
- server: string (optional) The name of the server to which a connection
- will be opened. Default value: 'www.google.com'.
- contact_list: string (optional) The name of the default contact list to
- use when no URI is specified to the methods of the service.
- Default value: 'default' (the logged in user's contact list).
- **kwargs: The other parameters to pass to gdata.service.GDataService
- constructor.
- """
- self.contact_list = contact_list
- gdata.service.GDataService.__init__(
- self, email=email, password=password, service='cp', source=source,
- server=server, additional_headers=additional_headers, **kwargs)
- def GetFeedUri(self, kind='contacts', contact_list=None, projection='full',
- scheme=None):
- """Builds a feed URI.
- Args:
- kind: The type of feed to return, typically 'groups' or 'contacts'.
- Default value: 'contacts'.
- contact_list: The contact list to return a feed for.
- Default value: self.contact_list.
- projection: The projection to apply to the feed contents, for example
- 'full', 'base', 'base/12345', 'full/batch'. Default value: 'full'.
- scheme: The URL scheme such as 'http' or 'https', None to return a
- relative URI without hostname.
- Returns:
- A feed URI using the given kind, contact list, and projection.
- Example: '/m8/feeds/contacts/default/full'.
- """
- contact_list = contact_list or self.contact_list
- if kind == 'profiles':
- contact_list = 'domain/%s' % contact_list
- prefix = scheme and '%s://%s' % (scheme, self.server) or ''
- return '%s/m8/feeds/%s/%s/%s' % (prefix, kind, contact_list, projection)
- def GetContactsFeed(self, uri=None):
- uri = uri or self.GetFeedUri()
- return self.Get(uri, converter=gdata.contacts.ContactsFeedFromString)
- def GetContact(self, uri):
- return self.Get(uri, converter=gdata.contacts.ContactEntryFromString)
- def CreateContact(self, new_contact, insert_uri=None, url_params=None,
- escape_params=True):
- """Adds an new contact to Google Contacts.
- Args:
- new_contact: atom.Entry or subclass A new contact which is to be added to
- Google Contacts.
- insert_uri: the URL to post new contacts to the feed
- url_params: dict (optional) Additional URL parameters to be included
- in the insertion request.
- escape_params: boolean (optional) If true, the url_parameters will be
- escaped before they are included in the request.
- Returns:
- On successful insert, an entry containing the contact created
- On failure, a RequestError is raised of the form:
- {'status': HTTP status code from server,
- 'reason': HTTP reason from the server,
- 'body': HTTP body of the server's response}
- """
- insert_uri = insert_uri or self.GetFeedUri()
- return self.Post(new_contact, insert_uri, url_params=url_params,
- escape_params=escape_params,
- converter=gdata.contacts.ContactEntryFromString)
- def UpdateContact(self, edit_uri, updated_contact, url_params=None,
- escape_params=True):
- """Updates an existing contact.
- Args:
- edit_uri: string The edit link URI for the element being updated
- updated_contact: string, atom.Entry or subclass containing
- the Atom Entry which will replace the contact which is
- stored at the edit_url
- url_params: dict (optional) Additional URL parameters to be included
- in the update request.
- escape_params: boolean (optional) If true, the url_parameters will be
- escaped before they are included in the request.
- Returns:
- On successful update, a httplib.HTTPResponse containing the server's
- response to the PUT request.
- On failure, a RequestError is raised of the form:
- {'status': HTTP status code from server,
- 'reason': HTTP reason from the server,
- 'body': HTTP body of the server's response}
- """
- return self.Put(updated_contact, self._CleanUri(edit_uri),
- url_params=url_params,
- escape_params=escape_params,
- converter=gdata.contacts.ContactEntryFromString)
- def DeleteContact(self, edit_uri, extra_headers=None,
- url_params=None, escape_params=True):
- """Removes an contact with the specified ID from Google Contacts.
- Args:
- edit_uri: string The edit URL of the entry to be deleted. Example:
- '/m8/feeds/contacts/default/full/xxx/yyy'
- url_params: dict (optional) Additional URL parameters to be included
- in the deletion request.
- escape_params: boolean (optional) If true, the url_parameters will be
- escaped before they are included in the request.
- Returns:
- On successful delete, a httplib.HTTPResponse containing the server's
- response to the DELETE request.
- On failure, a RequestError is raised of the form:
- {'status': HTTP status code from server,
- 'reason': HTTP reason from the server,
- 'body': HTTP body of the server's response}
- """
- return self.Delete(self._CleanUri(edit_uri),
- url_params=url_params, escape_params=escape_params)
- def GetGroupsFeed(self, uri=None):
- uri = uri or self.GetFeedUri('groups')
- return self.Get(uri, converter=gdata.contacts.GroupsFeedFromString)
- def CreateGroup(self, new_group, insert_uri=None, url_params=None,
- escape_params=True):
- insert_uri = insert_uri or self.GetFeedUri('groups')
- return self.Post(new_group, insert_uri, url_params=url_params,
- escape_params=escape_params,
- converter=gdata.contacts.GroupEntryFromString)
- def UpdateGroup(self, edit_uri, updated_group, url_params=None,
- escape_params=True):
- return self.Put(updated_group, self._CleanUri(edit_uri),
- url_params=url_params,
- escape_params=escape_params,
- converter=gdata.contacts.GroupEntryFromString)
- def DeleteGroup(self, edit_uri, extra_headers=None,
- url_params=None, escape_params=True):
- return self.Delete(self._CleanUri(edit_uri),
- url_params=url_params, escape_params=escape_params)
- def ChangePhoto(self, media, contact_entry_or_url, content_type=None,
- content_length=None):
- """Change the photo for the contact by uploading a new photo.
- Performs a PUT against the photo edit URL to send the binary data for the
- photo.
- Args:
- media: filename, file-like-object, or a gdata.MediaSource object to send.
- contact_entry_or_url: ContactEntry or str If it is a ContactEntry, this
- method will search for an edit photo link URL and
- perform a PUT to the URL.
- content_type: str (optional) the mime type for the photo data. This is
- necessary if media is a file or file name, but if media
- is a MediaSource object then the media object can contain
- the mime type. If media_type is set, it will override the
- mime type in the media object.
- content_length: int or str (optional) Specifying the content length is
- only required if media is a file-like object. If media
- is a filename, the length is determined using
- os.path.getsize. If media is a MediaSource object, it is
- assumed that it already contains the content length.
- """
- if isinstance(contact_entry_or_url, gdata.contacts.ContactEntry):
- url = contact_entry_or_url.GetPhotoEditLink().href
- else:
- url = contact_entry_or_url
- if isinstance(media, gdata.MediaSource):
- payload = media
- # If the media object is a file-like object, then use it as the file
- # handle in the in the MediaSource.
- elif hasattr(media, 'read'):
- payload = gdata.MediaSource(file_handle=media,
- content_type=content_type, content_length=content_length)
- # Assume that the media object is a file name.
- else:
- payload = gdata.MediaSource(content_type=content_type,
- content_length=content_length, file_path=media)
- return self.Put(payload, url)
- def GetPhoto(self, contact_entry_or_url):
- """Retrives the binary data for the contact's profile photo as a string.
-
- Args:
- contact_entry_or_url: a gdata.contacts.ContactEntry objecr or a string
- containing the photo link's URL. If the contact entry does not
- contain a photo link, the image will not be fetched and this method
- will return None.
- """
- # TODO: add the ability to write out the binary image data to a file,
- # reading and writing a chunk at a time to avoid potentially using up
- # large amounts of memory.
- url = None
- if isinstance(contact_entry_or_url, gdata.contacts.ContactEntry):
- photo_link = contact_entry_or_url.GetPhotoLink()
- if photo_link:
- url = photo_link.href
- else:
- url = contact_entry_or_url
- if url:
- return self.Get(url, converter=str)
- else:
- return None
- def DeletePhoto(self, contact_entry_or_url):
- url = None
- if isinstance(contact_entry_or_url, gdata.contacts.ContactEntry):
- url = contact_entry_or_url.GetPhotoEditLink().href
- else:
- url = contact_entry_or_url
- if url:
- self.Delete(url)
- def GetProfilesFeed(self, uri=None):
- """Retrieves a feed containing all domain's profiles.
- Args:
- uri: string (optional) the URL to retrieve the profiles feed,
- for example /m8/feeds/profiles/default/full
- Returns:
- On success, a ProfilesFeed containing the profiles.
- On failure, raises a RequestError.
- """
-
- uri = uri or self.GetFeedUri('profiles')
- return self.Get(uri,
- converter=gdata.contacts.ProfilesFeedFromString)
- def GetProfile(self, uri):
- """Retrieves a domain's profile for the user.
- Args:
- uri: string the URL to retrieve the profiles feed,
- for example /m8/feeds/profiles/default/full/username
- Returns:
- On success, a ProfileEntry containing the profile for the user.
- On failure, raises a RequestError
- """
- return self.Get(uri,
- converter=gdata.contacts.ProfileEntryFromString)
- def UpdateProfile(self, edit_uri, updated_profile, url_params=None,
- escape_params=True):
- """Updates an existing profile.
- Args:
- edit_uri: string The edit link URI for the element being updated
- updated_profile: string atom.Entry or subclass containing
- the Atom Entry which will replace the profile which is
- stored at the edit_url.
- url_params: dict (optional) Additional URL parameters to be included
- in the update request.
- escape_params: boolean (optional) If true, the url_params will be
- escaped before they are included in the request.
- Returns:
- On successful update, a httplib.HTTPResponse containing the server's
- response to the PUT request.
- On failure, raises a RequestError.
- """
- return self.Put(updated_profile, self._CleanUri(edit_uri),
- url_params=url_params, escape_params=escape_params,
- converter=gdata.contacts.ProfileEntryFromString)
- def ExecuteBatch(self, batch_feed, url,
- converter=gdata.contacts.ContactsFeedFromString):
- """Sends a batch request feed to the server.
-
- Args:
- batch_feed: gdata.contacts.ContactFeed A feed containing batch
- request entries. Each entry contains the operation to be performed
- on the data contained in the entry. For example an entry with an
- operation type of insert will be used as if the individual entry
- had been inserted.
- url: str The batch URL to which these operations should be applied.
- converter: Function (optional) The function used to convert the server's
- response to an object. The default value is ContactsFeedFromString.
-
- Returns:
- The results of the batch request's execution on the server. If the
- default converter is used, this is stored in a ContactsFeed.
- """
- return self.Post(batch_feed, url, converter=converter)
-
- def ExecuteBatchProfiles(self, batch_feed, url,
- converter=gdata.contacts.ProfilesFeedFromString):
- """Sends a batch request feed to the server.
- Args:
- batch_feed: gdata.profiles.ProfilesFeed A feed containing batch
- request entries. Each entry contains the operation to be performed
- on the data contained in the entry. For example an entry with an
- operation type of insert will be used as if the individual entry
- had been inserted.
- url: string The batch URL to which these operations should be applied.
- converter: Function (optional) The function used to convert the server's
- response to an object. The default value is
- gdata.profiles.ProfilesFeedFromString.
- Returns:
- The results of the batch request's execution on the server. If the
- default converter is used, this is stored in a ProfilesFeed.
- """
- return self.Post(batch_feed, url, converter=converter)
- def _CleanUri(self, uri):
- """Sanitizes a feed URI.
- Args:
- uri: The URI to sanitize, can be relative or absolute.
- Returns:
- The given URI without its http://server prefix, if any.
- Keeps the leading slash of the URI.
- """
- url_prefix = 'http://%s' % self.server
- if uri.startswith(url_prefix):
- uri = uri[len(url_prefix):]
- return uri
- class ContactsQuery(gdata.service.Query):
- def __init__(self, feed=None, text_query=None, params=None,
- categories=None, group=None):
- self.feed = feed or '/m8/feeds/contacts/default/full'
- if group:
- self._SetGroup(group)
- gdata.service.Query.__init__(self, feed=self.feed, text_query=text_query,
- params=params, categories=categories)
- def _GetGroup(self):
- if 'group' in self:
- return self['group']
- else:
- return None
- def _SetGroup(self, group_id):
- self['group'] = group_id
- group = property(_GetGroup, _SetGroup,
- doc='The group query parameter to find only contacts in this group')
- class GroupsQuery(gdata.service.Query):
- def __init__(self, feed=None, text_query=None, params=None,
- categories=None):
- self.feed = feed or '/m8/feeds/groups/default/full'
- gdata.service.Query.__init__(self, feed=self.feed, text_query=text_query,
- params=params, categories=categories)
- class ProfilesQuery(gdata.service.Query):
- """Constructs a query object for the profiles feed."""
- def __init__(self, feed=None, text_query=None, params=None,
- categories=None):
- self.feed = feed or '/m8/feeds/profiles/default/full'
- gdata.service.Query.__init__(self, feed=self.feed, text_query=text_query,
- params=params, categories=categories)