mwilliams-fleakr 0.5.1

data/lib/fleakr/objects/photo.rb

@@ -0,0 +1,147 @@
+module Fleakr
+  module Objects # :nodoc:
+    
+    # = Photo
+    #
+    # Handles both the retrieval of Photo objects from various associations (e.g. User / Set) as 
+    # well as the ability to upload images to the Flickr site.
+    # 
+    # == Attributes
+    #
+    # [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
+    # [medium] The medium representation of this photo
+    # [large] The large representation of this photo
+    # [original] The original photo
+    # [previous] The previous photo based on the current context
+    # [next] The next photo based on the current context 
+    #
+    # == Associations
+    #
+    # [images] The underlying images for this photo.
+    # [tags] The tags for this photo.
+    # [comments] The comments associated with this photo
+    #
+    class Photo
+
+      # Available sizes for this photo
+      SIZES = [:square, :thumbnail, :small, :medium, :large, :original]
+
+      include Fleakr::Support::Object
+      extend Forwardable
+
+      def_delegators :context, :next, :previous
+
+      flickr_attribute :id, :from => ['@id', 'photoid']
+      flickr_attribute :title, :description, :secret, :posted, :taken, :url
+      flickr_attribute :farm_id, :from => '@farm'
+      flickr_attribute :server_id, :from => '@server'
+      flickr_attribute :owner_id, :from => ['@owner', 'owner@nsid']
+      flickr_attribute :updated, :from => '@lastupdate'
+      flickr_attribute :comment_count, :from => 'comments'
+
+      # TODO:
+      # * visibility
+      # * editability
+      # * usage
+
+      find_all :by_set_id, :using => :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'
+      
+      lazily_load :posted, :taken, :updated, :comment_count, :url, :description, :with => :load_info
+      
+      has_many :images, :tags, :comments
+
+      # Upload the photo specified by <tt>filename</tt> to the user's Flickr account. When uploading,
+      # there are several options available (none are required):
+      #
+      # [:title] The title for this photo. Any string is allowed.
+      # [:description] The description for this photo. Any string is allowed.
+      # [:tags] A collection of tags for this photo. This can be a string or array of strings.
+      # [:viewable_by] Who can view this photo?  Acceptable values are one of <tt>:everyone</tt>,
+      #                <tt>:friends</tt> or <tt>:family</tt>.  This can also take an array of values
+      #                (e.g. <tt>[:friends, :family]</tt>) to make it viewable by friends and family.
+      # [:level] The safety level of this photo.  Acceptable values are one of <tt>:safe</tt>,
+      #          <tt>:moderate</tt>, or <tt>:restricted</tt>.
+      # [:type] The type of image this is.  Acceptable values are one of <tt>:photo</tt>,
+      #         <tt>:screenshot</tt>, or <tt>:other</tt>.
+      # [:hide?] Should this photo be hidden from public searches? Takes a boolean.
+      #
+      def self.upload(filename, options = {})
+        response = Fleakr::Api::UploadRequest.with_response!(filename, :create, options)
+        photo = Photo.new(response.body)
+        Photo.find_by_id(photo.id)
+      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, :update, :photo_id => self.id)
+        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
+
+      def context # :nodoc:
+        @context ||= begin
+          response = Fleakr::Api::MethodRequest.with_response!('photos.getContext', :photo_id => self.id)
+          PhotoContext.new(response.body)
+        end
+      end
+
+      # The user who uploaded this photo.  See Fleakr::Objects::User for additional information.
+      # 
+      def owner
+        @owner ||= User.find_by_id(owner_id)
+      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
+          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/photo_context.rb

