ruby-picasa 0.2.0

data/.autotest

@@ -0,0 +1,7 @@
+require 'autotest'
+require 'autotest/rspec'
+
+Autotest.add_hook :initialize do |at|
+ at.add_exception %r{^\./(?:\.git|pkg|doc)}
+ at.add_exception %r{\.sw[op]$}
+end

data/History.txt

@@ -0,0 +1,11 @@
+=== 0.2.0 / 2009-02-25
+
+* First public release.
+
+=== 0.1.0 / 2009-02-21
+
+* First working version.
+
+=== 0.0.0 / 2009-02-21
+
+* Needed to access Picasa.

data/Manifest.txt

@@ -0,0 +1,15 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/ruby_picasa/types.rb
+lib/ruby_picasa.rb
+spec/ruby_picasa/types_spec.rb
+spec/ruby_picasa_spec.rb
+spec/sample/album.atom
+spec/sample/recent.atom
+spec/sample/search.atom
+spec/sample/user.atom
+spec/spec.opts
+spec/spec_helper.rb
+.autotest

data/README.txt

@@ -0,0 +1,74 @@
+= ruby_picasa
+
+* http://github.com/pangloss/ruby_picasa
+
+== DESCRIPTION:
+
+Provides a super easy to use object layer for authenticating and accessing
+Picasa through their API.
+
+== FEATURES:
+
+* Simplifies the process of obtaining both a temporary and a permanent AuthSub
+  token.
+* Very easy to use API.
+* Allows access to both public and private User, Album and Photo data.
+* Uses Objectify::Xml to define the XML object-relational layer with a very
+  easy to understand DSL. See www.github.com/pangloss/objectify_xml
+
+== PROBLEMS:
+
+* None known.
+
+== SYNOPSIS:
+
+  # 1. Authorize application for access (in a rails controller)
+  #
+  redirect_to RubyPicasa.authorization_url(auth_result_url)
+
+  # 2. Extract the Picasa token from the request Picasa sends back to your app
+  #    and create a permanent AuthSub token. Returns an initialized Picasa
+  #    session.  (Called from the Rails action for auth_result_url above)
+  picasa = RubyPicasa.authorize_request(self.request)
+
+  # 3. Access the data you are interested in
+  @album = picasa.user.albums.first
+  @photo = @album.photos.first
+
+  # 4. Display your photos
+  image_tag @photo.url
+  image_tag @photo.url('160c') # Picasa thumbnail names are predefined
+
+== REQUIREMENTS:
+
+* objectify_xml
+
+== INSTALL:
+
+* gem install ruby-picasa
+* gem install pangloss-ruby-picasa --source http://gems.github.com
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Darrick Wiebe
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/ruby_picasa.rb'
+require 'spec/rake/spectask'
+
+Hoe.new('ruby-picasa', RubyPicasa::VERSION) do |p|
+  p.rubyforge_name = 'ruby-picasa'
+  p.developer('pangloss', 'darrick@innatesoftware.com')
+  p.extra_deps = 'objectify-xml'
+  p.testlib = 'spec'
+  p.test_globs = 'spec/**/*_spec.rb'
+  p.remote_rdoc_dir = ''
+end
+
+desc "Run all specifications"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs = ['lib', 'spec']
+  t.spec_opts = ['--colour', '--format', 'specdoc']
+end
+
+# vim: syntax=Ruby

data/lib/ruby_picasa.rb

