fleakr 0.3.0 → 0.4.0

data/lib/fleakr/objects/image.rb

@@ -24,11 +24,11 @@ module Fleakr
 
       include Fleakr::Support::Object
 
-      flickr_attribute :size,   :attribute => :label
-      flickr_attribute :width,  :attribute => :width
-      flickr_attribute :height, :attribute => :height
-      flickr_attribute :url,    :attribute => :source
-      flickr_attribute :page,   :attribute => :url
+      flickr_attribute :size,   :from => '@label'
+      flickr_attribute :width
+      flickr_attribute :height
+      flickr_attribute :url,    :from => '@source'
+      flickr_attribute :page,   :from => '@url'
 
       find_all :by_photo_id, :call => 'photos.getSizes', :path => 'sizes/size'
 
@@ -41,8 +41,8 @@ module Fleakr
       # directory, the file will be created with the original filename from Flickr.  
       # If the target is a file, it will be saved with the specified name.  In the
       # case that the target file already exists, this method will overwrite it.
-      def save_to(target)
-        destination = File.directory?(target) ? "#{target}/#{self.filename}" : "#{target}"
+      def save_to(target, prefix = nil)
+        destination = File.directory?(target) ? "#{target}/#{prefix}#{self.filename}" : "#{target}"
         File.open(destination, 'w') {|f| f << Net::HTTP.get(URI.parse(self.url)) }
       end
     

data/lib/fleakr/objects/photo.rb

@@ -7,6 +7,10 @@ module Fleakr
     #
     # [id] The ID for this photo
     # [title] The title of this photo
+    # [description] The description of this photo
+    # [secret] This photo's secret (used for sharing photo without permissions checking)
+    # [comment_count] Count of the comments attached to this photo
+    # [url] This photo's page on Flickr
     # [square] The tiny square representation of this photo
     # [thumbnail] The thumbnail for this photo
     # [small] The small representation of this photo
@@ -25,18 +29,78 @@ module Fleakr
 
       include Fleakr::Support::Object
 
-      flickr_attribute :title, :attribute => 'title'
-      flickr_attribute :id, :attribute => 'id'
-      flickr_attribute :farm_id, :attribute => 'farm'
-      flickr_attribute :server_id, :attribute => 'server'
-      flickr_attribute :secret, :attribute => 'secret'
+      flickr_attribute :id, :from => ['@id', 'photoid']
+      flickr_attribute :title
+      flickr_attribute :description
+      flickr_attribute :farm_id, :from => '@farm'
+      flickr_attribute :server_id, :from => '@server'
+      flickr_attribute :secret
+      flickr_attribute :posted
+      flickr_attribute :taken
+      flickr_attribute :updated, :from => '@lastupdate'
+      flickr_attribute :comment_count, :from => 'comments'
+      flickr_attribute :url
+
+      # TODO:
+      # * owner (user)
+      # * visibility
+      # * editability
+      # * usage
+      # * notes
+      # * tags
 
       find_all :by_photoset_id, :call => 'photosets.getPhotos', :path => 'photoset/photo'
       find_all :by_user_id, :call => 'people.getPublicPhotos', :path => 'photos/photo'
       find_all :by_group_id, :call => 'groups.pools.getPhotos', :path => 'photos/photo'
       
+      find_one :by_id, :using => :photo_id, :call => 'photos.getInfo', :authenticate? => true
+      
+      lazily_load :posted, :taken, :updated, :comment_count, :url, :description, :with => :load_info
+      
       has_many :images
 
