blob: 23c5febc2a443497c150b578f8c50f26241aa089 [file] [log] [blame]
#!/usr/bin/env python
# -*-*- encoding: utf-8 -*-*-
#
# This is the service file for the Google Photo python client.
# It is used for higher level operations.
#
# $Id: service.py 144 2007-10-25 21:03:34Z havard.gulldahl $
#
# Copyright 2007 Håvard Gulldahl
#
# 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.
"""Google PhotoService provides a human-friendly interface to
Google Photo (a.k.a Picasa Web) services[1].
It extends gdata.service.GDataService and as such hides all the
nasty details about authenticating, parsing and communicating with
Google Photos.
[1]: http://code.google.com/apis/picasaweb/gdata.html
Example:
import gdata.photos, gdata.photos.service
pws = gdata.photos.service.PhotosService()
pws.ClientLogin(username, password)
#Get all albums
albums = pws.GetUserFeed().entry
# Get all photos in second album
photos = pws.GetFeed(albums[1].GetPhotosUri()).entry
# Get all tags for photos in second album and print them
tags = pws.GetFeed(albums[1].GetTagsUri()).entry
print [ tag.summary.text for tag in tags ]
# Get all comments for the first photos in list and print them
comments = pws.GetCommentFeed(photos[0].GetCommentsUri()).entry
print [ c.summary.text for c in comments ]
# Get a photo to work with
photo = photos[0]
# Update metadata
# Attributes from the <gphoto:*> namespace
photo.summary.text = u'A nice view from my veranda'
photo.title.text = u'Verandaview.jpg'
# Attributes from the <media:*> namespace
photo.media.keywords.text = u'Home, Long-exposure, Sunset' # Comma-separated
# Adding attributes to media object
# Rotate 90 degrees clockwise
photo.rotation = gdata.photos.Rotation(text='90')
# Submit modified photo object
photo = pws.UpdatePhotoMetadata(photo)
# Make sure you only modify the newly returned object, else you'll get
# versioning errors. See Optimistic-concurrency
# Add comment to a picture
comment = pws.InsertComment(photo, u'I wish the water always was this warm')
# Remove comment because it was silly
print "*blush*"
pws.Delete(comment.GetEditLink().href)
"""
__author__ = u'havard@gulldahl.no'# (Håvard Gulldahl)' #BUG: pydoc chokes on non-ascii chars in __author__
__license__ = 'Apache License v2'
__version__ = '$Revision: 176 $'[11:-2]
import sys, os.path, StringIO
import time
import gdata.service
import gdata
import atom.service
import atom
import gdata.photos
SUPPORTED_UPLOAD_TYPES = ('bmp', 'jpeg', 'jpg', 'gif', 'png')
UNKOWN_ERROR=1000
GPHOTOS_BAD_REQUEST=400
GPHOTOS_CONFLICT=409
GPHOTOS_INTERNAL_SERVER_ERROR=500
GPHOTOS_INVALID_ARGUMENT=601
GPHOTOS_INVALID_CONTENT_TYPE=602
GPHOTOS_NOT_AN_IMAGE=603
GPHOTOS_INVALID_KIND=604
class GooglePhotosException(Exception):
def __init__(self, response):
self.error_code = response['status']
self.reason = response['reason'].strip()
if '<html>' in str(response['body']): #general html message, discard it
response['body'] = ""
self.body = response['body'].strip()
self.message = "(%(status)s) %(body)s -- %(reason)s" % response
#return explicit error codes
error_map = { '(12) Not an image':GPHOTOS_NOT_AN_IMAGE,
'kind: That is not one of the acceptable values':
GPHOTOS_INVALID_KIND,
}
for msg, code in error_map.iteritems():
if self.body == msg:
self.error_code = code
break
self.args = [self.error_code, self.reason, self.body]
class PhotosService(gdata.service.GDataService):
ssl = True
userUri = '/data/feed/api/user/%s'
def __init__(self, email=None, password=None, source=None,
server='picasaweb.google.com', additional_headers=None,
**kwargs):
"""Creates a client for the Google Photos 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: 'picasaweb.google.com'.
**kwargs: The other parameters to pass to gdata.service.GDataService
constructor.
"""
self.email = email
self.client = source
gdata.service.GDataService.__init__(
self, email=email, password=password, service='lh2', source=source,
server=server, additional_headers=additional_headers, **kwargs)
def GetFeed(self, uri, limit=None, start_index=None):
"""Get a feed.
The results are ordered by the values of their `updated' elements,
with the most recently updated entry appearing first in the feed.
Arguments:
uri: the uri to fetch
limit (optional): the maximum number of entries to return. Defaults to what
the server returns.
Returns:
one of gdata.photos.AlbumFeed,
gdata.photos.UserFeed,
gdata.photos.PhotoFeed,
gdata.photos.CommentFeed,
gdata.photos.TagFeed,
depending on the results of the query.
Raises:
GooglePhotosException
See:
http://code.google.com/apis/picasaweb/gdata.html#Get_Album_Feed_Manual
"""
if limit is not None:
uri += '&max-results=%s' % limit
if start_index is not None:
uri += '&start-index=%s' % start_index
try:
return self.Get(uri, converter=gdata.photos.AnyFeedFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def GetEntry(self, uri, limit=None, start_index=None):
"""Get an Entry.
Arguments:
uri: the uri to the entry
limit (optional): the maximum number of entries to return. Defaults to what
the server returns.
Returns:
one of gdata.photos.AlbumEntry,
gdata.photos.UserEntry,
gdata.photos.PhotoEntry,
gdata.photos.CommentEntry,
gdata.photos.TagEntry,
depending on the results of the query.
Raises:
GooglePhotosException
"""
if limit is not None:
uri += '&max-results=%s' % limit
if start_index is not None:
uri += '&start-index=%s' % start_index
try:
return self.Get(uri, converter=gdata.photos.AnyEntryFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def GetUserFeed(self, kind='album', user='default', limit=None):
"""Get user-based feed, containing albums, photos, comments or tags;
defaults to albums.
The entries are ordered by the values of their `updated' elements,
with the most recently updated entry appearing first in the feed.
Arguments:
kind: the kind of entries to get, either `album', `photo',
`comment' or `tag', or a python list of these. Defaults to `album'.
user (optional): whose albums we're querying. Defaults to current user.
limit (optional): the maximum number of entries to return.
Defaults to everything the server returns.
Returns:
gdata.photos.UserFeed, containing appropriate Entry elements
See:
http://code.google.com/apis/picasaweb/gdata.html#Get_Album_Feed_Manual
http://googledataapis.blogspot.com/2007/07/picasa-web-albums-adds-new-api-features.html
"""
if isinstance(kind, (list, tuple) ):
kind = ",".join(kind)
uri = '/data/feed/api/user/%s?kind=%s' % (user, kind)
return self.GetFeed(uri, limit=limit)
def GetTaggedPhotos(self, tag, user='default', limit=None):
"""Get all photos belonging to a specific user, tagged by the given keyword
Arguments:
tag: The tag you're looking for, e.g. `dog'
user (optional): Whose images/videos you want to search, defaults
to current user
limit (optional): the maximum number of entries to return.
Defaults to everything the server returns.
Returns:
gdata.photos.UserFeed containing PhotoEntry elements
"""
# Lower-casing because of
# http://code.google.com/p/gdata-issues/issues/detail?id=194
uri = '/data/feed/api/user/%s?kind=photo&tag=%s' % (user, tag.lower())
return self.GetFeed(uri, limit)
def SearchUserPhotos(self, query, user='default', limit=100):
"""Search through all photos for a specific user and return a feed.
This will look for matches in file names and image tags (a.k.a. keywords)
Arguments:
query: The string you're looking for, e.g. `vacation'
user (optional): The username of whose photos you want to search, defaults
to current user.
limit (optional): Don't return more than `limit' hits, defaults to 100
Only public photos are searched, unless you are authenticated and
searching through your own photos.
Returns:
gdata.photos.UserFeed with PhotoEntry elements
"""
uri = '/data/feed/api/user/%s?kind=photo&q=%s' % (user, query)
return self.GetFeed(uri, limit=limit)
def SearchCommunityPhotos(self, query, limit=100):
"""Search through all public photos and return a feed.
This will look for matches in file names and image tags (a.k.a. keywords)
Arguments:
query: The string you're looking for, e.g. `vacation'
limit (optional): Don't return more than `limit' hits, defaults to 100
Returns:
gdata.GDataFeed with PhotoEntry elements
"""
uri='/data/feed/api/all?q=%s' % query
return self.GetFeed(uri, limit=limit)
def GetContacts(self, user='default', limit=None):
"""Retrieve a feed that contains a list of your contacts
Arguments:
user: Username of the user whose contacts you want
Returns
gdata.photos.UserFeed, with UserEntry entries
See:
http://groups.google.com/group/Google-Picasa-Data-API/msg/819b0025b5ff5e38
"""
uri = '/data/feed/api/user/%s/contacts?kind=user' % user
return self.GetFeed(uri, limit=limit)
def SearchContactsPhotos(self, user='default', search=None, limit=None):
"""Search over your contacts' photos and return a feed
Arguments:
user: Username of the user whose contacts you want
search (optional): What to search for (photo title, description and keywords)
Returns
gdata.photos.UserFeed, with PhotoEntry elements
See:
http://groups.google.com/group/Google-Picasa-Data-API/msg/819b0025b5ff5e38
"""
uri = '/data/feed/api/user/%s/contacts?kind=photo&q=%s' % (user, search)
return self.GetFeed(uri, limit=limit)
def InsertAlbum(self, title, summary, location=None, access='public',
commenting_enabled='true', timestamp=None):
"""Add an album.
Needs authentication, see self.ClientLogin()
Arguments:
title: Album title
summary: Album summary / description
access (optional): `private' or `public'. Public albums are searchable
by everyone on the internet. Defaults to `public'
commenting_enabled (optional): `true' or `false'. Defaults to `true'.
timestamp (optional): A date and time for the album, in milliseconds since
Unix epoch[1] UTC. Defaults to now.
Returns:
The newly created gdata.photos.AlbumEntry
See:
http://code.google.com/apis/picasaweb/gdata.html#Add_Album_Manual_Installed
[1]: http://en.wikipedia.org/wiki/Unix_epoch
"""
album = gdata.photos.AlbumEntry()
album.title = atom.Title(text=title, title_type='text')
album.summary = atom.Summary(text=summary, summary_type='text')
if location is not None:
album.location = gdata.photos.Location(text=location)
album.access = gdata.photos.Access(text=access)
if commenting_enabled in ('true', 'false'):
album.commentingEnabled = gdata.photos.CommentingEnabled(text=commenting_enabled)
if timestamp is None:
timestamp = '%i' % int(time.time() * 1000)
album.timestamp = gdata.photos.Timestamp(text=timestamp)
try:
return self.Post(album, uri=self.userUri % self.email,
converter=gdata.photos.AlbumEntryFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def InsertPhoto(self, album_or_uri, photo, filename_or_handle,
content_type='image/jpeg'):
"""Add a PhotoEntry
Needs authentication, see self.ClientLogin()
Arguments:
album_or_uri: AlbumFeed or uri of the album where the photo should go
photo: PhotoEntry to add
filename_or_handle: A file-like object or file name where the image/video
will be read from
content_type (optional): Internet media type (a.k.a. mime type) of
media object. Currently Google Photos supports these types:
o image/bmp
o image/gif
o image/jpeg
o image/png
Images will be converted to jpeg on upload. Defaults to `image/jpeg'
"""
try:
assert(isinstance(photo, gdata.photos.PhotoEntry))
except AssertionError:
raise GooglePhotosException({'status':GPHOTOS_INVALID_ARGUMENT,
'body':'`photo` must be a gdata.photos.PhotoEntry instance',
'reason':'Found %s, not PhotoEntry' % type(photo)
})
try:
majtype, mintype = content_type.split('/')
assert(mintype in SUPPORTED_UPLOAD_TYPES)
except (ValueError, AssertionError):
raise GooglePhotosException({'status':GPHOTOS_INVALID_CONTENT_TYPE,
'body':'This is not a valid content type: %s' % content_type,
'reason':'Accepted content types: %s' % \
['image/'+t for t in SUPPORTED_UPLOAD_TYPES]
})
if isinstance(filename_or_handle, (str, unicode)) and \
os.path.exists(filename_or_handle): # it's a file name
mediasource = gdata.MediaSource()
mediasource.setFile(filename_or_handle, content_type)
elif hasattr(filename_or_handle, 'read'):# it's a file-like resource
if hasattr(filename_or_handle, 'seek'):
filename_or_handle.seek(0) # rewind pointer to the start of the file
# gdata.MediaSource needs the content length, so read the whole image
file_handle = StringIO.StringIO(filename_or_handle.read())
name = 'image'
if hasattr(filename_or_handle, 'name'):
name = filename_or_handle.name
mediasource = gdata.MediaSource(file_handle, content_type,
content_length=file_handle.len, file_name=name)
else: #filename_or_handle is not valid
raise GooglePhotosException({'status':GPHOTOS_INVALID_ARGUMENT,
'body':'`filename_or_handle` must be a path name or a file-like object',
'reason':'Found %s, not path name or object with a .read() method' % \
filename_or_handle
})
if isinstance(album_or_uri, (str, unicode)): # it's a uri
feed_uri = album_or_uri
elif hasattr(album_or_uri, 'GetFeedLink'): # it's a AlbumFeed object
feed_uri = album_or_uri.GetFeedLink().href
try:
return self.Post(photo, uri=feed_uri, media_source=mediasource,
converter=gdata.photos.PhotoEntryFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def InsertPhotoSimple(self, album_or_uri, title, summary, filename_or_handle,
content_type='image/jpeg', keywords=None):
"""Add a photo without constructing a PhotoEntry.
Needs authentication, see self.ClientLogin()
Arguments:
album_or_uri: AlbumFeed or uri of the album where the photo should go
title: Photo title
summary: Photo summary / description
filename_or_handle: A file-like object or file name where the image/video
will be read from
content_type (optional): Internet media type (a.k.a. mime type) of
media object. Currently Google Photos supports these types:
o image/bmp
o image/gif
o image/jpeg
o image/png
Images will be converted to jpeg on upload. Defaults to `image/jpeg'
keywords (optional): a 1) comma separated string or 2) a python list() of
keywords (a.k.a. tags) to add to the image.
E.g. 1) `dog, vacation, happy' 2) ['dog', 'happy', 'vacation']
Returns:
The newly created gdata.photos.PhotoEntry or GooglePhotosException on errors
See:
http://code.google.com/apis/picasaweb/gdata.html#Add_Album_Manual_Installed
[1]: http://en.wikipedia.org/wiki/Unix_epoch
"""
metadata = gdata.photos.PhotoEntry()
metadata.title=atom.Title(text=title)
metadata.summary = atom.Summary(text=summary, summary_type='text')
if keywords is not None:
if isinstance(keywords, list):
keywords = ','.join(keywords)
metadata.media.keywords = gdata.media.Keywords(text=keywords)
return self.InsertPhoto(album_or_uri, metadata, filename_or_handle,
content_type)
def UpdatePhotoMetadata(self, photo):
"""Update a photo's metadata.
Needs authentication, see self.ClientLogin()
You can update any or all of the following metadata properties:
* <title>
* <media:description>
* <gphoto:checksum>
* <gphoto:client>
* <gphoto:rotation>
* <gphoto:timestamp>
* <gphoto:commentingEnabled>
Arguments:
photo: a gdata.photos.PhotoEntry object with updated elements
Returns:
The modified gdata.photos.PhotoEntry
Example:
p = GetFeed(uri).entry[0]
p.title.text = u'My new text'
p.commentingEnabled.text = 'false'
p = UpdatePhotoMetadata(p)
It is important that you don't keep the old object around, once
it has been updated. See
http://code.google.com/apis/gdata/reference.html#Optimistic-concurrency
"""
try:
return self.Put(data=photo, uri=photo.GetEditLink().href,
converter=gdata.photos.PhotoEntryFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def UpdatePhotoBlob(self, photo_or_uri, filename_or_handle,
content_type = 'image/jpeg'):
"""Update a photo's binary data.
Needs authentication, see self.ClientLogin()
Arguments:
photo_or_uri: a gdata.photos.PhotoEntry that will be updated, or a
`edit-media' uri pointing to it
filename_or_handle: A file-like object or file name where the image/video
will be read from
content_type (optional): Internet media type (a.k.a. mime type) of
media object. Currently Google Photos supports these types:
o image/bmp
o image/gif
o image/jpeg
o image/png
Images will be converted to jpeg on upload. Defaults to `image/jpeg'
Returns:
The modified gdata.photos.PhotoEntry
Example:
p = GetFeed(PhotoUri)
p = UpdatePhotoBlob(p, '/tmp/newPic.jpg')
It is important that you don't keep the old object around, once
it has been updated. See
http://code.google.com/apis/gdata/reference.html#Optimistic-concurrency
"""
try:
majtype, mintype = content_type.split('/')
assert(mintype in SUPPORTED_UPLOAD_TYPES)
except (ValueError, AssertionError):
raise GooglePhotosException({'status':GPHOTOS_INVALID_CONTENT_TYPE,
'body':'This is not a valid content type: %s' % content_type,
'reason':'Accepted content types: %s' % \
['image/'+t for t in SUPPORTED_UPLOAD_TYPES]
})
if isinstance(filename_or_handle, (str, unicode)) and \
os.path.exists(filename_or_handle): # it's a file name
photoblob = gdata.MediaSource()
photoblob.setFile(filename_or_handle, content_type)
elif hasattr(filename_or_handle, 'read'):# it's a file-like resource
if hasattr(filename_or_handle, 'seek'):
filename_or_handle.seek(0) # rewind pointer to the start of the file
# gdata.MediaSource needs the content length, so read the whole image
file_handle = StringIO.StringIO(filename_or_handle.read())
name = 'image'
if hasattr(filename_or_handle, 'name'):
name = filename_or_handle.name
mediasource = gdata.MediaSource(file_handle, content_type,
content_length=file_handle.len, file_name=name)
else: #filename_or_handle is not valid
raise GooglePhotosException({'status':GPHOTOS_INVALID_ARGUMENT,
'body':'`filename_or_handle` must be a path name or a file-like object',
'reason':'Found %s, not path name or an object with .read() method' % \
type(filename_or_handle)
})
if isinstance(photo_or_uri, (str, unicode)):
entry_uri = photo_or_uri # it's a uri
elif hasattr(photo_or_uri, 'GetEditMediaLink'):
entry_uri = photo_or_uri.GetEditMediaLink().href
try:
return self.Put(photoblob, entry_uri,
converter=gdata.photos.PhotoEntryFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def InsertTag(self, photo_or_uri, tag):
"""Add a tag (a.k.a. keyword) to a photo.
Needs authentication, see self.ClientLogin()
Arguments:
photo_or_uri: a gdata.photos.PhotoEntry that will be tagged, or a
`post' uri pointing to it
(string) tag: The tag/keyword
Returns:
The new gdata.photos.TagEntry
Example:
p = GetFeed(PhotoUri)
tag = InsertTag(p, 'Beautiful sunsets')
"""
tag = gdata.photos.TagEntry(title=atom.Title(text=tag))
if isinstance(photo_or_uri, (str, unicode)):
post_uri = photo_or_uri # it's a uri
elif hasattr(photo_or_uri, 'GetEditMediaLink'):
post_uri = photo_or_uri.GetPostLink().href
try:
return self.Post(data=tag, uri=post_uri,
converter=gdata.photos.TagEntryFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def InsertComment(self, photo_or_uri, comment):
"""Add a comment to a photo.
Needs authentication, see self.ClientLogin()
Arguments:
photo_or_uri: a gdata.photos.PhotoEntry that is about to be commented
, or a `post' uri pointing to it
(string) comment: The actual comment
Returns:
The new gdata.photos.CommentEntry
Example:
p = GetFeed(PhotoUri)
tag = InsertComment(p, 'OOOH! I would have loved to be there.
Who's that in the back?')
"""
comment = gdata.photos.CommentEntry(content=atom.Content(text=comment))
if isinstance(photo_or_uri, (str, unicode)):
post_uri = photo_or_uri # it's a uri
elif hasattr(photo_or_uri, 'GetEditMediaLink'):
post_uri = photo_or_uri.GetPostLink().href
try:
return self.Post(data=comment, uri=post_uri,
converter=gdata.photos.CommentEntryFromString)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def Delete(self, object_or_uri, *args, **kwargs):
"""Delete an object.
Re-implementing the GDataService.Delete method, to add some
convenience.
Arguments:
object_or_uri: Any object that has a GetEditLink() method that
returns a link, or a uri to that object.
Returns:
? or GooglePhotosException on errors
"""
try:
uri = object_or_uri.GetEditLink().href
except AttributeError:
uri = object_or_uri
try:
return gdata.service.GDataService.Delete(self, uri, *args, **kwargs)
except gdata.service.RequestError, e:
raise GooglePhotosException(e.args[0])
def GetSmallestThumbnail(media_thumbnail_list):
"""Helper function to get the smallest thumbnail of a list of
gdata.media.Thumbnail.
Returns gdata.media.Thumbnail """
r = {}
for thumb in media_thumbnail_list:
r[int(thumb.width)*int(thumb.height)] = thumb
keys = r.keys()
keys.sort()
return r[keys[0]]
def ConvertAtomTimestampToEpoch(timestamp):
"""Helper function to convert a timestamp string, for instance
from atom:updated or atom:published, to milliseconds since Unix epoch
(a.k.a. POSIX time).
`2007-07-22T00:45:10.000Z' -> """
return time.mktime(time.strptime(timestamp, '%Y-%m-%dT%H:%M:%S.000Z'))
## TODO: Timezone aware