neves-ruby_picasa 0.2.3

data/lib/ruby_picasa.rb

@@ -0,0 +1,397 @@
+require 'objectify_xml'
+require 'objectify_xml/atom'
+require 'cgi'
+require 'net/http'
+require 'net/https'
+require File.join(File.dirname(__FILE__), 'ruby_picasa/types')
+
+module RubyPicasa
+  VERSION = '0.2.3'
+
+  class PicasaError < StandardError
+  end
+
+  class PicasaTokenError < PicasaError
+  end
+end
+
+# == Authorization
+#
+# RubyPicasa makes authorizing a Rails app easy. It is a two step process: 
+#
+# First redirect the user to the authorization url, if the user authorizes your
+# application, Picasa will redirect the user back to the url you specify (in
+# this case authorize_picasa_url). 
+#
+# Next, pass the Rails request object to the authorize_token method which will
+# make the api call to upgrade the token and if successful return an initialized
+# Picasa session object ready to use. The token object can be retrieved from the
+# token attribute.
+#
+#   class PicasaController < ApplicationController
+#     def request_authorization
+#       redirect_to Picasa.authorization_url(authorize_picasa_url)
+#     end
+#
+#     def authorize
+#       if Picasa.token_in_request?(request)
+#         begin
+#           picasa = Picasa.authorize_request(request)
+#           current_user.picasa_token = picasa.token
+#           current_user.save
+#           flash[:notice] = 'Picasa authorization complete'
+#           redirect_to picasa_path
+#         rescue PicasaTokenError => e
+#           # 
+#           @error = e.message
+#           render
+#         end
+#       end
+#     end
+#   end
+#
+class Picasa
+  class << self
+    # The user must be redirected to this address to authorize the application
+    # to access their Picasa account. The token_from_request and
+    # authorize_request methods can be used to handle the resulting redirect
+    # from Picasa.
+    def authorization_url(return_to_url, request_session = true, secure = false, authsub_url = nil)
+      session = request_session ? '1' : '0'
+      secure = secure ? '1' : '0'
+      return_to_url = CGI.escape(return_to_url)
+      url = authsub_url || 'http://www.google.com/accounts/AuthSubRequest'
+      "#{ url }?scope=http%3A%2F%2F#{ host }%2Fdata%2F&session=#{ session }&secure=#{ secure }&next=#{ return_to_url }"
+    end
+
+    # Takes a Rails request object and extracts the token from it. This would
+    # happen in the action that is pointed to by the return_to_url argument
+    # when the authorization_url is created.
+    def token_from_request(request)
+      if token = request.parameters['token']
+        return token
+      else
+        raise RubyPicasa::PicasaTokenError, 'No Picasa authorization token was found.'
+      end
+    end
+
+    def token_in_request?(request)
+      request.parameters['token']
+    end
+
+    # Takes a Rails request object as in token_from_request, then makes the
+    # token authorization request to produce the permanent token. This will
+    # only work if request_session was true when you created the
+    # authorization_url.
+    def authorize_request(request)
+      p = Picasa.new(token_from_request(request))
+      p.authorize_token!
+      p
+    end
+
+    # The url to make requests to without the protocol or path.
+    def host
+      @host ||= 'picasaweb.google.com'
+    end
+
+    # In the unlikely event that you need to access this api on a different url,
+    # you can set it here. It defaults to picasaweb.google.com
+    def host=(h)
+      @host = h
+    end
+
+    # A simple test used to determine if a given resource id is it's full
+    # identifier url. This is not intended to be a general purpose method as the
+    # test is just a check for the http/https protocol prefix.
+    def is_url?(path)
+      path.to_s =~ %r{\Ahttps?://}
+    end
+
+    # For more on possible options and their meanings, see: 
+    # http://code.google.com/apis/picasaweb/reference.html
+    #
+    # The following values are valid for the thumbsize and imgmax query
+    # parameters and are embeddable on a webpage. These images are available as
+    # both cropped(c) and uncropped(u) sizes by appending c or u to the size.
+    # As an example, to retrieve a 72 pixel image that is cropped, you would
+    # specify 72c, while to retrieve the uncropped image, you would specify 72u
+    # for the thumbsize or imgmax query parameter values.
+    #
+    # 32, 48, 64, 72, 144, 160
+    #
+    # The following values are valid for the thumbsize and imgmax query
+    # parameters and are embeddable on a webpage. These images are available as
+    # only uncropped(u) sizes by appending u to the size or just passing the
+    # size value without appending anything. 
+    #
+    # 200, 288, 320, 400, 512, 576, 640, 720, 800
+    #
+    # The following values are valid for the thumbsize and imgmax query
+    # parameters and are not embeddable on a webpage. These image sizes are
+    # only available in uncropped format and are accessed using only the size
+    # (no u is appended to the size).
+    #
+    # 912, 1024, 1152, 1280, 1440, 1600
+    # 
+    def path(args = {})
+      path, options = parse_url(args)
+      if path.nil?
+        path = ["/data/feed/api"]
+        if args[:user_id] == 'all'
+          path += ["all"]
+        else
+          path += ["user", CGI.escape(args[:user_id] || 'default')]
+        end
+        path += ['albumid', CGI.escape(args[:album_id])] if args[:album_id]
+        path += ['album', CGI.escape(args[:album])] if args[:album]
+        path = path.join('/')
+      end
+      options['kind'] = 'photo' if args[:recent_photos] or args[:album_id] or args[:album]
+      if args[:thumbsize] and not args[:thumbsize].split(/,/).all? { |s| RubyPicasa::Photo::VALID.include?(s) }
+        raise RubyPicasa::PicasaError, 'Invalid thumbsize.'
+      end
+      if args[:imgmax] and not RubyPicasa::Photo::VALID.include?(args[:imgmax])
+        raise RubyPicasa::PicasaError, 'Invalid imgmax.'
+      end
+      [:max_results, :start_index, :tag, :q, :kind,
+       :access, :thumbsize, :imgmax, :bbox, :l].each do |arg|
+        options[arg.to_s.dasherize] = args[arg] if args[arg]
+      end
+      if options.empty?
+        path
+      else
+        [path, options.map { |k, v| [k.to_s, CGI.escape(v.to_s)].join('=') }.join('&')].join('?')
+      end
+    end
+
+    # builder helper for creating a public RubyPicasa::User
+    def public_user(user_id, options = {})
+        Picasa.new.user(user_id, options)
+    end
+
+    # builder helper for creating a public RubyPicasa::Album using an album_id
+    def public_album_by_id(user_id, album_id, options = {})
+        options[:user_id] = user_id
+        Picasa.new.album(album_id, options)
+    end
+
+    # builder helper for creating a public RubyPicasa::Album using an album_name
+    def public_album_by_name(user_id, album_name, options = {})
+        options[:user_id] = user_id
+        Picasa.new.album_by_name(album_name, options)
+    end
+
+    private
+
+    # Extract the path and a hash of key/value pairs from a given url with
+    # optional query string.
+    def parse_url(args)
+      url = args[:url]
+      url ||= args[:user_id] if is_url?(args[:user_id]) 
+      url ||= args[:album_id] if is_url?(args[:album_id])
+      if url
+        uri = URI.parse(url)
+        path = uri.path
+        options = {}
+        if uri.query
+          uri.query.split('&').each do |query|
+            k, v = query.split('=')
+            options[k] = CGI.unescape(v)
+          end
+        end
+        [path, options]
+      else
+        [nil, {}]
+      end
+    end
+  end
+
+  # The AuthSub token currently in use.
+  attr_reader :token
+
+  def initialize(token = nil)
+    @token = token
+    @request_cache = {}
+  end
+
+  # Attempt to upgrade the current AuthSub token to a permanent one. This only
+  # works if the Picasa session is initialized with a single use token.
+  def authorize_token!
+    http = Net::HTTP.new("www.google.com", 443)
+    http.use_ssl = true
+    response = http.get('/accounts/accounts/AuthSubSessionToken', auth_header)
+    token = response.body.scan(/Token=(.*)/).flatten.compact.first
+    if token
+      @token = token
+    else
+      raise RubyPicasa::PicasaTokenError, 'The request to upgrade to a session token failed.'
+    end
+    @token
+  end
+
+  # Retrieve a RubyPicasa::User record including all user albums.
+  def user(user_id_or_url = nil, options = {})
+    options = make_options(:user_id, user_id_or_url, options)
+    get(options)
+  end
+
+  # Retrieve a RubyPicasa::Album record. If you pass an id or a feed url it will
+  # include all photos. If you pass an entry url, it will not include photos.
+  def album(album_id_or_url, options = {})
+    options = make_options(:album_id, album_id_or_url, options)
+    get(options)
+  end
+
+  # Retrieve a RubyPicasa::Album record by using the album name
+  def album_by_name(album_name, options = {})
+    options = make_options(:album, album_name, options)
+    get(options)
+  end
+
+  # This request does not require authentication. Returns a RubyPicasa::Search
+  # object containing the first 10 matches. You can call #next and #previous to
+  # navigate the paginated results on the Search object.
+  def search(q, options = {})
+    h = {}
+    h[:max_results] = 10
+    h[:user_id] = 'all'
+    h[:kind] = 'photo'
+    # merge options over h, but merge q over options
+    get(h.merge(options).merge(:q => q))
+  end
+
+  # Retrieve a RubyPicasa object determined by the type of xml results returned
+  # by Picasa. Any supported type of RubyPicasa resource can be requested with
+  # this method.
+  def get_url(url, options = {})
+    options = make_options(:url, url, options)
+    get(options)
+  end
+
+  # Retrieve a RubyPicasa::RecentPhotos object, essentially a User object which
+  # contains photos instead of albums.
+  def recent_photos(user_id_or_url, options = {})
+    options = make_options(:user_id, user_id_or_url, options)
+    options[:recent_photos] = true
+    get(options)
+  end
+
+  # Retrieves the user's albums and finds the first one with a matching title.
+  # Returns a RubyPicasa::Album object.
+  def album_by_title(title, options = {})
+    if a = user.albums.find { |a| title === a.title }
+      a.load options
+    end
+  end
+
+  # Returns the raw xml from Picasa. See the Picasa.path method for valid
+  # options.
+  def xml(options = {})
+    http = Net::HTTP.new(Picasa.host, 80)
+    path = Picasa.path(options)
+    response = http.get(path, auth_header)
+    if response.code =~ /20[01]/
+      response.body
+    end
+  end
+
+  private
+
+  # If the value parameter is a hash, treat it as the options hash, otherwise
+  # insert the value into the hash with the key specified.
+  #
+  # Uses merge to ensure that a new hash object is returned to prevent caller's
+  # has from accidentally being modified.
+  def make_options(key, value, options)
+    if value.is_a? Hash
+      {}.merge value
+    else
+      options ||= {}
+      options.merge(key => value)
+    end
+  end
+
+  # Combines the cached xml request with the class_from_xml factory. See the
+  # Picasa.path method for valid options.
+  def get(options = {})
+    with_cache(options) do |xml|
+      class_from_xml(xml)
+    end
+  end
+
+  # Returns the header data needed to make AuthSub requests.
+  def auth_header
+    if token
+      { "Authorization" => %{AuthSub token="#{ token }"} }
+    else
+      {}
+    end
+  end
+
+  # Caches the raw xml returned from the API. Keyed on request url.
+  def with_cache(options)
+    path = Picasa.path(options)
+    @request_cache.delete(path) if options[:reload]
+    xml = nil
+    if @request_cache.has_key? path
+      xml = @request_cache[path]
+    else
+      xml = @request_cache[path] = xml(options)
+    end
+    if xml
+      yield xml
+    end
+  end
+
+  # Returns the first xml element in the document (see
+  # Objectify::Xml.first_element) with the xml data types of the feed and first entry
+  # element in the document, used to determine which RubyPicasa object should
+  # be initialized to handle the data.
+  def xml_data(xml)
+    if xml = Objectify::Xml.first_element(xml)
+      # There is something wrong with Nokogiri xpath/css search with
+      # namespaces. If you are searching a document that has namespaces,
+      # it's impossible to match any elements in the root xmlns namespace.
+      # Matching just on attributes works though.
+      feed, entry = xml.search('//*[@term][@scheme]', xml.namespaces)
+      feed_scheme = feed['term'] if feed
+      entry_scheme = entry['term'] if entry
+      [xml, feed_scheme, entry_scheme]
+    end
+  end
+
+  # Initialize the correct RubyPicasa object depending on the type of feed and
+  # entries in the document.
+  def class_from_xml(xml)
+    xml, feed_scheme, entry_scheme = xml_data(xml)
+    if xml
+      r = case feed_scheme
+      when /#user$/
+        case entry_scheme
+        when /#album$/
+          RubyPicasa::User.new(xml, self)
+        when /#photo$/
+          RubyPicasa::RecentPhotos.new(xml, self)
+        end
+      when /#album$/
+        case entry_scheme
+        when nil, /#photo$/
+          RubyPicasa::Album.new(xml, self)
+        end
+      when /#photo$/
+        case entry_scheme
+        when /#photo$/
+          RubyPicasa::Search.new(xml, self)
+        when nil
+          RubyPicasa::Photo.new(xml, self)
+        end
+      end
+      if r
+        r.session = self
+        r
+      else
+        raise RubyPicasa::PicasaError, "Unknown feed type\n feed:  #{ feed_scheme }\n entry: #{ entry_scheme }"
+      end
+    end
+  end
+end

data/spec/ruby_picasa/types_spec.rb

@@ -0,0 +1,303 @@
+require File.join(File.dirname(__FILE__), '../spec_helper')
+
+include RubyPicasa
+
+describe 'a RubyPicasa document', :shared => true do
+  it 'should have a feed_id' do
+    @object.feed_id.should_not be_nil
+  end
+
+  it 'should have an author' do
+    unless @no_author
+      @object.author.should_not be_nil
+      @object.author.name.should == 'Liz'
+      @object.author.uri.should == 'http://picasaweb.google.com/liz'
+    end
+  end
+
+  it 'should get links by name' do
+    @object.link('abc').should be_nil
+    @object.link('self').href.should_not be_nil
+  end
+
+  it 'should do nothing for previous and next' do
+    @object.previous.should be_nil if @object.link('previous').nil?
+    @object.next.should be_nil if @object.link('next').nil?
+  end
+
+  it 'should get the feed' do
+    @object.session.expects(:get_url).with(@object.feed_id.
+                                            gsub(/entry/, 'feed').
+                                            gsub(/default/, 'liz'), {})
+    @object.feed
+  end
+
+  it 'should have links' do
+    @object.links.should_not be_empty
+    @object.links.each do |l|
+      l.should be_an_instance_of(Objectify::Atom::Link)
+    end
+  end
+
+  describe 'session' do
+    it 'should return @session' do
+      @object.session = :sess
+      @object.session.should == :sess
+    end
+
+    it 'should get the parent session' do
+      @object.session = nil
+      @parent.expects(:session).returns(:parent_sess)
+      @object.session.should == :parent_sess
+    end
+
+    it 'should be nil if no parent' do
+      @object.session = nil
+      @object.expects(:parent).returns nil
+      @object.session.should be_nil
+    end
+  end
+end
+
+
+describe User do
+  it_should_behave_like 'a RubyPicasa document'
+
+  before :all do
+    @xml = open_file('user.atom').read
+  end
+
+  before do
+    @parent = mock('parent')
+    @object = @user = User.new(@xml, @parent)
+    @user.session = mock('session')
+  end
+
+  it 'should have albums' do
+    @user.albums.length.should == 1
+    @user.albums.first.should be_an_instance_of(Album)
+  end
+end
+
+describe RecentPhotos do
+  it_should_behave_like 'a RubyPicasa document'
+
+  before :all do
+    @xml = open_file('recent.atom').read
+  end
+
+  before do
+    @parent = mock('parent')
+    @object = @album = RecentPhotos.new(@xml, @parent)
+    @album.session = mock('session')
+  end
+
+  it 'should have 1 photo' do
+    @album.photos.length.should == 1
+    @album.photos.first.should be_an_instance_of(Photo)
+  end
+
+  it 'should request next' do
+    @album.session.expects(:get_url).with('http://picasaweb.google.com/data/feed/api/user/liz?start-index=2&max-results=1&kind=photo').returns(:result)
+    @album.next.should == :result
+  end
+
+  it 'should not request previous on first page' do
+    @album.session.expects(:get_url).never
+    @album.previous.should be_nil
+  end
+end
+
+describe Album do
+  it_should_behave_like 'a RubyPicasa document'
+
+  before :all do
+    @xml = open_file('album.atom').read
+  end
+
+  before do
+    @parent = mock('parent')
+    @object = @album = Album.new(@xml, @parent)
+    @album.session = mock('session')
+  end
+
+  it 'should have a numeric id' do
+    @object.id.should_not be_nil
+    @object.id.to_s.should match(/\A\d+\Z/)
+  end
+
+  it 'should have 1 entry' do
+    @album.entries.length.should == 1
+  end
+
+  it 'should get links by name' do
+    @album.link('abc').should be_nil
+    @album.link('alternate').href.should == 'http://picasaweb.google.com/liz/Lolcats'
+  end
+
+  describe 'photos' do
+    it 'should use entries if available' do
+      @album.expects(:session).never
+      @album.photos.should == @album.entries
+    end
+
+    it 'should request photos if needed' do
+      @album.entries = []
+      new_album = mock('album', :entries => [:photo])
+      @album.session.expects(:get_url).with(@album.link(/feed/).href, {}).returns(new_album)
+      @album.photos.should == [:photo]
+    end
+
+    it 'should not request photos twice if there are none' do
+      @album.entries = []
+      new_album = mock('album', :entries => [])
+      @album.session.expects(:get_url).with(@album.link(/feed/).href, {}).times(1).returns(new_album)
+      @album.photos.should == []
+      # note that mocks are set to accept only one get_url request
+      @album.photos.should == []
+    end
+
+    it 'should not request photos if there is no session' do
+      @album.entries = []
+      @album.expects(:session).returns(nil)
+      @album.photos.should == []
+    end
+  end
+
+  it 'should be public' do
+    @album.public?.should be_true
+  end
+
+  it 'should not be private' do
+    @album.private?.should be_false
+  end
+
+  describe 'first Photo' do
+    before do
+      @photo = @album.entries.first
+      @photo.should be_an_instance_of(Photo)
+    end
+
+    it 'should have a parent' do
+      @photo.parent.should == @album
+    end
+
+    it 'should not have an author' do
+      @photo.author.should be_nil
+    end
+
+    it 'should have a content' do
+      @photo.content.should be_an_instance_of(PhotoUrl)
+    end
+
+    it 'should have 3 thumbnails' do
+      @photo.thumbnails.length.should == 3
+      @photo.thumbnails.each do |t|
+        t.should be_an_instance_of(ThumbnailUrl)
+      end
+    end
+
+    it 'should have a numeric id' do
+      @object.id.should_not be_nil
+      @object.id.to_s.should match(/\A\d+\Z/)
+    end
+
+    it 'should have a default url' do
+      @photo.url.should == 'http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/invisible_bike.jpg'
+    end
+
+    it 'should have thumbnail urls' do
+      @photo.url('72').should == 'http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/s72/invisible_bike.jpg'
+    end
+
+    it 'should have a default url with options true' do
+      @photo.url(nil, true).should == [
+        'http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/invisible_bike.jpg',
+        { :width => 410, :height => 295 }
+      ]
+    end
+
+    it 'should have a default url with options' do
+      @photo.url(nil, :id => 'p').should == [
+        'http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/invisible_bike.jpg',
+        { :width => 410, :height => 295, :id => 'p' }
+      ]
+    end
+
+    it 'should have a default url with options first' do
+      @photo.url(:id => 'p').should == [
+        'http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/invisible_bike.jpg',
+        { :width => 410, :height => 295, :id => 'p' }
+      ]
+    end
+
+    it 'should have thumbnail urls with options' do
+      @photo.url('72', {:class => 'x'}).should == [
+        'http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/s72/invisible_bike.jpg',
+        { :width => 72, :height => 52, :class => 'x' }
+      ]
+    end
+
+    it 'should have thumbnail info' do
+      @photo.thumbnail('72').width.should == 72
+    end
+
+    it 'should retrieve valid thumbnail info' do
+      photo = mock('photo')
+      thumb = mock('thumb')
+      photo.expects(:thumbnails).returns([thumb])
+      @photo.session.expects(:get_url).with('http://picasaweb.google.com/data/feed/api/user/liz/albumid/5228155363249705041/photoid/5234820919508560306',
+                                      {:thumbsize => '32c'}).returns(photo)
+      @photo.thumbnail('32c').should == thumb
+    end
+
+    it 'should retrieve valid thumbnail info and handle not found' do
+      @photo.session.expects(:get_url).with('http://picasaweb.google.com/data/feed/api/user/liz/albumid/5228155363249705041/photoid/5234820919508560306',
+                                      {:thumbsize => '32c'}).returns(nil)
+      @photo.thumbnail('32c').should be_nil
+    end
+
+    it 'should convert the thumbnail url into another size without crop' do
+        @photo.tb(160).should == "http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/s160/invisible_bike.jpg"
+    end
+    
+    it 'should convert the thumbnail url into another size with crop' do
+        @photo.tb(160, true).should == "http://lh5.ggpht.com/liz/SKXR5BoXabI/AAAAAAAAAzs/tJQefyM4mFw/s160-c/invisible_bike.jpg"
+    end
+  end
+end
+
+describe Search do
+  it_should_behave_like 'a RubyPicasa document'
+
+  before :all do
+    @xml = open_file('search.atom').read
+  end
+
+  before do
+    @no_author = true
+    @parent = mock('parent')
+    @object = @search = Search.new(@xml, @parent)
+    @search.session = mock('session')
+  end
+
+  it 'should have 1 entry' do
+    @search.entries.length.should == 1
+    @search.entries.first.should be_an_instance_of(Photo)
+  end
+
+  it 'should alias entries to photos' do
+    @search.photos.should == @search.entries
+  end
+
+  it 'should request next' do
+    @search.session.expects(:get_url).with('http://picasaweb.google.com/data/feed/api/all?q=puppy&start-index=3&max-results=1').returns(:result)
+    @search.next.should == :result
+  end
+
+  it 'should request previous' do
+    @search.session.expects(:get_url).with('http://picasaweb.google.com/data/feed/api/all?q=puppy&start-index=1&max-results=1').returns(:result)
+    @search.previous.should == :result
+  end
+end
+