@@ -0,0 +1,49 @@
+module Fleakr
+  module Objects # :nodoc:
+
+    # = PhotoContext
+    #
+    # This class represents the context for a photo as retrieved from the API.  It's not
+    # intended to be used directly, but is used in conjunction with Photo#previous and 
+    # Photo#next
+    #
+    # == Attributes
+    #
+    # [count] The number of photos available
+    
+    class PhotoContext
+      
+      include Fleakr::Support::Object
+      
+      flickr_attribute :count
+      flickr_attribute :next_id,     :from => 'nextphoto@id'
+      flickr_attribute :previous_id, :from => 'prevphoto@id'
+
+      # Is there a previous photo available for the current photo?
+      #
+      def previous?
+        previous_id != '0'
+      end
+      
+      # The previous photo if one is available
+      #
+      def previous
+        Photo.find_by_id(previous_id) if previous?
+      end
+      
+      # Is there a next photo available for the current photo?
+      #
+      def next?
+        next_id != '0'
+      end
+      
+      # The next photo if one is available
+      #
+      def next
+        Photo.find_by_id(next_id) if next?
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/objects/search.rb

@@ -0,0 +1,30 @@
+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
+        @results ||= begin
+          response = Fleakr::Api::MethodRequest.with_response!('photos.search', parameters)
+          (response.body/'rsp/photos/photo').map {|p| Photo.new(p) }
+        end
+      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,50 @@
+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
+    # [count] Count of photos in this set
+    # 
+    # == Associations
+    # 
+    # [photos] The collection of photos for this set. See Fleakr::Objects::Photo
+    # [comments] All comments associated with this set. See Fleakr::Objects::Comment
+    #
+    class Set
+
+      include Fleakr::Support::Object
+
+      has_many :photos, :comments
+
+      flickr_attribute :id, :title, :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 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 
+      # 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_with_index do |photo, index|
+          image = photo.send(size)
+          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
+end

data/lib/fleakr/objects/tag.rb

@@ -0,0 +1,56 @@
+module Fleakr
+  module Objects # :nodoc:
+
+    # = Tag
+    #
+    # This class represents a tag that can be associated with a photo or an individual user.
+    #
+    # == Attributes
+    #
+    # [id] The unique identifier for this tag
+    # [raw] The raw, user-entered value for this tag
+    # [value] The formatted value for this tag. Also available through <tt>to_s</tt>
+    #
+    class Tag
+      
+      include Fleakr::Support::Object
+      
+      flickr_attribute :id, :raw
+      flickr_attribute :author_id, :from => '@author'
+      flickr_attribute :value, :from => '.' # pull this from the current node
+      flickr_attribute :machine_flag, :from => '@machine_tag'
+      
+      find_all :by_photo_id, :call => 'tags.getListPhoto', :path => 'photo/tags/tag'
+      find_all :by_user_id, :call => 'tags.getListUser', :path => 'who/tags/tag'
+      
+      # The first user who created this tag.  See Fleakr::Objects::User for more information
+      #
+      def author
+        @author ||= User.find_by_id(author_id) unless author_id.nil?
+      end
+      
+      # A list of related tags.  Each of the objects in the collection is an instance of Tag
+      #
+      def related
+        @related ||= begin
+          response = Fleakr::Api::MethodRequest.with_response!('tags.getRelated', :tag => value)
+          (response.body/'rsp/tags/tag').map {|e| Tag.new(e) }
+        end
+      end
+      
+      # Is this a machine tag?
+      #
+      def machine?
+        machine_flag != '0'
+      end
+      
+      # The formatted value of the tag.  Also available as <tt>value</tt>
+      #
+      def to_s
+        value
+      end
+      
+    end
+    
+  end
+end

data/lib/fleakr/objects/user.rb

@@ -0,0 +1,95 @@
+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)
+    # [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
+    # [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
+    # [tags] The tags associated with this user
+    #
+    # == 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
+
+      flickr_attribute :id, :from => 'user@nsid'
+      flickr_attribute :username, :location
+      flickr_attribute :name, :from => 'person/realname'
+      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, :tags
+
+      find_one :by_username, :call => 'people.findByUsername'
+      find_one :by_email, :using => :find_email, :call => 'people.findByEmail'
+      find_one :by_id, :using => :user_id, :call => 'people.getInfo'
+
+      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
+      
+      # 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::MethodRequest.with_response!('people.getInfo', :user_id => self.id)
+        self.populate_from(response.body)
+      end
+
+    end
+  end
+end

