tomk32-flickr_fu 0.3.0

data/.gitignore

@@ -0,0 +1,13 @@
+rdoc
+.DS_Store
+*.gem
+demo*
+*~
+*.sw*
+.specification
+nbproject/
+doc/rspec_report.html
+doc/rspec_profile.txt
+spec/spec.local.opts
+coverage/
+pkg/

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2008 CommonThread, LLC
+
+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/README

@@ -0,0 +1,182 @@
+= flickr-fu
+
+== Contact
+
+  Author: Ben Wyrosdick
+  Email: ben [at] commonthread.com
+  Lighthouse: http://commonthread.lighthouseapp.com/projects/12069-flickr_fu/overview
+  Main Repository: http://github.com/commonthread/flickr_fu/tree/master
+
+== Getting Started
+
+  You need to first get an API key as detailed here:
+
+  http://www.flickr.com/services/api/misc.api_keys.html
+  
+== Installation
+
+  sudo gem install flickr-fu
+
+== Documentation
+
+  RDoc Documentation can be found here:
+
+  http://www.commonthread.com/projects/flickr_fu/rdoc/
+
+== Example flickr.yml
+--- !map:HashWithIndifferentAccess
+key: "YOUR KEY"
+secret: "YOUR SECRET"
+token_cache: "token_cache.yml"
+
+== Authorization
+
+  To authorise your application to access Flickr using your API key you will
+  need to access a specific URL.
+  
+  To generate this URL run the following and when presented with the URL 
+  access it from your browser. Confirm the application has permission at 
+  the level you have specified.
+  
+  Note that flickr has different types of keys. If you use one for a webapplication,
+  which is most likely, you need to define a callback and somehow make sure that
+  you connect the parameter :frob that flickr send via the callback is assigned
+  to the right user account. The best way to do this is to loop over all the current
+  user's flickr accounts and try flickr.auth.token with the :frob.
+  
+  Finally, cache the token (this will create the token cache file)
+  
+  If you have an invalid API key you will see errors such as:
+  
+  "100: Invalid API Key"
+  
+  If you don't follow the process below to authorise your application
+  you will see errors such as:
+  
+  "98: Login failed / Invalid auth token" or 
+  "99: User not logged in / Insufficient permissions"
+  
+== Authorization Example for non-webapplication
+
+  require 'flickr_fu'
+  
+  flickr = Flickr.new('flickr.yml')
+  
+  puts "visit the following url, then click <enter> once you have authorized:"
+
+  # request write permissions
+  puts flickr.auth.url(:write)
+  
+  gets
+  
+  flickr.auth.cache_token
+
+== Authorization Example for a webapplication
+
+  flickr.auth.token also contains the nsid and username, this
+  example only stores the token and no other userdata.
+  All you need in the views is a button or link to FlickrController.create
+
+  require 'flickr_fu'
+  class FlickrController < ActionController::Base
+    def create
+      flickr = Flickr.new('flickr.yml')
+      redirect_to flickr.auth.url(:write)
+    end
+    def flickr_callback
+      flickr = Flickr.new('flickr.yml')
+      flickr.auth.frob = params[:frob]
+      current_user.update_attribute :flickr_token, flickr.auth.token.token
+    end
+    def something_else_with_flickr
+      flickr = Flickr.new(YAML.load_file('flickr.yml').merge(:token => current_user.flickr_token))
+      # now you have full access on the user's data :)
+    end
+  end
+
+=== User creation on the fly
+
+  To use the userdata in flickr.auth.token and create
+  an account with it on the fly try following flickr_callback
+  
+  def flickr_callback
+    flickr = Flickr.new('flickr.yml')
+    flickr.auth.frob = params[:frob]
+    if(!logged_in?)
+      # no user yet for this flickr id, create a new user
+      if (current_user = User.find_by_flickr_nsid(flickr.auth.token.user_id))).nil?
+        current_user = User.new do |user|
+          user.login = flickr.auth.token.username
+          user.real_name = flickr.auth.token.user_real_name
+          user.flickr_nsid = flickr.auth.token.user_id
+          user.flickr_token = flickr.auth.token.token
+        end
+      else # we have a user for that flick account, login and update token
+        current_user.flickr_token = flickr.auth.token.token
+      end
+      if(current_user.save)
+        flash[:notice] = 'Registered and logged in via flickr'
+        redirect_to '/'
+      else
+        // probably you validate for the presence of an email address?
+        flash[:error] = 'Logged in via flickr but some user data is missing'
+        @user = current_user
+        render :action => 'users/new'
+      end
+    else
+      current_user.update_attribute :flickr_token, flickr.auth.token.token
+    end
+  end
+
+== Search Example
+
+  require 'flickr_fu'
+
+  flickr = Flickr.new('flickr.yml')
+
+  photos = flickr.photos.search(:tags => 'ruby-flickr')
+
+  puts "found #{photos.size} photo(s)"
+
+  photos.each do |photo|
+    puts photo.title
+    puts photo.description unless [nil, ''].include?(photo.description)
+    [:square, :thumbnail, :small, :medium, :large, :original].each do |size|
+      puts "#{size}: #{photo.url(size)}"
+    end
+    puts "comments: #{photo.comments.size}"
+    photo.comments.each do |comment|
+      intro = "#{comment.author_name} says - "
+      puts "#{intro}\"#{comment.comment.gsub("\n", "\n"+(" "*intro.length))}\""
+    end
+    puts "notes: #{photo.notes.size}"
+    photo.notes.each do |note|
+      puts "[#{note.x},#{note.y} ~ #{note.width}x#{note.height}] - \"#{note.note}\""
+    end
+    puts
+    puts
+  end
+  
+== Another Search Example
+
+  If searching for photos by user id then you need to specify the 'alias' - without
+  intervention this is usually set by Flickr and is an alphanumeric string. 
+  
+  To find out the user id for a given user, you can use the tool at:
+  
+  http://idgettr.com/
+  
+  And replace the line in the above sample to query on user id:
+  
+  photos = flickr.photos.search(:user_id => 'your_user_id_here')
+
+== Patch Contributers
+
+  Chris Ledet
+  Maciej Biłas
+  Mike Perham
+  Chris Anderton
+  Luke Francl
+  Thomas R. Koll
+  P. Mark Anderson
+  Josh Nichols