+      # Upload the photo specified by <tt>filename</tt> to the user's Flickr account.  This
+      # call requires authentication.
+      #
+      def self.upload(filename)
+        response = Fleakr::Api::UploadRequest.with_response!(filename)
+        photo = Photo.new(response.body)
+        Photo.find_by_id(photo.id, :authenticate? => true)
+      end
+
+      # Replace the current photo's image with the one specified by filename.  This 
+      # call requires authentication.
+      #
+      def replace_with(filename)
+        response = Fleakr::Api::UploadRequest.with_response!(filename, :photo_id => self.id, :type => :update)
+        self.populate_from(response.body)
+        self
+      end
+
+      # TODO: Refactor this to remove duplication w/ User#load_info - possibly in the lazily_load class method
+      def load_info # :nodoc:
+        response = Fleakr::Api::MethodRequest.with_response!('photos.getInfo', :photo_id => self.id)
+        self.populate_from(response.body)
+      end
+
+      # When was this photo posted?
+      #
+      def posted_at
+        Time.at(posted.to_i)
+      end
+      
+      # When was this photo taken?
+      #
+      def taken_at
+        Time.parse(taken)
+      end
+      
+      # When was this photo last updated?  This includes addition of tags and other metadata.
+      #
+      def updated_at
+        Time.at(updated.to_i)
+      end
+
       # Create methods to access image sizes by name
       SIZES.each do |size|
         define_method(size) do

data/lib/fleakr/objects/search.rb

@@ -9,13 +9,10 @@ module Fleakr
 
       # 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
+        @results ||= begin
+          response = Fleakr::Api::MethodRequest.with_response!('photos.search', parameters)
+          (response.body/'rsp/photos/photo').map {|p| Photo.new(p) }
         end
-        @results
       end
 
       private

data/lib/fleakr/objects/set.rb

@@ -8,6 +8,7 @@ module Fleakr
     # [id] The ID for this photoset
     # [title] The title of this photoset
     # [description] The description of this set
+    # [count] Count of photos in this set
     # 
     # == Associations
     # 
@@ -19,26 +20,31 @@ module Fleakr
 
       has_many :photos, :using => :photoset_id
 
-      flickr_attribute :id, :attribute => 'id'
+      flickr_attribute :id
       flickr_attribute :title
       flickr_attribute :description
+      flickr_attribute :count, :from => '@photos'
 
       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
+      # Save all photos in this set to the specified directory for 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 
+      # <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|
+        self.photos.each_with_index do |photo, index|
           image = photo.send(size)
-          image.save_to(target) unless image.nil?
+          image.save_to(target, file_prefix(index)) unless image.nil?
         end
       end
+      
+      def file_prefix(index) # :nodoc:
+        sprintf("%0#{self.count.length}d_", (index + 1))
+      end
 
     end
   end

data/lib/fleakr/objects/user.rb

@@ -11,6 +11,7 @@ module Fleakr
     # [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)
+    # [location] This user's location (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
@@ -42,37 +43,24 @@ module Fleakr
 
       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'
+      flickr_attribute :id, :from => 'user@nsid'
+      flickr_attribute :username
+      flickr_attribute :name, :from => 'person/realname'
+      flickr_attribute :location
+      flickr_attribute :photos_url, :from => 'person/photosurl'
+      flickr_attribute :profile_url, :from => 'person/profileurl'
+      flickr_attribute :photos_count, :from => 'person/photos/count'
+      flickr_attribute :icon_server, :from => 'person@iconserver'
+      flickr_attribute :icon_farm, :from => 'person@iconfarm'
+      flickr_attribute :pro, :from => 'person@ispro'
+      flickr_attribute :admin, :from => 'person@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 :name, :photos_url, :profile_url, :photos_count, :location, :with => :load_info
       lazily_load :icon_server, :icon_farm, :pro, :admin, :with => :load_info
 
       scoped_search
@@ -97,7 +85,7 @@ module Fleakr
       end
       
       def load_info # :nodoc:
-        response = Fleakr::Api::Request.with_response!('people.getInfo', :user_id => self.id)
+        response = Fleakr::Api::MethodRequest.with_response!('people.getInfo', :user_id => self.id)
         self.populate_from(response.body)
       end
 

data/lib/fleakr/objects.rb

@@ -0,0 +1,9 @@
+require 'fleakr/objects/authentication_token'
+require 'fleakr/objects/contact'
+require 'fleakr/objects/error'
+require 'fleakr/objects/group'
+require 'fleakr/objects/image'
+require 'fleakr/objects/photo'
+require 'fleakr/objects/search'
+require 'fleakr/objects/set'
+require 'fleakr/objects/user'

data/lib/fleakr/support/attribute.rb

@@ -2,25 +2,43 @@ module Fleakr
   module Support # :nodoc:all
     class Attribute
 
-      attr_reader :name, :xpath, :attribute
+      # TODO: Refactor the location / attribute logic into a Source class
 
