mwilliams-fleakr 0.5.1

data/README.rdoc

@@ -0,0 +1,350 @@
+= Fleakr
+
+== Description
+
+A small, yet powerful, gem to interface with Flickr photostreams
+
+== Installation
+
+=== Stable
+
+    sudo gem install fleakr
+
+=== Bleeding Edge
+
+    sudo gem install reagent-fleakr --source=http://gems.github.com
+    
+Or ...
+
+    $ git clone git://github.com/reagent/fleakr.git
+    $ cd fleakr
+    $ rake gem && sudo gem install pkg/fleakr-<version>.gem
+
+== Usage
+
+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
+
+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>'
+
+=== 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">
+
+Or by email:
+
+    >> user = Fleakr.user('user@host.com')
+    => #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00">
+
+Once you have a user, you can find his associated sets:
+
+    >> user.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 his groups if you would like:
+    
+    >> user.groups
+    => [#<Fleakr::Objects::Group:0x11f2330 ..., 
+        #<Fleakr::Objects::Group:0x11f2308 ...
+    >> user.groups.first.name
+    => "Rural Decay"
+    >> user.groups.first.id
+    => "14581414@N00"
+
+Groups also contain photos:
+
+    >> 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:
+
+    >> user.sets.first
+    => #<Fleakr::Objects::Set:0x1195bbc @title="The Decapitator", @id="72157603480986566", @description="">
+    >> user.sets.first.photos.first
+    => #<Fleakr::Objects::Photo:0x1140108 ... >
+    >> 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"
+    
+=== Tags
+
+Tags are available for users and photos.  Retrieving them is easy:
+
+    >> user = Fleakr.user('the decapitator')
+    >> user.tags
+    => [#<Fleakr::Objects::Tag:0x190d5fc @value="ad">, 
+        #<Fleakr::Objects::Tag:0x1908a20 @value="ads">, ...
+    >> user.photos.first.tags
+    => [#<Fleakr::Objects::Tag:0x17b1b18 @machine_flag="0", @author_id="21775151@N06", ...
+
+All tags have values, but for tags associated with photos there is some additional information:
+
+    >> tag = user.photos.first.tags.first
+    >> tag.id
+    => "21729829-3263659141-427098"
+    >> tag.raw
+    => "decapitator"
+    >> tag.value
+    => "decapitator"
+    >> tag.to_s
+    => "decapitator"
+    >> tag.machine?
+    => false
+    >> tag.author
+    => #<Fleakr::Objects::User:0x1a149f0 @username="the decapitator", ... >
+    
+Each tag can also have related tags:
+
+    >> user.photos.first.tags[1].related.first.related.first.to_s
+    => "face"
+    
+You get the idea - see Fleakr::Objects::Tag for more information.
+
+=== Comments
+
+Similar to tags, photosets and photos can each have comments:
+
+    >> user.sets.first.comments
+    => [#<Fleakr::Objects::Comment:0x19795cc ...
+    >> user.photos.first.comments
+    => [#<Fleakr::Objects::Comment:0x17bf0b0 @body="Dayum, that's some wishful thinking!" ...
+
+All comments have additional information:
+
+    >> comment = user.photos.first.comments.first
+    >> comment.id
+    => "21729829-3263659141-72157613553885978"
+    >> comment.body
+    => "Dayum, that's some wishful thinking!"
+    >> comment.to_s
+    => "Dayum, that's some wishful thinking!"
+    >> comment.url
+    => "http://www.flickr.com/photos/the_decapitator/3263659141/#comment72157613553885978"
+    >> comment.author
+    => #<Fleakr::Objects::User:0x178e3d4 @username="jaspertandy", ... >
+
+See Fleakr::Objects::Comment for more information.
+
+=== Saving Images
+
+If a photo interests you, save it down to a directory of your choosing:
+
+    >> photo.original.save_to('/tmp')
+    => #<File:/tmp/2924549350_1cf67c2d47_o.jpg (closed)>
+    
+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/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:
+
+    >> photos = Fleakr.search('ponies!!')
+    => [#<Fleakr::Objects::Photo:0x11f4e64 @title="hiroshima atomic garden", @id="3078234390">, 
+        #<Fleakr::Objects::Photo:0x11f4928 @title="PONYLOV", @id="3077360853">, ...
+    >> photos.first.title
+    => "hiroshima atomic garden"
+
+You can also search based on tags:
+
+    >> photos = Fleakr.search(:tags => 'macro')
+    >> photos.first.title
+    => "Demure"
+    >> photos.first.id
+    => "3076049945"
+
+Searches can also be scoped to other entities in the system (namely Users and Groups):
+
+    >> user.groups.first.search('awesome')
+    => [#<Fleakr::Objects::Photo:0x18cb4cc @server_id="2012", @id="2181921273",
+         @farm_id="3", @title="", @secret="634eda7521">, ... 
+    >> user.search('serpent')
+    => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
+        @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]
+
+=== 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 
+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.  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?
+
+Because so much of the underlying API is hidden under the covers, it's often tough to know
+what's really going on when you run into unexpected behavior.  To make things easier, you can
+have Fleakr log all of the API traffic.  Here's how:
+
+    Fleakr.logger = Logger.new('/tmp/fleakr.log')
+    
+Now any calls to the API will log both their request and response data to that file.  But be 
+warned, this can be pretty verbose by default (especially if you're doing file uploads).  To see
+just the requests you need to tune the log level:
+
+    logger = Logger.new('/tmp/fleakr.log')
+    logger.level = Logger::INFO
+    
+    Fleakr.logger = logger
+    
+Even if something doesn't go wrong, this is a good way to get a sense for when you're making
+API requests.
+
+== Roadmap / TODO
+
+=== 0.4.x
+
+* Implement remaining bits of person and photo-related API calls (read-only)
+
+=== 0.5.x
+
+* Implement asynchronous file upload / replacement w/ ticket checking
+* 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
+
+Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,41 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/fleakr/version'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'fleakr'
+  s.version          = Fleakr::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  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'
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
+  
+  s.add_dependency('hpricot', '~> 0.8.1')
+  s.add_dependency('activesupport', '~> 2.0')
+  s.add_dependency('loggable', '~> 0.2.0')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end

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,66 @@
+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 
+      # 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.  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)
+        
+        self.method = method
+      end
+   
+      def method=(method) # :nodoc:
+        @method = method.sub(/^(flickr\.)?/, 'flickr.')
+        @parameters << ValueParameter.new('method', @method)
+      end
+
+      def send # :nodoc:
+        logger.info("Sending request to: #{endpoint_uri}")
+        response_xml = Net::HTTP.get(endpoint_uri)
+        logger.debug("Response data:\n#{response_xml}")
+        
+        Response.new(response_xml)
+      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/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        then 1
+          when :moderate    then 2
+          when :restricted  then 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       then 1
+          when :screenshot  then 2
+          when :other       then 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