data/Rakefile

@@ -0,0 +1,73 @@
+require 'rake'
+require 'rake/rdoctask'
+
+# Gem building
+begin
+  begin
+    require 'jeweler'
+  rescue LoadError
+    require 'rubygems'
+    require 'jeweler'
+  end
+  Jeweler::Tasks.new do |s|
+    s.name = "flickr_fu"
+    s.summary = "Provides a ruby interface to flickr via the REST api"
+    s.email = "ben@commonthread.com"
+    s.homepage = "http://github.com/commonthread/flickr_fu"
+    s.description = "Provides a ruby interface to flickr via the REST api"
+    s.authors = ["Ben Wyrosdick", "Maciej Bilas"]
+    s.rdoc_options = ["--main", "README"]
+    s.extra_rdoc_files = ["README"]
+    s.add_dependency("mime-types", ["> 0.0.0"])
+    s.add_dependency("xml-magic", ["> 0.0.0"])
+	s.files.exclude("spec/spec.local.opts")
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+desc 'Generate documentation for flickr_fu.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'flickr_fu'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# RSpec support
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems'
+  require 'spec'
+end
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts <<-EOS
+	  To use rspec for testing you must install rspec gem:
+	  gem install rspec
+  EOS
+  exit(0)
+end
+
+task :default => :spec
+
+spec_common = Proc.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_opts << ['--options', "spec/spec.local.opts" ] if File.exist?(File.dirname(__FILE__) + "/spec/spec.local.opts")
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc "Run the specs under spec/models"
+Spec::Rake::SpecTask.new do |t|
+  spec_common.call(t)
+end
+
+desc "Analyze code coverage with tests"
+Spec::Rake::SpecTask.new("rcov") do |t|
+  spec_common.call(t)
+  t.rcov = true
+  t.rcov_opts = ["-x", "/var/lib", "-x", "spec/", "-T"]
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 3
+:patch: 0

data/lib/flickr/auth.rb

