fleakr 0.4.1 → 0.4.2

data/README.rdoc

@@ -169,7 +169,33 @@ Searches can also be scoped to other entities in the system (namely Users and Gr
     => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
         @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]
 
-=== Authenticated Calls & Uploads
+=== Uploading Files
+
+Before you can upload files, you need to be able to make authenticated calls to the Flickr 
+API.  Skip to the next section (Authenticated Calls) for details on how to make this work.
+
+Uploading single files is simple:
+
+    >> Fleakr.upload('/path/to/image.jpg')
+    => [#<Fleakr::Objects::Photo:0x217fb54 @updated="1236133594", @server_id="3266", ...>]
+    
+Notice that the newly-uploaded image is returned.  You can further inspect / modify this as
+necessary.  The real magic is in uploading multiple files - the upload method takes a file
+glob:
+
+    >> Fleakr.upload('/path/to/images/*.jpg')
+    => [#<Fleakr::Objects::Photo:0x217faa0 ...>,
+        #<Fleakr::Objects::Photo:0x212fb18 ...>,
+        #<Fleakr::Objects::Photo:0x20e09c8 ...>]
+
+You can also set options on the file(s) that you're uploading:
+
+    >> Fleakr.upload('/path/to/party/images/*.jpg', :viewable_by => :everyone, 
+                                                    :title => 'Party Pics')
+
+The full list of options can be found in the Fleakr::Objects::Photo documentation.
+
+=== Authenticated Calls
 
 While read-only access to the API gets you quite a bit of data, you'll need to generate an
 authentication token if you want access to the more powerful features (like uploading your 
@@ -197,7 +223,9 @@ confirm access to get your mini-token. Now you're ready to make authenticated re
     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.
+for future requests, just set Fleakr.auth_token to the generated value.  Similarly, if you have
+an authenticated frob from Flickr (using authentication for desktop applications, for example)
+you can also set <tt>Fleakr.frob</tt> to the frob value returned from the API.
 
 === What Went Wrong?
 
@@ -223,20 +251,19 @@ API requests.
 
 === 0.4.x
 
-* Allow passing of parameters to file uploads to allow for access control / naming
 * Implement remaining bits of person and photo-related API calls (read-only)
-* Automatically sign all calls (if we have a secret), authenticate all calls (if we have a token)
 
 === 0.5.x
 
 * Implement asynchronous file upload / replacement w/ ticket checking
-* Provide a better searching interface
+* Provide a better searching interface with ruby-like option syntax
 
 === Future
 
 * Implement save-able search results (e.g. Fleakr.search('ponies').save_to('/path', :medium))
 * Implement deeper associations for core elements (e.g. tags / etc..)
 * Implement write methods for photos & photosets
+* Implement flickr.places.* portion of API 
 
 == License
 

data/Rakefile

@@ -19,7 +19,7 @@ spec = Gem::Specification.new do |s|
   s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
   
   s.add_dependency('hpricot', '~> 0.6.0')
-  s.add_dependency('activesupport', '~> 2.2.0')
+  s.add_dependency('activesupport', '~> 2.0')
   s.add_dependency('loggable', '~> 0.2.0')
 end
 

data/lib/fleakr.rb

@@ -5,7 +5,15 @@ require 'uri'
 require 'cgi'
 require 'net/http'
 require 'hpricot'
-require 'activesupport'
+
+# Require only what we need from ActiveSupport
+require 'active_support/core_ext/array'
+require 'active_support/core_ext/module'
+require 'active_support/core_ext/blank'
+require 'active_support/core_ext/time'
+require 'active_support/inflector'
+require 'active_support/core_ext/string'
+
 require 'md5'
 require 'loggable'
 
@@ -75,7 +83,7 @@ module Fleakr
   # Generic catch-all exception for any API errors
   class ApiError < StandardError; end
 
-  mattr_accessor :api_key, :shared_secret, :mini_token, :auth_token
+  mattr_accessor :api_key, :shared_secret, :mini_token, :auth_token, :frob
 
   # 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:
@@ -113,8 +121,12 @@ module Fleakr
   #  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) }
+  # Additionally, options can be supplied as part of the upload that will apply to all files
+  # that are matched by the pattern passed to <tt>glob</tt>.  For a full list, see 
+  # Fleakr::Objects::Photo.
+  #
+  def self.upload(glob, options = {})
+    Dir[glob].map {|file| Fleakr::Objects::Photo.upload(file, options) }
   end
 
   # Get the authentication token needed for authenticated requests.  Will either use
@@ -122,13 +134,29 @@ module Fleakr
   #
   def self.token
     @token ||= begin
-      if !Fleakr.auth_token.nil?
+      if Fleakr.auth_token
         Fleakr::Objects::AuthenticationToken.from_auth_token(Fleakr.auth_token)
-      else
+      elsif Fleakr.frob
+        Fleakr::Objects::AuthenticationToken.from_frob(Fleakr.frob)
+      elsif Fleakr.mini_token
         Fleakr::Objects::AuthenticationToken.from_mini_token(Fleakr.mini_token)
       end
     end
   end
+  
+  # Reset the cached token whenever setting a new value for the mini_token, auth_token, or frob
+  #
+  [:mini_token, :auth_token, :frob].each do |attribute|
+    class_eval <<-ACCESSOR
+      def self.#{attribute}=(#{attribute})
+        reset_token
+        @@#{attribute} = #{attribute}
+      end
+    ACCESSOR
+  end
 
+  def self.reset_token # :nodoc: #
+    @token = nil
+  end
   
 end

data/lib/fleakr/api.rb

@@ -1,5 +1,6 @@
 require "fleakr/api/response"
 require "fleakr/api/method_request"
+require "fleakr/api/option"
 require "fleakr/api/upload_request"
 require "fleakr/api/parameter_list"
 require "fleakr/api/parameter"

data/lib/fleakr/api/method_request.rb

@@ -1,12 +1,17 @@
 module Fleakr
   module Api # :nodoc:
     
+    # = MethodRequest
+    # 
+    # Handles all API requests that are non-upload related.  For upload requests see the
+    # UploadRequest class.
+    #
     class MethodRequest
       attr_reader :parameters, :method
       
       # Makes a request to the Flickr API and returns a valid Response object.  If
       # there are errors on the response it will raise an ApiError exception.  See 
-      # #Fleakr::Api::MethodRequest.new for details about the additional parameters
+      # MethodRequest#new for details about the additional parameters
       #
       def self.with_response!(method, additional_parameters = {})
         request = self.new(method, additional_parameters)
@@ -25,9 +30,9 @@ module Fleakr
       # see (#Fleakr.api_key=)
       #
       # The <tt>additional_parameters</tt> is a list of parameters to pass directly to 
-      # the Flickr API call.  Exceptions to this are the <tt>:sign?</tt> and 
-      # <tt>:authenticate?</tt> options that determine if the call should be signed or
-      # authenticated.
+      # the Flickr API call.  The exception to this is the <tt>:authenticate?</tt> option
+      # that will force the call to not be authenticated if it is set to false (The default
+      # behavior is to authenticate all calls when we have a token).
       #
       def initialize(method, additional_parameters = {})
         @parameters = ParameterList.new(additional_parameters)

data/lib/fleakr/api/option.rb

@@ -0,0 +1,175 @@
+module Fleakr
+  module Api # :nodoc:
+
+    # = Option
+    #
+    # Top-level class for creating specific option instances based on type
+    #
+    class Option
+      
+      MAPPING = {
+        :tags        => 'TagOption',
+        :viewable_by => 'ViewOption',
+        :level       => 'LevelOption',
+        :type        => 'TypeOption',
+        :hide?       => 'HiddenOption'
+      }
+      
+      # Initialize a new option for the specified type and value
+      #
+      def self.for(type, value)
+        class_for(type).new(type, value)
+      end
+      
+      def self.class_for(type) # :nodoc:
+        class_name = MAPPING[type] || 'SimpleOption'
+        "Fleakr::Api::#{class_name}".constantize
+      end
+      
+    end
+    
+    # = SimpleOption
+    # 
+    # Simple name / value option pair
+    #
+    class SimpleOption
+
+      attr_reader :type, :value
+     
+      # Create an option of the specified type and value
+      #
+      def initialize(type, value)
+        @type  = type
+        @value = value
+      end
+      
+      # Generate hash representation of this option
+      #
+      def to_hash
+        {type => value}
+      end
+      
+    end
+    
+    # = TagOption
+    #
+    # Represents values for tags
+    #
+    class TagOption < SimpleOption
+      
+      # Tag with specified values.  Value passed will be converted to an array if it isn't
+      # already
+      # 
+      def initialize(type, value)
+        super type, value
+        @value = Array(self.value)
+      end
+    
+      # Hash representation of tag values (separated by spaces).  Handles multi-word tags 
+      # by enclosing each tag in double quotes.
+      #
+      def to_hash
+        tags = value.map {|tag| "\"#{tag}\"" }
+        {type => tags.join(' ')}
+      end
+      
+    end
+    
+    # = ViewOption
+    #
+    # Specify who is able to view the photo.
+    #
+    class ViewOption < SimpleOption
+      
+      # Specify who this is viewable by (e.g. everyone / friends / family).
+      #
+      def initialize(type, value)
+        super type, Array(value)
+      end
+      
+      # Is this publicly viewable? (i.e. :everyone)
+      #
+      def public?
+        value == [:everyone]
+      end
+      
+      # Is this viewable by friends? (i.e. :friends)
+      #
+      def friends?
+        value.include?(:friends)
+      end
+
+      # Is this viewable by family? (i.e. :family)
+      #
+      def family?
+        value.include?(:family)
+      end
+      
+      # Hash representation of photo permissions
+      #
+      def to_hash
+        {:is_public => public?.to_i, :is_friend => friends?.to_i, :is_family => family?.to_i}
+      end
+      
+    end
+    
+    # = LevelOption
+    #
+    # Specify the "safety level" of this photo (e.g. safe / moderate / restricted)
+    #
+    class LevelOption < SimpleOption
+     
+      def value # :nodoc: 
+        case @value
+          when :safe: 1
+          when :moderate: 2
+          when :restricted: 3
+        end
+      end
+      
+      # Hash representation of the safety_level for this photo
+      #
+      def to_hash
+        {:safety_level => value}
+      end
+      
+    end
+    
+    # = TypeOption
+    #
+    # Specify the type of this photo (e.g. photo / screenshot / other)
+    #
+    class TypeOption < SimpleOption
+      
+      def value # :nodoc:
+        case @value
+          when :photo: 1
+          when :screenshot: 2
+          when :other: 3
+        end
+      end
+      
+      # Hash representation of this type
+      #
+      def to_hash
+        {:content_type => value}
+      end
+      
+    end
+    
+    # = HiddenOption
+    #
+    # Specify whether this photo should be hidden from search
+    #
+    class HiddenOption < SimpleOption
+     
+      # Hash representation of whether to hide this photo
+      #
+      def to_hash
+        {:hidden => (value ? 2 : 1)}
+      end
+      
+    end
+
+  end
+end

data/lib/fleakr/api/parameter_list.rb

@@ -10,8 +10,8 @@ module Fleakr
     class ParameterList
       
       # Create a new parameter list with optional parameters:
-      # [:sign?] Will these parameters be used to sign the request?
-      # [:authenticate?] Will the request need to be authenticated?
+      # [:authenticate?] Request will automatically be authenticated if Fleakr.token is available
+      #                  set this to false to force it not to authenticate
       #
       # Any additional name / value pairs will be created as individual 
       # ValueParameters as part of the list.  Example:
@@ -22,7 +22,8 @@ module Fleakr
       #   => #<Fleakr::Api::ValueParameter:0x1656da4 @include_in_signature=true, @name="foo", @value="bar">
       #
       def initialize(options = {})
-        @api_options = options.extract!(:sign?, :authenticate?)
+        # TODO: need to find a way to move the unexpected behavior in Fleakr.token elsewhere
+        @api_options = options.extract!(:authenticate?)
         
         @list = Hash.new
 
@@ -41,13 +42,13 @@ module Fleakr
       # Should this parameter list be signed?
       #
       def sign?
-        (@api_options[:sign?] == true || authenticate?) ? true : false
+        !Fleakr.shared_secret.blank?
       end
       
       # Should we send the auth_token with the request?
       #
       def authenticate?
-        (@api_options[:authenticate?] == true) ? true : false
+        @api_options.has_key?(:authenticate?) ? @api_options[:authenticate?] : !Fleakr.token.blank?
       end
       
       # Access an individual parameter by key (symbol or string)
@@ -64,7 +65,7 @@ module Fleakr
       # list - e.g. <tt>foo=bar&blee=baz</tt>
       #
       def to_query
-        list.values.map(&:to_query).join('&')
+        list.values.map {|element| element.to_query }.join('&')
       end
       
       # Generate the form representation of this parameter list including the

data/lib/fleakr/api/upload_request.rb

@@ -19,8 +19,8 @@ module Fleakr
       # a Fleakr::ApiError with the reason for the error.  See UploadRequest#new for more 
       # details.
       #
-      def self.with_response!(filename, options = {})
-        request = self.new(filename, options)
+      def self.with_response!(filename, type = :create, options = {})
+        request = self.new(filename, type, options)
         response = request.send
         
         raise(Fleakr::ApiError, "Code: #{response.error.code} - #{response.error.message}") if response.error?
@@ -28,21 +28,27 @@ module Fleakr
         response
       end
       
-      # Create a new UploadRequest with the specified filename and options:
+      # Create a new UploadRequest with the specified filename, type, and options.  Type
+      # is one of <tt>:create</tt> or <tt>:update</tt> to specify whether we are saving a new
+      # image or replacing an existing one.  
       #
-      # [:type] Valid values are :create and :update and are used when uploading new 
-      #         photos or replacing existing ones
+      # For a list of available options, see the documentation in Fleakr::Objects::Photo
       #
-      def initialize(filename, options = {})
-        type_options = options.extract!(:type)
-        options.merge!(:authenticate? => true)
+      def initialize(filename, type = :create, options = {})
+        @type    = type
+        @options = options
         
-        @type = type_options[:type] || :create
-        
-        @parameters = ParameterList.new(options)
+        @parameters = ParameterList.new(upload_options)
         @parameters << FileParameter.new('photo', filename)
       end
       
+      # A list of upload options for this upload request (see Fleakr::Api::Option)
+      #
+      def upload_options
+        option_list = @options.map {|key, value| Option.for(key, value) }
+        option_list.inject({}) {|hash, option| hash.merge(option.to_hash)}
+      end
+      
       def headers # :nodoc:
         {'Content-Type' => "multipart/form-data; boundary=#{self.parameters.boundary}"}
       end