/usr/lib/python2.7/dist-packages/gdata/photos/service.py

#!/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
python-gdata 2.0.18+dfsg1-2 / usr / lib / python2.7 / dist-packages / gdata / photos / service.py