@@ -0,0 +1,279 @@
+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.0'
+
+  class PicasaError < StandardError
+  end
+
+  class PicasaTokenError < PicasaError
+  end
+end
+
+class Picasa
+  include RubyPicasa
+
+  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)
+      session = request_session ? '1' : '0'
+      secure = secure ? '1' : '0'
+      return_to_url = CGI.escape(return_to_url)
+      url = 'http://www.google.com/accounts/AuthSubRequest'
+      "#{ url }?scope=http%3A%2F%2Fpicasaweb.google.com%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.params['token']
+        return token
+      else
+        raise PicasaTokenError, 'No Picasa authorization token was found.'
+      end
+    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
+
+    def host
+      'picasaweb.google.com'
+    end
+
+    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 = path.join('/')
+      end
+      options['kind'] = 'photo' if args[:recent_photos] or args[:album_id]
+      [: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
+
+    private
+
+    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
+
+  attr_reader :token
+
+  def initialize(token)
+    @token = token
+    @request_cache = {}
+  end
+
+  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
+
+  def user(user_id_or_url = 'default', options = {})
+    get(options.merge(:user_id => user_id_or_url))
+  end
+
+  def album(album_id_or_url, options = {})
+    get(options.merge(:album_id => album_id_or_url))
+  end
+
+  # This request does not require authentication.
+  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
+
+  def get_url(url, options = {})
+    get(options.merge(:url => url))
+  end
+
+  def recent_photos(user_id_or_url = 'default', options = {})
+    if user_id_or_url.is_a?(Hash)
+      options = user_id_or_url
+      user_id_or_url = 'default'
+    end
+    h = {}
+    h[:user_id] = user_id_or_url
+    h[:recent_photos] = true
+    get(options.merge(h))
+  end
+
+  def album_by_title(title, options = {})
+    if a = user.albums.find { |a| title === a.title }
+      a.load options
+    end
+  end
+
+  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
+
+  def get(options = {})
+    with_cache(options) do |xml|
+      class_from_xml(xml)
+    end
+  end
+
+  private
+
+  def auth_header
+    if token
+      { "Authorization" => %{AuthSub token="#{ token }"} }
+    else
+      {}
+    end
+  end
+
+  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
+
+  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
+
+  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$/
+          User.new(xml, self)
+        when /#photo$/
+          RecentPhotos.new(xml, self)
+        end
+      when /#album$/
+        case entry_scheme
+        when nil, /#photo$/
+          Album.new(xml, self)
+        end
+      when /#photo$/
+        case entry_scheme
+        when /#photo$/
+          Search.new(xml, self)
+        when nil
+          Photo.new(xml, self)
+        end
+      end
+      if r
+        r.session = self
+        r
+      else
+        raise PicasaError, "Unknown feed type\n feed:  #{ feed_scheme }\n entry: #{ entry_scheme }"
+      end
+    end
+  end
+end

data/lib/ruby_picasa/types.rb

@@ -0,0 +1,165 @@
+# Note that in all defined classes I'm ignoring values I don't happen to care
+# about. If you care about them, please feel free to add support for them,
+# which should not be difficult.
+#
+# Plural attribute names will be treated as arrays unless the element name
+# in the xml document is already plural. (Convention seems to be to label
+# repeating elements in the singular.)
+#
+# If an attribute should be a non-trivial datatype, define the mapping from
+# the fully namespaced attribute name to the class you wish to use in the
+# class method #types.
+#
+# Define which namespaces you support in the class method #namespaces. Any
+# elements defined in other namespaces are automatically ignored.
+module RubyPicasa
+  class PhotoUrl < Objectify::ElementParser
+    attributes :url, :height, :width
+  end
+
+
+  class ThumbnailUrl < PhotoUrl
+    def thumb_name
+      url.scan(%r{/([^/]+)/[^/]+$}).flatten.compact.first
+    end
+  end
+
+
+  class Base < Objectify::DocumentParser
+    namespaces :openSearch, :gphoto, :media
+    flatten 'media:group'
+
+    attribute :id, 'id'
+    attributes :updated, :title
+
+    has_many :links, Objectify::Atom::Link, 'link'
+    has_one :content, PhotoUrl, 'media:content'
+    has_many :thumbnails, ThumbnailUrl, 'media:thumbnail'
+    has_one :author, Objectify::Atom::Author, 'author'
+
+    def link(rel)
+      links.find { |l| l.rel == rel }
+    end
+
+    def session=(session)
+      @session = session
+    end
+
+    def session
+      if @session
+        @session
+      else
+        @session = parent.session if parent
+      end
+    end
+
+    def load(options = {})
+      session.get_url(id, options)
+    end
+
+    def next
+      if link = link('next')
+        session.get_url(link.href)
+      end
+    end
+
+    def previous
+      if link = link('previous')
+        session.get_url(link.href)
+      end
+    end
+  end
+
+
+  class User < Base
+    attributes :total_results, # represents total number of albums
+      :start_index,
+      :items_per_page,
+      :thumbnail
+    has_many :entries, :Album, 'entry'
+
+    def albums
+      entries
+    end
+  end
+
+
+  class RecentPhotos < User
+    has_many :entries, :Photo, 'entry'
+
+    def photos
+      entries
+    end
+
+    undef albums
+  end
+
+
+  class Album < Base
+    attributes :published,
+      :summary,
+      :rights,
+      :gphoto_id,
+      :name,
+      :access,
+      :numphotos, # number of pictures in this album
+      :total_results, # number of pictures matching this 'search'
+      :start_index,
+      :items_per_page,
+      :allow_downloads
+    has_many :entries, :Photo, 'entry'
+
+    def public?
+      rights == 'public'
+    end
+
+    def private?
+      rights == 'private'
+    end
+
+    def photos(options = {})
+      if entries.blank? and !@photos_requested
+        @photos_requested = true
+        self.session ||= parent.session
+        self.entries = session.album(id, options).entries if self.session
+      else
+        entries
+      end
+    end
+  end
+
+
+  class Search < Album
+  end
+
+
+  class Photo < Base
+    attributes :published,
+      :summary,
+      :gphoto_id,
+      :version, # can use to determine if need to update...
+      :position,
+      :albumid, # useful from the recently updated feed for instance.
+      :width,
+      :height,
+      :description,
+      :keywords,
+      :credit
+    has_one :author, Objectify::Atom::Author, 'author'
+
+    def url(thumb_name = nil)
+      if thumb_name
+        if thumb = thumbnail(thumb_name)
+          thumb.url
+        end
+      else
+        content.url
+      end
+    end
+
+    def thumbnail(thumb_name)
+      thumbnails.find { |t| t.thumb_name == thumb_name }
+    end
+  end
+end
+