reagent-fleakr 0.3.0 → 0.4.0

data/README.rdoc

@@ -2,7 +2,7 @@
 
 == Description
 
-A teeny tiny gem to interface with Flickr photostreams
+A small, yet powerful, gem to interface with Flickr photostreams
 
 == Installation
 
@@ -22,16 +22,24 @@ Or ...
 
 == Usage
 
-Before doing anything, require the library:
+To get started, you'll need to grab an API key from Flickr to at least perform any of
+the non-authenticated, read-only calls.  Head on over to the Flickr site to grab one, I'll
+be here when you get back: http://www.flickr.com/services/api/misc.api_keys.html
 
-    >> require 'rubygems'
-    >> require 'fleakr'
+Now that you have your key, you can get things rolling with irb and the fleakr gem:
 
+    $ irb -r rubygems
+    >> require 'fleakr'
+    
 Then, set your API key (only need to do this once per session):
 
     >> Fleakr.api_key = '<your api key here>'
-    
-Find a user by username:
+
+=== A Brief Tour
+
+With just an API key, you have the ability to retrieve a substantial amount of data 
+about users, their photosets, photos, contacts, and groups.  Let's start by finding a 
+user by his username:
 
     >> user = Fleakr.user('the decapitator')
     => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">
@@ -47,13 +55,18 @@ Once you have a user, you can find his associated sets:
     => [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">, 
         #<Fleakr::Objects::Set:0x66d898 @title="londonpaper hijack", ...
 
+His individual photos:
+
+    >> user.photos.first
+    => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
+
 Or contacts:
 
     >> user.contacts.first
     => #<Fleakr::Objects::User:0x19039bc @username=".schill",
         @id="12289718@N00", @icon_farm="1", @icon_server="4">
 
-Or groups if you would like:
+Or his groups if you would like:
     
     >> user.groups
     => [#<Fleakr::Objects::Group:0x11f2330 ..., 
@@ -65,7 +78,7 @@ Or groups if you would like:
 
 Groups also contain photos:
 
-    >> u.groups.last.photos.first.title
+    >> user.groups.last.photos.first.title
     => "Welcome To The Machine"
 
 When accessing a set, you can also grab all the photos that are in that set:
@@ -77,20 +90,59 @@ When accessing a set, you can also grab all the photos that are in that set:
     >> user.sets.first.photos.first.title
     => "Untitled1"
     
+=== Photos
+
+Each photo object contains metadata about a collection of images, each representing different
+sizes.  Once we have a single photo:
+    
+    >> photo = user.photos.first
+    => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
+    
+We can get information about one of the sizes:
+
+    >> photo.small
+    => #<Fleakr::Objects::Image:0x1768f1c @height="172", @size="Small", @width="240",
+        @url="http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg",  
+        @page="http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/">
+
+Grab the URL for the image itself:
+
+    >> photo.small.url
+    => "http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg"
+    
+Or grab the URL for its page on the Flickr site:
+    
+    >> photo.small.page
+    => "http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/"
+    
+Other sizes are available (:square, :thumbnail, :small, :medium, :large, :original) and
+are accessed in the same way:
+    
+    >> photo.original.url
+    => "http://farm4.static.flickr.com/3250/2924549350_1cf67c2d47_o.jpg"    
+
+=== Saving Images
+
 If a photo interests you, save it down to a directory of your choosing:
 
-    >> user.sets.first.photos.first.small.save_to('/tmp')
-    => #<File:/tmp/2117922283_715587b2cb_m.jpg (closed)>
+    >> photo.original.save_to('/tmp')
+    => #<File:/tmp/2924549350_1cf67c2d47_o.jpg (closed)>
     
-If you can't decide on a photo and would rather just save the whole set, specify the target directory 
-and the size of the images you're interested in:
+Similarly, you can save down entire sets.  Just specify the target directory and the size 
+of the images you're interested in:
 
     >> user.sets.first.save_to('/tmp', :square)
     => [#<Fleakr::Objects::Photo:0x1187a1c @secret="715587b2cb" ...
+    
+This creates a subdirectory within the target directory based on the set's name and preserves
+the original order of the photos:
+    
     >> Dir["/tmp/#{user.sets.first.title}/*.jpg"].map
-    => ["/tmp/The Decapitator/2117919621_8b2d601bff_s.jpg", 
-        "/tmp/The Decapitator/2117921045_5fb15eff90_s.jpg", 
-        "/tmp/The Decapitator/2117922283_715587b2cb_s.jpg", ...
+    => ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg", 
+        "/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg", 
+        "/tmp/The Decapitator/03_2118696542_8af5763bde_s.jpg", ... ]
+
+=== Searching
 
 If you would prefer to just search photos, you can do that with search text:
 
@@ -116,13 +168,56 @@ Searches can also be scoped to other entities in the system (namely Users and Gr
     >> user.search('serpent')
     => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
         @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]
-        
-== TODO
 
-* Implement remaining bits of person, photoset, and photo-releated APIs
+=== Authenticated Calls & Uploads
+
+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 
+own photos).  
+
+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.
+
+== Roadmap / TODO
+
+=== 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
-* Lazily load attributes for objects that need to be accessed via secondary API call
-        
+
+=== 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
+
 == License
 
 Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com)

data/Rakefile

@@ -12,7 +12,7 @@ spec = Gem::Specification.new do |s|
   s.has_rdoc         = true
   s.extra_rdoc_files = %w(README.rdoc)
   s.rdoc_options     = %w(--main README.rdoc)
-  s.summary          = "A teeny tiny gem to interface with Flickr photostreams"
+  s.summary          = "A small, yet powerful, gem to interface with Flickr photostreams"
   s.author           = 'Patrick Reagan'
   s.email            = 'reaganpr@gmail.com'
   s.homepage         = 'http://sneaq.net'

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/lib/fleakr/api.rb

@@ -0,0 +1,7 @@
+require "fleakr/api/response"
+require "fleakr/api/method_request"
+require "fleakr/api/upload_request"
+require "fleakr/api/parameter_list"
+require "fleakr/api/parameter"
+require "fleakr/api/value_parameter"
+require "fleakr/api/file_parameter"

data/lib/fleakr/api/file_parameter.rb

@@ -0,0 +1,47 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = FileParameter
+    #
+    # Parameter class to encapsulate file data sent to the Flickr upload API
+    #
+    class FileParameter < Parameter
+      
+      MIME_TYPES = {
+        '.jpg' => 'image/jpeg',
+        '.png' => 'image/png',
+        '.gif' => 'image/gif'
+      }
+      
+      # Create a parameter with name and specified filename
+      #
+      def initialize(name, filename)
+        @filename = filename
+        super(name, false)
+      end
+      
+      # Discover MIME type by file extension using MIME_TYPES constant
+      #
+      def mime_type
+        MIME_TYPES[File.extname(@filename)]
+      end
+      
+      # File data (from @filename) to pass to the Flickr API
+      # 
+      def value
+        @value ||= File.read(@filename)
+      end
+      
+      # Generate a form representation of this file for upload (as multipart/form-data)
+      #
+      def to_form
+        "Content-Disposition: form-data; name=\"#{self.name}\"; filename=\"#{@filename}\"\r\n" +
+        "Content-Type: #{self.mime_type}\r\n" +
+        "\r\n" +
+        "#{self.value}\r\n"
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/api/method_request.rb

@@ -0,0 +1,57 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    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
+      #
+      def self.with_response!(method, additional_parameters = {})
+        request = self.new(method, additional_parameters)
+        response = request.send
+
+        raise(Fleakr::ApiError, "Code: #{response.error.code} - #{response.error.message}") if response.error?
+
+        response
+      end
+      
+      # Create a new request for the specified API method and pass along any additional
+      # parameters.  The Flickr API uses namespacing for its methods - this is optional
+      # when calling this method.
+      #
+      # This must be called after initializing the library with the required API key
+      # 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.
+      #
+      def initialize(method, additional_parameters = {})
+        @parameters = ParameterList.new(additional_parameters)
+        
+        self.method = method
+      end
+   
+      def method=(method) # :nodoc:
+        @method = method.sub(/^(flickr\.)?/, 'flickr.')
+        @parameters << ValueParameter.new('method', @method)
+      end
+
+      def send # :nodoc:
+        Response.new(Net::HTTP.get(endpoint_uri))
+      end
+      
+      private
+      def endpoint_uri
+        uri = URI.parse('http://api.flickr.com/services/rest/')
+        uri.query = self.parameters.to_query
+        uri
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/api/parameter.rb

@@ -0,0 +1,35 @@
+module Fleakr
+  module Api # :nodoc:
+
+    # = Parameter
+    # 
+    # Base class for other parameters that get passed to the Flickr API - see
+    # #FileParameter and #ValueParameter for examples
+    #
+    class Parameter
+     
+      attr_reader :name
+     
+      # A new named parameter (never used directly)
+      #
+      def initialize(name, include_in_signature = true)
+        @name                 = name
+        @include_in_signature = include_in_signature
+      end
+      
+      # Should this parameter be used when generating the signature?
+      #
+      def include_in_signature?
+        (@include_in_signature == true) ? true : false
+      end
+      
+      # Used for sorting when generating a signature
+      #
+      def <=>(other)
+        self.name <=> other.name
+      end
+      
+    end
+    
+  end
+end