@@ -0,0 +1,76 @@
+class Flickr::Auth < Flickr::Base
+  def initialize(flickr)
+    @flickr = flickr
+  end
+
+  # get or return a frob to use for authentication
+  def frob
+    @frob ||= get_frob
+  end
+  
+  # set the frob
+  def frob= frob
+    @frob=frob
+  end
+
+  # generates the authorization url to allow access to a flickr account.
+  # 
+  # Params
+  # * perms (Optional)
+  #     sets the permision level to grant on the flickr account.
+  #       :read - permission to read private information (DEFAULT)
+  #       :write - permission to add, edit and delete photo metadata (includes 'read')
+  #       :delete - permission to delete photos (includes 'write' and 'read')
+  # 
+  def url(perms = :read)
+    options = {:api_key => @flickr.api_key, :perms => perms, :frob => self.frob}
+    @flickr.sign_request(options)
+    Flickr::Base::AUTH_ENDPOINT + "?" + options.collect{|k,v| "#{k}=#{v}"}.join('&')
+  end
+
+  # gets the token object for the current frob
+  # 
+  # Params
+  # * pass_through (Optional)
+  #     Boolean value that determines if a call will be made to flickr to find a taken for the current frob if empty
+  # 
+  def token(pass_through = true)
+    @token ||= get_token(pass_through) rescue nil
+  end
+
+  # saves the current token to the cache file if token exists
+  # 
+  # Param
+  # * filename (Optional)
+  #     filename of the cache file. defaults to the file passed into Flickr.new
+  # 
+  def cache_token(filename = @flickr.token_cache)
+    if filename and self.token
+      cache_file = File.open(filename, 'w+')
+      cache_file.puts self.token.to_yaml
+      cache_file.close
+      true
+    else
+      false
+    end
+  end
+
+  private
+  def get_frob
+    rsp = @flickr.send_request('flickr.auth.getFrob')
+
+    rsp.frob.to_s
+  end
+
+  def get_token(pass_through)
+    if @flickr.token
+      @flickr.token
+    elsif @flickr.token_cache and File.exists?(@flickr.token_cache)
+      YAML.load_file(@flickr.token_cache)
+    elsif pass_through
+      rsp = @flickr.send_request('flickr.auth.getToken', {:frob => self.frob})
+
+      Token.new(:token => rsp.auth.token.to_s, :permisions => rsp.auth.perms.to_s, :user_id => rsp.auth.user[:nsid], :username => rsp.auth.user[:username], :user_real_name => rsp.auth.user[:fullname])
+    end
+  end
+end

data/lib/flickr/base.rb