-      def initialize(name, options = {})
+      attr_reader :name, :sources
+
+      def initialize(name, sources = nil)
         @name = name.to_sym
-        @attribute = options[:attribute]
+        
+        @sources = Array(sources)
+        @sources << @name.to_s if @sources.empty?
+      end
+      
+      def split(source)
+        location, attribute = source.split('@')
+        location = self.name.to_s if location.blank?
+        
+        [location, attribute]
+      end
+      
+      def node_for(document, source)
+        document.at(location(source)) || document.search("//[@#{attribute(source)}]").first
+      end
 
-        @xpath = options[:xpath]
-        @xpath ||= @name.to_s unless @attribute
+      def attribute(source)
+        location, attribute = source.split('@')
+        attribute || location
+      end
+      
+      def location(source)
+        split(source).first
       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
+        values = sources.map do |source|
+          node = node_for(document, source)
+          (node.attributes[attribute(source)] || node.inner_text) unless node.nil?
         end
+        values.compact.first
       end
 
     end

data/lib/fleakr/support/object.rb

@@ -9,7 +9,7 @@ module Fleakr
         end
       
         def flickr_attribute(name, options = {})
-          self.attributes << Attribute.new(name, options)
+          self.attributes << Attribute.new(name, options[:from])
           class_eval "attr_accessor :#{name}"
         end
       
@@ -34,7 +34,7 @@ module Fleakr
         
           class_eval <<-CODE
             def self.find_all_#{condition}(value)
