reagent-fleakr 0.2.1 → 0.3.0

data/lib/fleakr/objects/search.rb

@@ -0,0 +1,33 @@
+module Fleakr
+  module Objects # :nodoc:
+    class Search
+
+      # Create a new search
+      def initialize(search_options)
+        @search_options = search_options
+      end
+
+      # Retrieve search results from the API
+      def results
+        if @results.nil?
+          response = Fleakr::Api::Request.with_response!('photos.search', parameters)
+          @results = (response.body/'rsp/photos/photo').map do |flickr_photo|
+            Photo.new(flickr_photo)
+          end
+        end
+        @results
+      end
+
+      private
+      def tag_list
+        Array(@search_options[:tags]).join(',')
+      end
+
+      def parameters
+        @search_options.merge!(:tags => tag_list) if tag_list.length > 0
+        @search_options
+      end
+
+    end
+  end
+end

data/lib/fleakr/objects/set.rb

@@ -0,0 +1,45 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = Set
+    #
+    # == Attributes
+    # 
+    # [id] The ID for this photoset
+    # [title] The title of this photoset
+    # [description] The description of this set
+    # 
+    # == Associations
+    # 
+    # [photos] The collection of photos for this set. See Fleakr::Objects::Photo
+    #
+    class Set
+
+      include Fleakr::Support::Object
+
+      has_many :photos, :using => :photoset_id
+
+      flickr_attribute :id, :attribute => 'id'
+      flickr_attribute :title
+      flickr_attribute :description
+
+      find_all :by_user_id, :call => 'photosets.getList', :path => 'photosets/photoset'
+
+      # Save all photos in this set to the specified directory using the specified size.  Allowed
+      # Sizes include <tt>:square</tt>, <tt>:small</tt>, <tt>:thumbnail</tt>, <tt>:medium</tt>,  
+      # <tt>:large</tt>, and <tt>:original</tt>.  When saving the set, this # method will create 
+      # a subdirectory based on the set's title.
+      #
+      def save_to(path, size)
+        target = "#{path}/#{self.title}"
+        FileUtils.mkdir(target) unless File.exist?(target)
+
+        self.photos.each do |photo|
+          image = photo.send(size)
+          image.save_to(target) unless image.nil?
+        end
+      end
+
+    end
+  end
+end

data/lib/fleakr/objects/user.rb

