reagent-fleakr 0.2.1 → 0.3.0

data/{README.markdown → README.rdoc}

@@ -1,10 +1,16 @@
-# Fleakr
+= Fleakr
 
-## Description
+== Description
 
 A teeny tiny gem to interface with Flickr photostreams
 
-## Installation
+== Installation
+
+=== Stable
+
+    sudo gem install fleakr
+
+=== Bleeding Edge
 
     sudo gem install reagent-fleakr --source=http://gems.github.com
     
@@ -14,7 +20,7 @@ Or ...
     $ cd fleakr
     $ rake gem && sudo gem install pkg/fleakr-<version>.gem
 
-## Usage
+== Usage
 
 Before doing anything, require the library:
 
@@ -23,40 +29,51 @@ Before doing anything, require the library:
 
 Then, set your API key (only need to do this once per session):
 
-    >> Fleakr::Request.api_key = '<your api key here>'
+    >> Fleakr.api_key = '<your api key here>'
     
 Find a user by username:
 
-    >> user = Fleakr::User.find_by_username('the decapitator')
-    => #<Fleakr::User:0x692648 @username="the decapitator", @id="21775151@N06">
+    >> user = Fleakr.user('the decapitator')
+    => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">
 
 Or by email:
 
-    >> user = Fleakr::User.find_by_email('user@host.com')
-    => #<Fleakr::User:0x11f484c @username="bckspcr", @id="84481630@N00">
+    >> 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::Set:0x671358 @title="The Decapitator", @description="">, 
-        #<Fleakr::Set:0x66d898 @title="londonpaper hijack", ...
+    => [#<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::Group:0x11f2330 ..., 
-        #<Fleakr::Group:0x11f2308 ...
+    => [#<Fleakr::Objects::Group:0x11f2330 ..., 
+        #<Fleakr::Objects::Group:0x11f2308 ...
     >> user.groups.first.name
     => "Rural Decay"
     >> user.groups.first.id
     => "14581414@N00"
 
+Groups also contain photos:
+
+    >> u.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::Set:0x1195bbc @title="The Decapitator", @id="72157603480986566", @description="">
+    => #<Fleakr::Objects::Set:0x1195bbc @title="The Decapitator", @id="72157603480986566", @description="">
     >> user.sets.first.photos.first
-    => #<Fleakr::Photo:0x1140108 ... >
+    => #<Fleakr::Objects::Photo:0x1140108 ... >
     >> user.sets.first.photos.first.title
     => "Untitled1"
     
@@ -69,7 +86,7 @@ If you can't decide on a photo and would rather just save the whole set, specify
 and the size of the images you're interested in:
 
     >> user.sets.first.save_to('/tmp', :square)
-    => [#<Fleakr::Photo:0x1187a1c @secret="715587b2cb" ...
+    => [#<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", 
@@ -77,26 +94,36 @@ and the size of the images you're interested in:
 
 If you would prefer to just search photos, you can do that with search text:
 
-    >> search = Fleakr::Search.new('ponies!!')
-    >> search.results
-    => [#<Fleakr::Photo:0x11f4e64 @title="hiroshima atomic garden", @id="3078234390">, 
-        #<Fleakr::Photo:0x11f4928 @title="PONYLOV", @id="3077360853">, ...
-    >> search.results.first.title
+    >> 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:
 
-    >> search = Fleakr::Search.new(nil, :tags => 'macro')
-    >> search.results.first.title
+    >> photos = Fleakr.search(:tags => 'macro')
+    >> photos.first.title
     => "Demure"
-    >> search.results.first.id
+    >> photos.first.id
     => "3076049945"
 
-## TODO
+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
+== License
 
 Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com)
 

data/Rakefile

@@ -10,13 +10,13 @@ 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.markdown)
+  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.markdown Rakefile) + Dir.glob("{lib,test}/**/*")
-  # s.executables    = ['fleakr']
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
   
   s.add_dependency('hpricot', '~> 0.6.0')
   s.add_dependency('activesupport', '~> 2.2.0')

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