neves-ruby_picasa 0.2.3

data/History.txt

@@ -0,0 +1,22 @@
+=== 0.2.1 / 2009-03-05
+
+* Now fully documented.
+* Full spec suite with 100% coverage.
+* Even easier to use the api.
+* Move thumbnail and url to Base so it can be used for Photos and Albums. 
+* Enable url to optionally return width and height for image_tag.
+* Use the numeric gphoto:id as id and rename tho standard atom feed id to feed_id
+* Fixed handling of cropped thumbnails and automatically query for valid thumbnail sizes.
+* Stopped using the wrong url to #load albums. Renamed method to #feed.
+
+=== 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/README.txt

@@ -0,0 +1,79 @@
+= 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
+
+== PUBLIC ALBUMS:
+  # 1. Create an public user by its id:
+  #
+  user = Picasa.public_user("user_id")
+  
+== 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/lib/ruby_picasa/types.rb

@@ -0,0 +1,315 @@
+module RubyPicasa
+  # attributes :url, :height, :width
+  class PhotoUrl < Objectify::ElementParser
+    attributes :url, :height, :width
+  end
+
+
+  class ThumbnailUrl < PhotoUrl
+
+    # The name of the current thumbnail. For possible names, see Photo#url
+    def thumb_name
+      name = url.scan(%r{/s([^/]+)/[^/]+$}).flatten.compact.first
+      if name
+        name.sub(/-/, '')
+      end
+    end
+  end
+
+
+  # Note that in all defined classes I'm ignoring values I don't happen to need
+  # or know about. Please do add support for the ones I've missed.  Be sure to
+  # declare which namespaces are supported with the namespaces method.  Any
+  # elements defined in other namespaces are automatically ignored.
+  #
+  # Base class for User, Photo and Album types, not used independently.
+  #
+  #   attribute :id, 'gphoto:id'
+  #   attribute :feed_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'
+  class Base < Objectify::DocumentParser
+    namespaces :openSearch, :gphoto, :media
+    flatten 'media:group'
+
+    attribute :id, 'gphoto:id'
+    attribute :feed_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'
+
+    # Return the link object with a matching rel attribute value. +rel+ can be
+    # either a fully matching string or a regular expression.
+    def link(rel)
+      links.find { |l| rel === l.rel }
+    end
+
+    def session=(session)
+      @session = session
+    end
+
+    # Should return the Picasa instance that retrieved this data.
+    def session
+      if @session
+        @session
+      else
+        @session = parent.session if parent
+      end
+    end
+
+    # Retrieves the data feed at the url of the current record.
+    def feed(options = {})
+      session.get_url(link('http://schemas.google.com/g/2005#feed').href, options)
+    end
+
+    # If the results are paginated, retrieve the next page.
+    def next
+      if link = link('next')
+        session.get_url(link.href)
+      end
+    end
+
+    # If the results are paginated, retrieve the previous page.
+    def previous
+      if link = link('previous')
+        session.get_url(link.href)
+      end
+    end
+
+    # Thumbnail names are by image width in pixels. Sizes up to 160 may be
+    # either cropped (square) or uncropped:
+    #
+    #   cropped:        32c, 48c, 64c, 72c, 144c, 160c
+    #   uncropped:      32u, 48u, 64u, 72u, 144u, 160u
+    #
+    # The rest of the image sizes should be specified by the desired width
+    # alone. Widths up to 800px may be embedded on a webpage:
+    # 
+    #   embeddable:     200, 288, 320, 400, 512, 576, 640, 720, 800
+    #   not embeddable: 912, 1024, 1152, 1280, 1440, 1600
+    #
+    # if a options is set to true or a hash is given, the width and height of
+    # the image will be added to the hash and returned. Useful for passing to
+    # the rails image_tag helper as follows:
+    #
+    #   image_tag(*image.url('72c', { :class => 'thumb' }))
+    #   
+    # which results in:
+    #
+    #   <img href="..." class="thumb" width="72" height="72">
+    #
+    def url(thumb_name = nil, options = nil)
+      url = nil
+      if thumb_name.is_a? Hash
+        options = thumb_name
+        thumb_name = nil
+      end
+      options = {} if options and not options.is_a? Hash
+      if thumb_name
+        if thumb = thumbnail(thumb_name)
+          url = thumb.url
+          options = { :width => thumb.width, :height => thumb.height }.merge(options) if options
+        end
+      else
+        url = content.url
+        options = { :width => content.width, :height => content.height }.merge(options) if options
+      end
+      if options
+        [url, options]
+      else
+        url
+      end
+    end
+
+    # See +url+ for possible image sizes
+    def thumbnail(thumb_name)
+      raise PicasaError, 'Invalid thumbnail size' unless Photo::VALID.include?(thumb_name.to_s)
+      thumb = thumbnails.find { |t| t.thumb_name == thumb_name }
+      if thumb
+        thumb
+      elsif session
+        f = feed(:thumbsize => thumb_name)
+        if f
+          f.thumbnails.first
+        end
+      end
+    end
+
+    # convert a thumbnail from a size to another, example:
+    # tb(160) converts this thumbnail url:
+    # http://lh5.ggpht.com/_8t0hxCMjpcM/SZ7OKoCAAsI/AAAAAAAABYA/_lUCR6-iV2g/s144-c/Calibration_Control_Image.jpg
+    # into this one with new size:
+    # http://lh5.ggpht.com/_8t0hxCMjpcM/SZ7OKoCAAsI/AAAAAAAABYA/_lUCR6-iV2g/s160/Calibration_Control_Image.jpg
+    # the thumb does not need to exist on the xml
+    def tb(new_size, crop = false)
+        crop = crop ? "-c" : ""
+        parts = thumbnails.first.url.split "/"
+        parts[-2] = "s" + new_size.to_s + crop
+        parts.join "/"
+    end
+    end
+
+
+  # Includes attributes and associations defined on Base, plus:
+  #
+  #   attributes :total_results, # represents total number of albums
+  #     :start_index,
+  #     :items_per_page,
+  #     :thumbnail
+  #   has_many :entries, :Album, 'entry'
+  class User < Base
+    attributes :total_results, # represents total number of albums
+      :start_index,
+      :items_per_page,
+      :thumbnail
+    has_many :entries, :Album, 'entry'
+
+    # The current page of albums associated to the user.
+    def albums
+      entries
+    end
+  end
+
+
+  # Includes attributes and associations defined on Base and User, plus:
+  #
+  #   has_many :entries, :Photo, 'entry'
+  class RecentPhotos < User
+    has_many :entries, :Photo, 'entry'
+
+    # The current page of recently updated photos associated to the user.
+    def photos
+      entries
+    end
+
+    undef albums
+  end
+
+
+  # Includes attributes and associations defined on Base, plus:
+  #
+  #   attributes :published,
+  #     :summary,
+  #     :rights,
+  #     :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'
+  class Album < Base
+    attributes :published,
+      :summary,
+      :rights,
+      :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'
+
+    # True if this album's rights are set to public
+    def public?
+      rights == 'public'
+    end
+
+    # True if this album's rights are set to private
+    def private?
+      rights == 'private'
+    end
+
+    # The current page of photos in the album.
+    def photos(options = {})
+      if entries.blank? and !@photos_requested
+        @photos_requested = true
+        if session and data = feed
+          self.entries = data.entries 
+        else
+          []
+        end
+      else
+        entries
+      end
+    end
+  end
+
+
+  class Search < Album
+    # The current page of photos matching the search.
+    def photos(options = {})
+      super
+    end
+  end
+
+
+  # Includes attributes and associations defined on Base, plus:
+  #
+  #   attributes :published,
+  #     :summary,
+  #     :version, # can use to determine if need to update...
+  #     :position,
+  #     :albumid, # useful from the recently updated feed for instance.
+  #     :width,
+  #     :height,
+  #     :description,
+  #     :keywords,
+  #     :credit
+  #   attribute :unique_id, 'exif:imageUniqueID'
+  #   attribute :exif_distance, 'exif:distance'
+  #   attribute :exif_exposure, 'exif:exposure'
+  #   attribute :exif_flash, 'exif:flash'
+  #   attribute :exif_focallength, 'exif:focallength'
+  #   attribute :exif_fstop, 'exif:fstop'
+  #   attribute :exif_iso, 'exif:iso'
+  #   attribute :exif_make, 'exif:make'
+  #   attribute :exif_model, 'exif:model'
+  #   attribute :exif_time, 'exif:time'
+  #   has_one :author, Objectify::Atom::Author, 'author'
+  class Photo < Base
+    CROPPED = %w[ 32c 48c 64c 72c 144c 160c ]
+    UNCROPPED = %w[ 32u 48u 64u 72u 144u 160u 32 48 64 72 144 160 ]
+    MEDIUM = %w[ 200 288 320 400 512 576 640 720 800 ]
+    LARGE = %w[ 912 1024 1152 1280 1440 1600 ]
+    VALID = CROPPED + UNCROPPED + MEDIUM + LARGE
+
+    namespace :exif
+
+    attributes :published,
+      :summary,
+      :version, # can use to determine if need to update...
+      :position,
+      :albumid, # useful from the recently updated feed for instance.
+      :width,
+      :height,
+      :description,
+      :keywords,
+      :credit
+
+    flatten 'exif:tags'
+    attribute :unique_id, 'exif:imageUniqueID'
+    attribute :exif_distance, 'exif:distance'
+    attribute :exif_exposure, 'exif:exposure'
+    attribute :exif_flash, 'exif:flash'
+    attribute :exif_focallength, 'exif:focallength'
+    attribute :exif_fstop, 'exif:fstop'
+    attribute :exif_iso, 'exif:iso'
+    attribute :exif_make, 'exif:make'
+    attribute :exif_model, 'exif:model'
+    attribute :exif_time, 'exif:time'
+
+    has_one :author, Objectify::Atom::Author, 'author'
+
+  end
+end
+