@@ -0,0 +1,151 @@
+module Flickr
+  def self.new(*params)
+    Flickr::Base.new(*params)
+  end
+  
+  class Base
+    attr_reader :api_key, :api_secret, :token_cache, :token
+    
+    REST_ENDPOINT = 'http://api.flickr.com/services/rest/'
+    AUTH_ENDPOINT = 'http://flickr.com/services/auth/'
+    UPLOAD_ENDPOINT = 'http://api.flickr.com/services/upload/'
+    
+    # create a new flickr object
+    # 
+    # You can either pass a hash with the following attributes:
+    # 
+    # * :key (Required)
+    #     the API key
+    # * :secret (Required)
+    #     the API secret
+    # * :token (Optional)
+    #     Flickr::Auth::Token object
+    #
+    # or:
+    # 
+    # * config_file (Required)
+    #     yaml file to load configuration from
+    # * options (Optional)
+    #     hash containing any of the two options
+    #     * token_cache
+    #       location of the token cache file. This will override the setting in the config file
+    #     * environment
+    #       section in the config file that flickr_fu should look for the API key and secret
+    #       Useful when using with Rails
+    #
+    # Config Example (yaml file)
+    # ---
+    #   key: YOUR_API_KEY
+    #   secret: YOUR_API_SECRET
+    #   token_cache: token.yml
+    #
+    # Example config file with two environments:
+    # ---
+    #   development:
+    #     key: YOUR_DEVELOPMENT_API_KEY
+    #     secret: YOUR_DEVELOPMENT_API_SECRET
+    #   production:
+    #     key: YOUR_PRODUCTION_API_KEY
+    #     secret: YOUR_PRODUCTION_API_SECRET
+    def initialize(config_param, options_param = {})
+      if options_param.is_a? String
+        options = {:token_cache => options_param}
+      else
+        options = options_param
+      end
+      if config_param.is_a? String
+        config = YAML.load_file(config_param)
+        config = config[options[:environment]] if options.has_key? :environment
+      else
+        config = config_param
+      end
+      @api_key = config[:key] || config["key"]
+      @api_secret = config[:secret] || config["secret"]
+      @token_cache = options[:token_cache] || config["token_cache"]
+      @token = config[:token] || options[:token]
+      raise 'config file must contain an api key and secret' unless @api_key and @api_secret
+      raise 'you cannot specify both the token and token_cache' if @token and @token_cache
+    end
+
+    # sends a request to the flickr REST api
+    # 
+    # Params
+    # * method (Required)
+    #     name of the flickr method (ex. flickr.photos.search)
+    # * options (Optional)
+    #     hash of query parameters, you do not need to include api_key, api_sig or auth_token because these are added automatically
+    # * http_method (Optional)
+    #     choose between a GET and POST http request. Valid options are:
+    #       :get (DEFAULT)
+    #       :post
+    # * endpoint (Optional)
+    #     url of the api endpoint
+    # 
+    def send_request(method, options = {}, http_method = :get, endpoint = REST_ENDPOINT)
+      options.merge!(:api_key => @api_key, :method => method)
+      sign_request(options)
+      
+      rsp = request_over_http(options, http_method, endpoint)
+      
+      rsp = '<rsp stat="ok"></rsp>' if rsp == ""
+      xm = XmlMagic.new(rsp)
+      
+      if xm[:stat] == 'ok'
+        xm
+      else
+        raise Flickr::Errors.error_for(xm.err[:code].to_i, xm.err[:msg])
+      end
+    end
+    
+    # alters your api parameters to include a signiture and authorization token
+    # 
+    # Params
+    # * options (Required)
+    #     the hash of parameters to be passed to the send_request
+    # * authorize (Optional)
+    #     boolean value to determine if the call with include an auth_token (Defaults to true)
+    # 
+    def sign_request(options, authorize = true)
+      options.merge!(:auth_token => self.auth.token(false).to_s, :api_key => @api_key) if authorize and self.auth.token(false)
+      options.delete(:api_sig)
+      options.merge!(:api_sig => Digest::MD5.hexdigest(@api_secret + options.to_a.sort_by{|k| k[0].to_s}.flatten.join)) if @api_secret
+    end
+    
+    # creates and/or returns the Flickr::Test object
+    def test() @test ||= Flickr::Test.new(self) end
+
+    # creates and/or returns the Flickr::Photos object
+    def photos() @photos ||= Flickr::Photos.new(self) end
+      
+    # creates and/or returns the Flickr::Photos object
+    def photosets() @photosets ||= Flickr::Photosets.new(self) end
+      
+    # creates and/or returns the Flickr::People object
+    def people() @people ||= Flickr::People.new(self) end
+      
+    # creates and/or returns the Flickr::Auth object
+    def auth() @auth ||= Flickr::Auth.new(self) end
+      
+    # creates and/or returns the Flickr::Uploader object
+    def uploader() @uploader ||= Flickr::Uploader.new(self) end
+
+    # creates and/or returns the Flickr::Contacts object
+    def contacts() @contacts ||= Flickr::Contacts.new(self) end
+
+    # creates and/or returns the Flickr::Urls object
+    def urls() @urls ||= Flickr::Urls.new(self) end
+            
+    protected
+    
+    # For easier testing. You can mock this method with a XML file you're expecting to receive
+    def request_over_http(options, http_method, endpoint)
+      if http_method == :get
+        api_call = endpoint + "?" + options.collect{|k,v| "#{k}=#{CGI.escape(v.to_s)}"}.join('&')
+        Net::HTTP.get(URI.parse(api_call))
+      else
+        Net::HTTP.post_form(URI.parse(endpoint), options).body
+      end
+    end
+    
+  end
+end

data/lib/flickr/comment.rb

@@ -0,0 +1,16 @@
+# wrapping class to hold a flickr comment
+# 
+class Flickr::Photos::Comment
+  attr_accessor :id, :comment, :author, :author_name, :created_at, :permalink
+  
+  # create a new instance of a flickr comment.
+  # 
+  # Params
+  # * attributes (Required)
+  #     a hash of attributes used to set the initial values of the comment object
+  def initialize(attributes)
+    attributes.each do |k,v|
+      send("#{k}=", v)
+    end
+  end
+end

data/lib/flickr/contact.rb