@@ -0,0 +1,106 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = User
+    #
+    # == Accessors
+    # 
+    # This class maps directly onto the flickr.people.* API methods and provides the following attributes
+    # for a user:
+    #
+    # [id] The ID for this user (also referred to as the NSID in the API docs)
+    # [username] This user's username
+    # [name] This user's full name (if entered)
+    # [photos_url] The direct URL to this user's photostream
+    # [profile_url] The direct URL to this user's profile
+    # [photos_count] The number of photos that this user has uploaded
+    # [icon_url] This user's buddy icon (or a default one if an icon wasn't uploaded)
+    # [pro?] Does this user have a pro account?
+    # [admin?] Is this user an admin?
+    #
+    # == Associations
+    #
+    # The User class is pretty central to many of the other data available across the system, so there are a
+    # few associations available to a user:
+    # 
+    # [sets] A list of this user's public sets (newest first). See Fleakr::Objects::Set for more information.
+    # [groups] A list of this user's public groups. See Fleakr::Objects::Group.
+    # [photos] A list of this user's public photos (newest first).  See Fleakr::Objects::Photo.
+    # [contacts] A list of this user's contacts - these are simply User objects
+    #
+    # == Examples
+    #
+    # Access to a specific user is typically done through the Fleakr.user method:
+    #
+    #  user = Fleakr.user('brownout')
+    #  user.id
+    #  user.username
+    #  user.sets
+    #  user.contacts
+    #
+    class User
+
+      include Fleakr::Support::Object
+
+      def self.lazily_load(*attributes)
+        options = attributes.extract_options!
+
+        attributes.each do |attribute|
+          class_eval <<-CODE
+            def #{attribute}_with_loading
+              self.send(:#{options[:with]}) if @#{attribute}.nil?
+              #{attribute}_without_loading
+            end
+            alias_method_chain :#{attribute}, :loading
+          CODE
+        end
+      end
+
+      flickr_attribute :id, :xpath => 'rsp/user', :attribute => 'nsid'
+      flickr_attribute :username, :xpath => 'rsp/user/username'
+      flickr_attribute :name, :xpath => 'rsp/person/realname'
+      flickr_attribute :photos_url, :xpath => 'rsp/person/photosurl'
+      flickr_attribute :profile_url, :xpath => 'rsp/person/profileurl'
+      flickr_attribute :photos_count, :xpath => 'rsp/person/photos/count'
+      flickr_attribute :icon_server, :xpath => 'rsp/person', :attribute => 'iconserver'
+      flickr_attribute :icon_farm, :xpath => 'rsp/person', :attribute => 'iconfarm'
+      flickr_attribute :pro, :xpath => 'rsp/person', :attribute => 'ispro'
+      flickr_attribute :admin, :xpath => 'rsp/person', :attribute => 'isadmin'
+
+      has_many :sets, :groups, :photos, :contacts
+
+      find_one :by_username, :call => 'people.findByUsername'
+      find_one :by_email, :using => :find_email, :call => 'people.findByEmail'
+
+      lazily_load :name, :photos_url, :profile_url, :photos_count, :with => :load_info
+      lazily_load :icon_server, :icon_farm, :pro, :admin, :with => :load_info
+
+      scoped_search
+      
+      # Is this a pro account?
+      def pro?
+        (self.pro.to_i == 0) ? false : true
+      end
+
+      # Is this user an admin?
+      def admin?
+        (self.admin.to_i == 0) ? false : true
+      end
+
+      # This user's buddy icon
+      def icon_url
+        if self.icon_server.to_i > 0
+          "http://farm#{self.icon_farm}.static.flickr.com/#{self.icon_server}/buddyicons/#{self.id}.jpg"
+        else
+          'http://www.flickr.com/images/buddyicon.jpg'
+        end
+      end
+      
+      def load_info # :nodoc:
+        response = Fleakr::Api::Request.with_response!('people.getInfo', :user_id => self.id)
+        self.populate_from(response.body)
+      end
+
+    end
+  end
+end

data/lib/fleakr/support/attribute.rb

@@ -0,0 +1,28 @@
+module Fleakr
+  module Support # :nodoc:all
+    class Attribute
+
+      attr_reader :name, :xpath, :attribute
+
+      def initialize(name, options = {})
+        @name = name.to_sym
+        @attribute = options[:attribute]
+
+        @xpath = options[:xpath]
+        @xpath ||= @name.to_s unless @attribute
+      end
+
+      def value_from(document)
+        node = document
+
+        begin 
+          node = document.at(self.xpath) if self.xpath
+          self.attribute.nil? ? node.inner_text : node[self.attribute]
+        rescue NoMethodError
+          nil
+        end
+      end
+
+    end
+  end
+end

data/lib/fleakr/support/object.rb

@@ -0,0 +1,88 @@
+module Fleakr
+  module Support # :nodoc:all
+    module Object
+    
+      module ClassMethods
+      
+        def attributes
+          @attributes ||= []
+        end
+      
+        def flickr_attribute(name, options = {})
+          self.attributes << Attribute.new(name, options)
+          class_eval "attr_accessor :#{name}"
+        end
+      
+        def has_many(*attributes)
+          options = attributes.extract_options!
+          class_name = self.name
+
+          attributes.each do |attribute|
+            target = "Fleakr::Objects::#{attribute.to_s.classify}"
+            finder_attribute = options[:using].nil? ? "#{class_name.demodulize.underscore}_id": options[:using]
+            class_eval <<-CODE
+              def #{attribute}
+                @#{attribute} ||= #{target}.send("find_all_by_#{finder_attribute}".to_sym, self.id)
+              end
+            CODE
+          end
+        end
+      
+        def find_all(condition, options)
+          attribute    = options[:using].nil? ? condition.to_s.sub(/^by_/, '') : options[:using]
+          target_class = options[:class_name].nil? ? self.name : "Fleakr::Objects::#{options[:class_name]}"
+        
+          class_eval <<-CODE
+            def self.find_all_#{condition}(value)
+              response = Fleakr::Api::Request.with_response!('#{options[:call]}', :#{attribute} => value)
+              (response.body/'rsp/#{options[:path]}').map {|e| #{target_class}.new(e) }
+            end
+          CODE
+        end
+      
+        def find_one(condition, options)
+          attribute = options[:using].nil? ? condition.to_s.sub(/^by_/, '') : options[:using]
+        
+          class_eval <<-CODE
+            def self.find_#{condition}(value)
+              response = Fleakr::Api::Request.with_response!('#{options[:call]}', :#{attribute} => value)
+              #{self.name}.new(response.body)
+            end
+          CODE
+        end
+        
+        def scoped_search
+          key = "#{self.name.demodulize.underscore.downcase}_id".to_sym
+
+          class_eval <<-CODE
+            def search(search_text)
+              Fleakr::Objects::Search.new(:text => search_text, :#{key} => self.id).results
+            end
+          CODE
+        end
+      
+      end
+    
+      module InstanceMethods
+      
+        def initialize(document = nil)
+          self.populate_from(document) unless document.nil?
+        end
+      
+        def populate_from(document)
+          self.class.attributes.each do |attribute|
+            value = attribute.value_from(document)
+            self.send("#{attribute.name}=".to_sym, value) unless value.nil?
+          end
+        end
+      
+      end
+
+      def self.included(other)
+        other.send(:extend, Fleakr::Support::Object::ClassMethods)
+        other.send(:include, Fleakr::Support::Object::InstanceMethods)
+      end
+      
+    end
+  end
+end

data/lib/fleakr/version.rb

@@ -1,9 +1,9 @@
 module Fleakr
-  module Version
+  module Version # :nodoc:
     
     MAJOR = 0
-    MINOR = 2
-    TINY  = 1
+    MINOR = 3
+    TINY  = 0
     
     def self.to_s
       [MAJOR, MINOR, TINY].join('.')

data/lib/fleakr.rb

@@ -3,17 +3,72 @@ $:.unshift(File.dirname(__FILE__))
 require 'uri'
 require 'cgi'
 require 'net/http'
+require 'rubygems'
 require 'hpricot'
 require 'activesupport'
 
-require 'fleakr/object'
-require 'fleakr/attribute'
-require 'fleakr/photo'
-require 'fleakr/request'
-require 'fleakr/response'
-require 'fleakr/error'
-require 'fleakr/set'
-require 'fleakr/user'
-require 'fleakr/group'
-require 'fleakr/search'
-require 'fleakr/image'
+%w(support api objects).each do |path|
+  full_path = File.expand_path(File.dirname(__FILE__)) + "/fleakr/#{path}"
+  Dir["#{full_path}/*.rb"].each {|f| require f }
+end
+
+# = Fleakr: A teeny tiny gem to interface with Flickr
+#
+# Getting started is easy, just make sure you have a valid API key from Flickr and you can
+# then start making any non-authenticated request to pull back data for yours and others' 
+# photostreams, sets, contacts, groups, etc...
+#
+# For now, all activity originates from a single user which you can find by username or
+# email address.
+#
+# Example:
+#
+#  require 'rubygems'
+#  require 'fleakr'
+#
+#  # Our API key is ABC123 (http://www.flickr.com/services/api/keys/apply/)
+#  Fleakr.api_key = 'ABC123'
+#  user = Fleakr.user('bees')
+#  user = Fleakr.user('user@host.com')
+#  # Grab a list of sets
+#  user.sets
+#  # Grab a list of the user's public groups
+#  user.groups
+#
+# To see what other associations and attributes are available, see the Fleakr::Objects::User class
+#
+module Fleakr
+
+  mattr_accessor :api_key
+
+  # Find a user based on some unique user data.  This method will try to find
+  # the user based on username and will fall back to email if that fails.  Example:
+  #
+  #  Fleakr.api_key = 'ABC123'
+  #  Fleakr.user('the decapitator') # => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">
+  #  Fleakr.user('user@host.com')   # => #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00">
+  #
+  def self.user(user_data)
+    begin
+      Objects::User.find_by_username(user_data)
+    rescue Api::Request::ApiError
+      Objects::User.find_by_email(user_data)
+    end
+  end
+  
+  # Search all photos on the Flickr site.  By default, this searches based on text, but you can pass
+  # different search parameters (passed as hash keys):
+  #
+  # [tags] The list of tags to search on (either as an array or comma-separated)
+  # [user_id] Scope the search to this user
+  # [group_id] Scope the search to this group
+  #
+  # If you're interested in User- and Group-scoped searches, you may want to use User#search and Group#search
+  # instead.
+  #
+  def self.search(params)
+    params = {:text => params} unless params.is_a?(Hash)
+    Objects::Search.new(params).results
+  end
+  
+end

data/test/fixtures/contacts.getPublicList.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<rsp stat="ok">
+<contacts page="1" pages="1" per_page="1000" perpage="1000" total="17">
+	<contact nsid="9302864@N42" username="blinky" iconserver="2263" iconfarm="3" ignored="0" />
+	<contact nsid="63204625@N20" username="inky" iconserver="53" iconfarm="1" ignored="0" />
+</contacts>
+</rsp>

data/test/fixtures/groups.pools.getPhotos.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<rsp stat="ok">
+<photos page="1" pages="796" perpage="100" total="79509">
+	<photo id="3101830908" owner="64008250@N00" secret="e85e249e72" server="3042" farm="4" title="Canal Gate" ispublic="1" isfriend="0" isfamily="0" ownername="oakraidr" dateadded="1229049777" />
+	<photo id="3100780049" owner="98821864@N00" secret="f46fbe211b" server="3274" farm="4" title="2alarm" ispublic="1" isfriend="0" isfamily="0" ownername="LooknFeel" dateadded="1229042651" />
+</photos>
+</rsp>

data/test/fixtures/people.getInfo.xml

@@ -2,7 +2,7 @@
 <rsp stat="ok">
   <person id="31066442@N69" nsid="31066442@N69" isadmin="0" ispro="1" iconserver="30" iconfarm="1">
   	<username>frootpantz</username>
-  	<realname />
+  	<realname>Sir Froot Pantz</realname>
   	<mbox_sha1sum>e52ed1e5b91c763694995460e9796fc2adc02019</mbox_sha1sum>
   	<location />
   	<photosurl>http://www.flickr.com/photos/frootpantz/</photosurl>

data/test/fixtures/photos.getSizes.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<rsp stat="ok">
+  <sizes canblog="0" canprint="0" candownload="1">
+  	<size label="Square" width="75" height="75" source="http://farm4.static.flickr.com/3093/2409912100_71e14ed08a_s.jpg" url="http://www.flickr.com/photos/the_decapitator/2409912100/sizes/sq/" media="photo" />
+  	<size label="Thumbnail" width="100" height="67" source="http://farm4.static.flickr.com/3093/2409912100_71e14ed08a_t.jpg" url="http://www.flickr.com/photos/the_decapitator/2409912100/sizes/t/" media="photo" />
+  	<size label="Small" width="240" height="160" source="http://farm4.static.flickr.com/3093/2409912100_71e14ed08a_m.jpg" url="http://www.flickr.com/photos/the_decapitator/2409912100/sizes/s/" media="photo" />
+  	<size label="Medium" width="500" height="334" source="http://farm4.static.flickr.com/3093/2409912100_71e14ed08a.jpg" url="http://www.flickr.com/photos/the_decapitator/2409912100/sizes/m/" media="photo" />
+  	<size label="Original" width="700" height="467" source="http://farm4.static.flickr.com/3093/2409912100_3305c4a108_o.jpg" url="http://www.flickr.com/photos/the_decapitator/2409912100/sizes/o/" media="photo" />
+  </sizes>
+</rsp>

data/test/test_helper.rb

@@ -15,16 +15,31 @@ class Test::Unit::TestCase
     end
   end
 
+  def self.should_search_by(key)
+    it "should be able to perform a scoped search by :#{key}" do
+      photos = [stub()]
+      search = stub(:results => photos)
+      
+      klass = self.class.name.sub(/Test$/, '').constantize
+      
+      instance = klass.new
+      instance.stubs(:id).with().returns('1')
+      
+      Fleakr::Objects::Search.expects(:new).with(:text => 'foo', key => '1').returns(search)
+      
+      instance.search('foo').should == photos
+    end
+  end
+
   def self.should_have_many(*attributes)
     class_name = self.name.demodulize.sub(/Test$/, '')
-    this_klass = "Fleakr::#{class_name}".constantize
+    this_klass = "Fleakr::Objects::#{class_name}".constantize
 
     options = attributes.extract_options!
     finder_attribute = options[:using].nil? ? "#{class_name.downcase}_id" : options[:using]
     
     attributes.each do |attribute|
-      target_klass = "Fleakr::#{attribute.to_s.singularize.classify}".constantize
-    
+      target_klass = "Fleakr::Objects::#{attribute.to_s.singularize.classify}".constantize
       it "should be able to retrieve the #{class_name.downcase}'s #{attribute}" do
         results = [stub()]
         object = this_klass.new
@@ -46,7 +61,7 @@ class Test::Unit::TestCase
 
   def self.should_find_one(thing, options)
     class_name  = thing.to_s.singularize.camelcase
-    klass       = "Fleakr::#{class_name}".constantize
+    klass       = "Fleakr::Objects::#{class_name}".constantize
     object_type = class_name.downcase    
 
     options[:with] = options[:by] if options[:with].nil?
@@ -63,7 +78,7 @@ class Test::Unit::TestCase
 
   def self.should_find_all(thing, options)
     class_name  = thing.to_s.singularize.camelcase
-    klass       = "Fleakr::#{class_name}".constantize
+    klass       = "Fleakr::Objects::#{class_name}".constantize
     object_type = class_name.downcase
     
     it "should be able to find all #{thing} by #{options[:by]}" do
@@ -93,7 +108,7 @@ class Test::Unit::TestCase
   
   def mock_request_cycle(options)
     response = stub(:body => Hpricot.XML(read_fixture(options[:for])))
-    Fleakr::Request.expects(:with_response!).with(options[:for], options[:with]).returns(response)
+    Fleakr::Api::Request.expects(:with_response!).with(options[:for], options[:with]).returns(response)
     
     response
   end