fleakr 0.3.0

data/README.rdoc

@@ -0,0 +1,149 @@
+= Fleakr
+
+== Description
+
+A teeny tiny 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
+
+Before doing anything, require the library:
+
+    >> require '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:
+
+    >> 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", ...
+
+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:
+    
+    >> 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"
+    
+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)>
+    
+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:
+
+    >> user.sets.first.save_to('/tmp', :square)
+    => [#<Fleakr::Objects::Photo:0x1187a1c @secret="715587b2cb" ...
+    >> 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", ...
+
+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">]
+        
+== TODO
+
+* Implement remaining bits of person, photoset, and photo-releated APIs
+* Provide a better searching interface
+* Lazily load attributes for objects that need to be accessed via secondary API call
+        
+== 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,40 @@
+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 teeny tiny 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.6.0')
+  s.add_dependency('activesupport', '~> 2.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/request.rb

@@ -0,0 +1,58 @@
+module Fleakr
+  module Api # :nodoc:
+    
+    # = Request
+    #
+    # Performs requests against the Flickr API and returns response objects (Flickr::Api::Response)
+    # that contain Hpricot documents for further parsing and inspection.  This class is used internally
+    # in all the defined model objects.
+    #
+    class Request
+
+      # Generic catch-all exception for any API errors
+      class ApiError < StandardError; end
+
+      # Makes a request to the Flickr API and returns a valid Response object.  If
+      # there are errors on the response it will rais an ApiError exception
+      def self.with_response!(method, additional_parameters = {})
+        request = Request.new(method, additional_parameters)
+        response = request.send
+
+        raise(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=)
+      def initialize(method, additional_parameters = {})
+        method = method.sub(/^(flickr\.)?/, 'flickr.')
+
+        default_parameters = {:api_key => Fleakr.api_key, :method => method}
+        @parameters = default_parameters.merge(additional_parameters)
+      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 = query_parameters
+        uri
+      end
+
+      def query_parameters
+        @parameters.map {|key,value| "#{key}=#{CGI.escape(value)}" }.join('&')
+      end
+
+
+
+    end
+  end
+end

data/lib/fleakr/api/response.rb

@@ -0,0 +1,35 @@
+module Fleakr
+  module Api
+    
+    # = Response
+    #
+    # Response objects contain Hpricot documents that are traversed and parsed by
+    # the model objects.  This class is never called directly but is instantiated
+    # during the request cycle (see: Fleakr::Api::Request.with_response!)
+    #
+    class Response
+
+      # Creates a new response from a raw XML string returned from a Request
+      def initialize(response_xml)
+        @response_xml = response_xml
+      end
+
+      # Return a document-based representation of the XML contained in the
+      # API response.  This is an Hpricot document object
+      def body
+        @body ||= Hpricot.XML(@response_xml)
+      end
+
+      # Did the response from the API contain errors?
+      def error?
+        (self.body/'rsp').attr('stat') != 'ok'
+      end
+
+      # Access the API error if one exists
+      def error
+        Fleakr::Objects::Error.new(self.body) if self.error?
+      end
+
+    end
+  end
+end

data/lib/fleakr/objects/contact.rb

@@ -0,0 +1,31 @@
+module Fleakr
+  module Objects # :nodoc:
+    class Contact # :nodoc:
+
+      include Fleakr::Support::Object
+
+      flickr_attribute :id, :attribute => 'nsid'
+      flickr_attribute :username, :attribute => 'username'
+      flickr_attribute :icon_server, :attribute => 'iconserver'
+      flickr_attribute :icon_farm, :attribute => 'iconfarm'
+
+      # Retrieve a list of contacts for the specified user ID and return an initialized
+      # collection of #User objects
+      def self.find_all_by_user_id(user_id)
+        response = Fleakr::Api::Request.with_response!('contacts.getPublicList', :user_id => user_id)
+        (response.body/'contacts/contact').map {|c| Contact.new(c).to_user }
+      end
+      
+      def to_user
+        user = User.new
+        self.class.attributes.each do |attribute|
+          attribute_name = attribute.name
+          user.send("#{attribute.name}=".to_sym, self.send(attribute.name))
+        end
+
+        user
+      end
+
+    end
+  end
+end

data/lib/fleakr/objects/error.rb

@@ -0,0 +1,22 @@
+module Fleakr
+  module Objects # :nodoc:
+    # = Error
+    #
+    # == Accessors
+    # 
+    # This class is a simple wrapper for the error response that the API returns.  There are
+    # a couple of attributes:
+    #
+    # [code] The error code as described in the documentation
+    # [message] The associated error message
+    #
+    class Error
+
+      include Fleakr::Support::Object
+
+      flickr_attribute :code, :xpath => 'rsp/err', :attribute => 'code'
+      flickr_attribute :message, :xpath => 'rsp/err', :attribute => 'msg'
+
+    end
+  end
+end

data/lib/fleakr/objects/group.rb

@@ -0,0 +1,26 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = Group
+    # 
+    # == Accessors
+    #
+    # [id] This group's ID
+    # [name] The name of the group
+    #
+    class Group
+
+      include Fleakr::Support::Object
+
+      flickr_attribute :id, :attribute => 'nsid'
+      flickr_attribute :name, :attribute => 'name'
+
+      find_all :by_user_id, :call => 'people.getPublicGroups', :path => 'groups/group'
+
+      has_many :photos
+      
+      scoped_search
+
+    end
+  end
+end

data/lib/fleakr/objects/image.rb

@@ -0,0 +1,51 @@
+module Fleakr
+  module Objects
+    
+    # = Image
+    #
+    # This class wraps the functionality for saving remote images to disk. It's called
+    # by the Fleakr::Objects::Photo class to save an image with a specific size and would 
+    # typically never be called directly.
+    # 
+    # Example:
+    # 
+    #  user = Fleakr.user('brownout')
+    #  user.photos.first.small.save_to('/tmp')
+    #
+    # == Attributes
+    # 
+    # [size] The name of this image's size (e.g. Square, Large, etc...)
+    # [width] The width of this image
+    # [height] The height of this image
+    # [url] The direct URL for this image
+    # [page] The page on Flickr that represents this photo
+    # 
+    class Image
+
+      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
+
+      find_all :by_photo_id, :call => 'photos.getSizes', :path => 'sizes/size'
+
+      # The filename portion of the image (without the full URL)
+      def filename
+        self.url.match(/([^\/]+)$/)[1]
+      end
+    
+      # Save this image to the specified directory or file. If the target is a
+      # 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}"
+        File.open(destination, 'w') {|f| f << Net::HTTP.get(URI.parse(self.url)) }
+      end
+    
+    end
+  end
+end

data/lib/fleakr/objects/photo.rb

@@ -0,0 +1,55 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = Photo
+    #
+    # == Attributes
+    #
+    # [id] The ID for this photo
+    # [title] The title of this photo
+    # [square] The tiny square representation of this photo
+    # [thumbnail] The thumbnail for this photo
+    # [small] The small representation of this photo
+    # [medium] The medium representation of this photo
+    # [large] The large representation of this photo
+    # [original] The original photo
+    #
+    # == Associations
+    #
+    # [images] The underlying images for this photo.
+    #
+    class Photo
+
+      # Available sizes for this photo
+      SIZES = [:square, :thumbnail, :small, :medium, :large, :original]
+
+      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'
+
+      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'
+      
+      has_many :images
+
+      # Create methods to access image sizes by name
+      SIZES.each do |size|
+        define_method(size) do
+          images_by_size[size]
+        end
+      end
+
+      private
+      def images_by_size
+        image_sizes = SIZES.inject({}) {|l,o| l.merge(o => nil)}
+        self.images.inject(image_sizes) {|l,o| l.merge!(o.size.downcase.to_sym => o) }
+      end
+
+    end
+  end
+end

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