428 lines
17 KiB
Python
428 lines
17 KiB
Python
|
#!/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)
|