@@ -0,0 +1,16 @@
+# wrapping class to hold a flickr contact
+# 
+class Flickr::Contacts::Contact
+  attr_accessor :nsid, :friend, :family, :iconfarm, :iconserver, :location, :username, :ignored, :realname, :path_alias
+  
+  # create a new instance of a flickr note.
+  # 
+  # Params
+  # * attributes (Required)
+  #     a hash of attributes used to set the initial values of the contact object
+  def initialize(attributes)
+    attributes.each do |k,v|
+      send("#{k}=", v)
+    end
+  end
+end

data/lib/flickr/contacts.rb

@@ -0,0 +1,55 @@
+class Flickr::Contacts < Flickr::Base
+  def initialize(flickr)
+    @flickr = flickr
+  end
+
+  # Get a user's public contact list.
+  # 
+  # Params
+  # * id (Required)
+  #     the nsid of the user to get information for
+  # 
+  def get_public_list(id, options={})
+    options.merge!({:user_id => id})
+    rsp = @flickr.send_request('flickr.contacts.getPublicList', options)
+    collect_contacts(rsp)
+  end
+    
+  
+  # Get the authorized user's contact list.
+  # 
+  def get_list(options={})
+    rsp = @flickr.send_request('flickr.contacts.getList', options)
+    collect_contacts(rsp)
+  end
+  
+  
+  protected
+  def collect_contacts(rsp)
+    contacts = []
+    return contacts unless rsp
+    if rsp.contacts.contact
+      rsp.contacts.contact.each do |contact|
+        attributes = create_attributes(contact)
+        contacts << Contact.new(attributes)
+      end
+    end
+    return contacts
+  end
+  
+  def create_attributes(contact)
+    {
+      :nsid => contact[:nsid], 
+      :path_alias => contact[:path_alias],
+      :username => contact[:username],
+      :iconfarm => contact[:iconfarm],
+      :iconserver => contact[:iconserver],
+      :ignored => contact[:ignored],
+      :friend => contact[:friend],
+      :family => contact[:family],
+      :realname => contact[:realname],
+      :location => contact[:location]
+     }
+  end
+  
+end

data/lib/flickr/errors.rb

@@ -0,0 +1,20 @@
+module Flickr
+    class Error < RuntimeError
+      attr_accessor :code
+    end
+    
+    
+    class Errors
+      
+      # Method used for raising the appropriate error class for a given error code.
+      # Currently raises only Flickr::Error
+      def self.error_for(code, message)
+        raise RuntimeError.new("Internal error. Flickr API error not identified or unknown error.") if (code.nil? || message.nil? || message.empty?)
+        raise RuntimeError.new("Internal error. Unknown error.") if code.to_i == 0 # We assume that error code 0 is never returned
+        e = Flickr::Error.new("#{code}: #{message}")
+        e.code = code
+        raise e
+      end
+    end
+
+end

data/lib/flickr/geo.rb

@@ -0,0 +1,42 @@
+class Flickr::Photos::Geo < Flickr::Base
+
+  def initialize(flickr)
+    @flickr = flickr
+  end
+
+  # Get the geo data (latitude and longitude and the accuracy level) of a photo.
+  #
+  # Params
+  # * photo_id (Required)
+  #
+  # Returns Flickr::Photos::Location object containing photo location
+  # or nil if photo is not geotagged.
+  def get_location(photo_id)
+    # begin
+    rsp = @flickr.send_request('flickr.photos.geo.getLocation', {:photo_id => photo_id})
+    Flickr::Photos::Location.new(:latitude => rsp.photo.location[:latitude].to_f,
+      :longitude => rsp.photo.location[:longitude].to_f, :accuracy => rsp.photo.location[:accuracy].to_i)
+  end
+
+  # Sets the geo data(latitude and longitude and the accuracy level) of a photo.
+  #
+  # Params
+  # * photo_id (Required)
+  # * latittude (Requried)
+  # * longitude (Required)
+  # * accuracy (Optional)
+  #
+  # Returns true if successful, raises an error otherwise.
+  def set_location(photo_id, lat, lon, accuracy = nil)
+    request_options = {:photo_id => photo_id, :lat => lat, :lon => lon}
+    request_options[:accuracy] = accuracy if !accuracy.nil?
+    @flickr.send_request('flickr.photos.geo.setLocation', request_options, :post)
+    true
+  end
+
+  def remove_location(photo_id)
+    request_options = {:photo_id => photo_id}
+    @flickr.send_request('flickr.photos.geo.removeLocation', request_options, :post)
+    true
+  end
+end