maciej-flickr_fu 0.3.0

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

data/lib/flickr/license.rb

@@ -0,0 +1,24 @@
+class Flickr::Photos::License
+  attr_accessor :id, :name, :url
+
+  # create a new instance of a flickr photo license.
+  # 
+  # Params
+  # * attributes (Required)
+  #     a hash of attributes used to set the initial values of the license object
+  def initialize(attributes)
+    attributes.each do |k,v|
+      send("#{k}=", v)
+    end
+  end
+  
+  def == o
+    return false unless o.respond_to?(:id) && o.respond_to?(:name) && o.respond_to?(:url)
+    return true if id == o.id && name == o.name && url == o.url
+    false
+  end
+  
+  def eql? o
+    return self == o
+  end
+end

data/lib/flickr/location.rb

@@ -0,0 +1,15 @@
+class Flickr::Photos::Location
+
+  attr_accessor :latitude, :longitude, :accuracy
+
+  # Create an instance of Flickr::Photos::Location
+  #
+  # Params
+  # * attributes (Required)
+  #     a hash of attributes used to set the initial values of the Location object
+  def initialize(attributes)
+    attributes.each do |k,v|
+      send("#{k}=", v)
+    end
+  end
+end

data/lib/flickr/note.rb

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

data/lib/flickr/people.rb

@@ -0,0 +1,54 @@
+class Flickr::People < Flickr::Base
+  def initialize(flickr)
+    @flickr = flickr
+  end
+  
+  # Get information about a user.
+  # 
+  # Params
+  # * id (Required)
+  #     the nsid of the user to get information for
+  # 
+  def find_by_id(id)
+    rsp = @flickr.send_request('flickr.people.getInfo', {:user_id => id})
+        
+    Person.new(@flickr, :nsid => rsp.person[:nsid],
+                        :is_admin => (rsp.person[:isadmin] == "1" ? true : false),
+                        :is_pro => (rsp.person[:ispro] == "1" ? true : false),
+                        :icon_server => rsp.person[:iconserver],
+                        :icon_farm => rsp.person[:iconfarm],
+                        :username => rsp.person.username.to_s,
+                        :realname => rsp.person.realname.to_s,
+                        :mbox_sha1sum => rsp.person.mbox_sha1sum.to_s,
+                        :location => rsp.person.location.to_s,
+                        :photos_url => rsp.person.photosurl.to_s,
+                        :profile_url => rsp.person.profileurl.to_s,
+                        :photo_count => rsp.person.photos.count.to_s.to_i,
+                        :photo_first_upload => (Time.at(rsp.person.photos.firstdate.to_s.to_i) rescue nil),
+                        :photo_first_taken => (Time.parse(rsp.person.photos.firstdatetaken.to_s) rescue nil))
+  end
+  
+  # Get information about a user.
+  # 
+  # Params
+  # * username (Required)
+  #     the username of the user to get information for
+  #
+  def find_by_username(username)
+    rsp = @flickr.send_request('flickr.people.findByUsername', {:username => username})
+    
+    find_by_id(rsp.user[:nsid])
+  end
+  
+  # Get information about a user.
+  # 
+  # Params
+  # * email (Required)
+  #     the email of the user to get information for
+  #
+  def find_by_email(email)
+    rsp = @flickr.send_request('flickr.people.findByEmail', {:find_email => email})
+    
+    find_by_id(rsp.user[:nsid])
+  end
+end

data/lib/flickr/person.rb

@@ -0,0 +1,82 @@
+# wrapping class to hold an flickr photo
+# 
+class Flickr::People::Person
+  attr_accessor :username, :nsid, :is_admin, :is_pro, :icon_server, :icon_farm, :realname, :mbox_sha1sum, :location, :photos_url, :profile_url, :photo_count, :photo_first_upload, :photo_first_taken
+    
+  # create a new instance of a flickr person.
+  # 
+  # Params
+  # * flickr (Required)
+  #     the flickr object
+  # * attributes (Required)
+  #     a hash of attributes used to set the initial values of the person object
+  def initialize(flickr, attributes)
+    @flickr = flickr
+    attributes.each do |k,v|
+      send("#{k}=", v)
+    end
+  end
+  
+  def buddy_icon
+    @buddy_icon ||= if icon_server.to_i > 0
+                      "http://farm#{icon_farm}.static.flickr.com/#{icon_server}/buddyicons/#{nsid}.jpg"
+                    else
+                      'http://www.flickr.com/images/buddyicon.jpg'
+                    end
+  end
+  
+  # Get a list of public photos for the given user.
+  # 
+  # Options
+  # * safe_search (Optional)
+  #     Safe search setting:
+  #       1 for safe.
+  #       2 for moderate.
+  #       3 for restricted.
+  #     (Please note: Un-authed calls can only see Safe content.)
+  # * per_page (Optional)
+  #     Number of photos to return per page. If this argument is omitted, it defaults to 100. The maximum allowed value is 500.
+  # * page (Optional)
+  #     The page of results to return. If this argument is omitted, it defaults to 1.
+  def public_photos(options = {})
+    options.merge!({:user_id => self.nsid, :extras => "license,date_upload,date_taken,owner_name,icon_server,original_format,last_update,geo,tags,machine_tags,o_dims,views,media"})
+
+    rsp = @flickr.send_request('flickr.people.getPublicPhotos', options)
+
+    returning Flickr::Photos::PhotoResponse.new(:page => rsp.photos[:page].to_i,
+                                :pages => rsp.photos[:pages].to_i,
+                                :per_page => rsp.photos[:perpage].to_i,
+                                :total => rsp.photos[:total].to_i,
+                                :photos => [],
+                                :api => self,
+                                :method => 'public_photos',
+                                :options => options) do |photos|
+      rsp.photos.photo.each do |photo|
+        attributes = {:id => photo[:id], 
+                      :owner => photo[:owner], 
+                      :secret => photo[:secret], 
+                      :server => photo[:server], 
+                      :farm => photo[:farm], 
+                      :title => photo[:title], 
+                      :is_public => photo[:ispublic], 
+                      :is_friend => photo[:isfriend], 
+                      :is_family => photo[:isfamily],
+                      :license_id => photo[:license].to_i,
+                      :uploaded_at => (Time.at(photo[:dateupload].to_i) rescue nil),
+                      :taken_at => (Time.parse(photo[:datetaken]) rescue nil),
+                      :owner_name => photo[:ownername],
+                      :icon_server => photo[:icon_server],
+                      :original_format => photo[:originalformat],
+                      :updated_at => (Time.at(photo[:lastupdate].to_i) rescue nil),
+                      :geo => photo[:geo],
+                      :tags => photo[:tags],
+                      :machine_tags => photo[:machine_tags],
+                      :o_dims => photo[:o_dims],
+                      :views => photo[:views].to_i,
+                      :media => photo[:media]}
+
+        photos << Flickr::Photos::Photo.new(@flickr, attributes)
+      end if rsp.photos.photo
+    end
+  end
+end