data/lib/fleakr/objects.rb

@@ -0,0 +1,12 @@
+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_context'
+require 'fleakr/objects/photo'
+require 'fleakr/objects/comment'
+require 'fleakr/objects/tag'
+require 'fleakr/objects/search'
+require 'fleakr/objects/set'
+require 'fleakr/objects/user'

data/lib/fleakr/support/attribute.rb

@@ -0,0 +1,46 @@
+module Fleakr
+  module Support # :nodoc:all
+    class Attribute
+
+      # TODO: Refactor the location / attribute logic into a Source class
+
+      attr_reader :name, :sources
+
+      def initialize(name, sources = nil)
+        @name = name.to_sym
+        
+        @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
+
+      def attribute(source)
+        location, attribute = source.split('@')
+        attribute || location
+      end
+      
+      def location(source)
+        split(source).first
+      end
+
+      def value_from(document)
+        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
+  end
+end

data/lib/fleakr/support/object.rb

@@ -0,0 +1,110 @@
+module Fleakr
+  module Support # :nodoc:all
+    module Object
+    
+      module ClassMethods
+      
+        def attributes
+          @attributes ||= []
+        end
+      
+        def flickr_attribute(*names_and_options)
+          options = names_and_options.extract_options!
+
+          names_and_options.each do |name|
+            self.attributes << Attribute.new(name, options[:from])
+            class_eval "attr_accessor :#{name}"
+          end
+        end
+      
+        def has_many(*attributes)
+          class_name = self.name
+
+          attributes.each do |attribute|
+            target           = "Fleakr::Objects::#{attribute.to_s.classify}"
+            finder_attribute = "#{class_name.demodulize.underscore}_id"
+
+            class_eval <<-CODE
+              def #{attribute}
+                @#{attribute} ||= #{target}.send("find_all_by_#{finder_attribute}".to_sym, self.id)
+              end
+            CODE
+          end
+        end
+      
+        def find_all(condition, options)
+          attribute    = options[:using].nil? ? condition.to_s.sub(/^by_/, '') : options[:using]
+          target_class = options[:class_name].nil? ? self.name : "Fleakr::Objects::#{options[:class_name]}"
+        
+          class_eval <<-CODE
+            def self.find_all_#{condition}(value, options = {})
+              options.merge!(:#{attribute} => value)
+              
+              response = Fleakr::Api::MethodRequest.with_response!('#{options[:call]}', options)
+              (response.body/'rsp/#{options[:path]}').map {|e| #{target_class}.new(e) }
+            end
+          CODE
+        end
+      
+        def find_one(condition, options)
+          attribute = options[:using].nil? ? condition.to_s.sub(/^by_/, '') : options[:using]
+        
+          class_eval <<-CODE
+            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
+        end
+        
+        def scoped_search
+          key = "#{self.name.demodulize.underscore.downcase}_id".to_sym
+
+          class_eval <<-CODE
+            def search(search_text)
+              Fleakr::Objects::Search.new(:text => search_text, :#{key} => self.id).results
+            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
+    
+      module InstanceMethods
+      
+        def initialize(document = nil)
+          self.populate_from(document) unless document.nil?
+        end
+      
+        def populate_from(document)
+          self.class.attributes.each do |attribute|
+            value = attribute.value_from(document)
+            self.send("#{attribute.name}=".to_sym, value) unless value.nil?
+          end
+        end
+      
+      end
+
+      def self.included(other)
+        other.send(:extend, Fleakr::Support::Object::ClassMethods)
+        other.send(:include, Fleakr::Support::Object::InstanceMethods)
+      end
+      
+    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

@@ -0,0 +1,13 @@
+module Fleakr
+  module Version # :nodoc:
+    
+    MAJOR = 0
+    MINOR = 5
+    TINY  = 0
+    
+    def self.to_s
+      [MAJOR, MINOR, TINY].join('.')
+    end
+    
+  end
+end