-              response = Fleakr::Api::Request.with_response!('#{options[:call]}', :#{attribute} => value)
+              response = Fleakr::Api::MethodRequest.with_response!('#{options[:call]}', :#{attribute} => value)
               (response.body/'rsp/#{options[:path]}').map {|e| #{target_class}.new(e) }
             end
           CODE
@@ -44,8 +44,10 @@ module Fleakr
           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)
+            def self.find_#{condition}(value, options = {})
+              options.merge!(:#{attribute} => value)
+              
+              response = Fleakr::Api::MethodRequest.with_response!('#{options[:call]}', options)
               #{self.name}.new(response.body)
             end
           CODE
@@ -60,6 +62,20 @@ module Fleakr
             end
           CODE
         end
+
+        def 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
       
       end
     

data/lib/fleakr/support.rb

@@ -0,0 +1,2 @@
+require 'fleakr/support/attribute'
+require 'fleakr/support/object'

data/lib/fleakr/version.rb

@@ -2,7 +2,7 @@ module Fleakr
   module Version # :nodoc:
     
     MAJOR = 0
-    MINOR = 3
+    MINOR = 4
     TINY  = 0
     
     def self.to_s

data/lib/fleakr.rb

@@ -6,13 +6,16 @@ require 'net/http'
 require 'rubygems'
 require 'hpricot'
 require 'activesupport'
+require 'md5'
 
-%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
+require 'fleakr/api'
+require 'fleakr/core_ext'
+require 'fleakr/support'
+require 'fleakr/objects'
 
-# = Fleakr: A teeny tiny gem to interface with Flickr
+# = Fleakr: A small, yet powerful, gem to interface with Flickr photostreams
+#
+# == Quick Start
 #
 # 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' 
@@ -36,10 +39,42 @@ end
 #  user.groups
 #
 # To see what other associations and attributes are available, see the Fleakr::Objects::User class
+# 
+# == Authentication
+#
+# If you want to do something more than just retrieve public photos (like upload your own), 
+# you'll need to generate an authentication token to use across requests and sessions.
+#
+# Assuming you've already applied for a key, go back and make sure you have the right settings
+# to get your auth token.  Click on the 'Edit key details' link and ensure that:
+#
+# 1. Your application description and notes are up-to-date
+# 1. The value for 'Authentication Type' is set to 'Mobile Application'
+# 1. The value for 'Mobile Permissions' is set to either 'write' or 'delete'
+#
+# Once this is set, you'll see your Authentication URL on the key details page (it will look
+# something like http://www.flickr.com/auth-534525246245).  Paste this URL into your browser and 
+# confirm access to get your mini-token. Now you're ready to make authenticated requests:
+#
+#   require 'rubygems'
+#   require 'fleakr'
+#
+#   Fleakr.api_key       = 'ABC123'
+#   Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
+#   Fleakr.mini_token    = '362-133-214'
+#
+#   Fleakr.upload('/path/to/my/photo.jpg')
+#   Fleakr.token.value # => "34132412341235-12341234ef34"
+# 
+# Once you use the mini-token once, it is no longer available.  To use the generated auth_token
+# for future requests, just set Fleakr.auth_token to the generated value.
 #
 module Fleakr
 
-  mattr_accessor :api_key
+  # Generic catch-all exception for any API errors
+  class ApiError < StandardError; end
+
+  mattr_accessor :api_key, :shared_secret, :mini_token, :auth_token
 
   # 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:
@@ -51,7 +86,7 @@ module Fleakr
   def self.user(user_data)
     begin
       Objects::User.find_by_username(user_data)
-    rescue Api::Request::ApiError
+    rescue ApiError
       Objects::User.find_by_email(user_data)
     end
   end
@@ -71,4 +106,28 @@ module Fleakr
     Objects::Search.new(params).results
   end
   
+  # Upload one or more files to your Flickr account (requires authentication).  Simply provide
+  # a filename or a pattern to upload one or more files:
+  #
+  #  Fleakr.upload('/path/to/my/mug.jpg')
+  #  Fleakr.upload('/User/Pictures/Party/*.jpg')
+  #
+  def self.upload(glob)
+    Dir[glob].each {|file| Fleakr::Objects::Photo.upload(file) }
+  end
+
+  # Get the authentication token needed for authenticated requests.  Will either use
+  # a valid auth_token (if available) or a mini-token to generate the auth_token.
+  #
+  def self.token
+    @token ||= begin
+      if !Fleakr.auth_token.nil?
+        Fleakr::Objects::AuthenticationToken.from_auth_token(Fleakr.auth_token)
+      else
+        Fleakr::Objects::AuthenticationToken.from_mini_token(Fleakr.mini_token)
+      end
+    end
+  end
+
+  
 end

data/test/fixtures/auth.checkToken.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<rsp stat="ok">
+<auth>
+	<token>abc-123</token>
+	<perms>delete</perms>
+	<user nsid="31066442@N69" fullname="Sir Froot Pants" username="frootpantz"></user>
+</auth>
+</rsp>

data/test/fixtures/auth.getFullToken.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<rsp stat="ok">
+<auth>
+	<token>abc-123</token>
+	<perms>delete</perms>
+	<user nsid="31066442@N69" fullname="Sir Froot Pants" username="frootpantz"></user>
+</auth>
+</rsp>

data/test/fixtures/people.getInfo.xml

@@ -4,7 +4,7 @@
   	<username>frootpantz</username>
   	<realname>Sir Froot Pantz</realname>
   	<mbox_sha1sum>e52ed1e5b91c763694995460e9796fc2adc02019</mbox_sha1sum>
-  	<location />
+  	<location>The Moon</location>
   	<photosurl>http://www.flickr.com/photos/frootpantz/</photosurl>
   	<profileurl>http://www.flickr.com/people/frootpantz/</profileurl>
   	<mobileurl>http://m.flickr.com/photostream.gne?id=34225</mobileurl>

data/test/fixtures/photos.getInfo.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<rsp stat="ok">
+  <photo id="1" secret="secret" server="3085" farm="4" dateuploaded="1230274722" isfavorite="0" license="0" rotation="0" originalsecret="sekrit" originalformat="jpg" media="photo">
+    <owner nsid="31066442@N69" username="frootpantz" realname="" location="" />
+    <title>Tree</title>
+    <description>A Tree</description>
+    <visibility ispublic="1" isfriend="0" isfamily="0" />
+    <dates posted="1230274722" taken="2008-12-25 18:26:55" takengranularity="0" lastupdate="1230276652" />
+
+    <editability cancomment="0" canaddmeta="0" />
+    <usage candownload="1" canblog="0" canprint="0" />
+    <comments>0</comments>
+    <notes />
+    <tags />
+    <urls>
+      <url type="photopage">http://www.flickr.com/photos/yes/1</url>
+    </urls>
+
+  </photo>
+</rsp>

data/test/test_helper.rb

@@ -9,6 +9,19 @@ require File.dirname(__FILE__) + '/../lib/fleakr'
 
 class Test::Unit::TestCase
 
+  def self.should_autoload_when_accessing(*attributes)
+    options = attributes.extract_options!
+    attributes.each do |accessor_name|
+      it "should load the additional user information when accessing the :#{accessor_name} attribute" do
+        klass = self.class.name.sub(/Test$/, '').constantize
+              
+        object = klass.new
+        object.expects(options[:with]).with()
+        object.send(accessor_name)
+      end
+    end
+  end
+
   def self.should_have_a_value_for(attribute_test)
     it "should have a value for :#{attribute_test.keys.first}" do
       @object.send(attribute_test.keys.first).should == attribute_test.values.first
@@ -64,12 +77,14 @@ class Test::Unit::TestCase
     klass       = "Fleakr::Objects::#{class_name}".constantize
     object_type = class_name.downcase    
 
+    condition_value = '1'
+
     options[:with] = options[:by] if options[:with].nil?
+    params = {options[:with] => condition_value}
 
     it "should be able to find a #{thing} by #{options[:by]}" do
-      condition_value = '1'
       stub = stub()
-      response = mock_request_cycle :for => options[:call], :with => {options[:with] => condition_value}
+      response = mock_request_cycle :for => options[:call], :with => params
 
       klass.expects(:new).with(response.body).returns(stub)
       klass.send("find_by_#{options[:by]}".to_sym, condition_value).should == stub
@@ -108,7 +123,7 @@ class Test::Unit::TestCase
   
   def mock_request_cycle(options)
     response = stub(:body => Hpricot.XML(read_fixture(options[:for])))
-    Fleakr::Api::Request.expects(:with_response!).with(options[:for], options[:with]).returns(response)
+    Fleakr::Api::MethodRequest.expects(:with_response!).with(options[:for], options[:with]).returns(response)
     
     response
   end

data/test/unit/fleakr/api/file_parameter_test.rb

@@ -0,0 +1,63 @@
+require File.dirname(__FILE__) + '/../../../test_helper'
+
+module Fleakr::Api
+  class FileParameterTest < Test::Unit::TestCase
+    
+    describe "An instance of the FileParameter class" do
+      
+      before do
+        @temp_dir = File.expand_path(create_temp_directory)
+        @filename = "#{@temp_dir}/image.jpg"
+      end
+      
+      after do
+        FileUtils.rm_rf(@temp_dir)
+      end
+      
+      it "should know not to include itself in the parameter signature" do
+        parameter = FileParameter.new('photo', @filename)
+        parameter.include_in_signature?.should be(false)
+      end
+      
+      {'jpg' => 'image/jpeg', 'png' => 'image/png', 'gif' => 'image/gif'}.each do |ext, mime_type|
+        it "should know the correct MIME type for an extension of #{ext}" do
+          parameter = FileParameter.new('photo', "#{@temp_dir}/image.#{ext}")
+          parameter.mime_type.should == mime_type
+        end
+      end
+      
+      it "should retrieve the contents of the file when accessing the value" do
+        File.expects(:read).with(@filename).returns('bopbip')
+        
+        parameter = FileParameter.new('photo', @filename)
+        parameter.value.should == 'bopbip'
+      end
+      
+      it "should cache the file contents after retrieving them" do
+        File.expects(:read).with(@filename).once.returns('bopbip')
+        
+        parameter = FileParameter.new('photo', @filename)
+        2.times { parameter.value }
+      end
+      
+      it "should know how to generate a form representation of itself" do
+        filename  = 'image.jpg'
+        mime_type = 'image/jpeg'
+
+        parameter = FileParameter.new('photo', filename)
+        parameter.stubs(:mime_type).with().returns(mime_type)
+        parameter.stubs(:value).with().returns('data')
+        
+        expected = 
+          "Content-Disposition: form-data; name=\"photo\"; filename=\"#{filename}\"\r\n" +
+          "Content-Type: image/jpeg\r\n" +
+          "\r\n" +
+          "data\r\n"
+        
+        parameter.to_form.should == expected
+      end
+      
+    end
+    
+  end
+end