README.rdoc @@ -1,2 +1,3 @@ /pkg/ -/coverage/ \ No newline at end of file +/coverage/ +/doc/ .gitignore @@ -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') Rakefile @@ -13,8 +13,19 @@ end module Fleakr + # Set the API key for all requests. Example: + # + # Fleakr.api_key = 'ABC123' + # mattr_accessor :api_key + # 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: + # + # Fleakr.api_key = 'ABC123' + # Fleakr.user('the decapitator') # => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06"> + # Fleakr.user('user@host.com') # => #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00"> + # def self.user(user_data) begin Objects::User.find_by_username(user_data) lib/fleakr.rb @@ -1,9 +1,12 @@ module Fleakr - module Api + module Api # :nodoc: 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 @@ -13,6 +16,20 @@ module Fleakr 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 + + private def endpoint_uri uri = URI.parse('http://api.flickr.com/services/rest/') uri.query = self.query_parameters @@ -23,13 +40,6 @@ module Fleakr @parameters.map {|key,value| "#{key}=#{CGI.escape(value)}" }.join('&') end - 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 Response.new(Net::HTTP.get(self.endpoint_uri)) end lib/fleakr/api/request.rb @@ -2,18 +2,23 @@ module Fleakr module Api 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 lib/fleakr/api/response.rb @@ -1,5 +1,5 @@ module Fleakr - module Objects + module Objects # :nodoc: class Contact include Fleakr::Support::Object @@ -9,14 +9,16 @@ module Fleakr 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 # # find_all :by_user_id, :call => 'contacts.getPublicList', :path => 'contacts/contact', :class_name => 'User' - - def to_user + + def to_user # :nodoc: user = User.new self.class.attributes.each do |attribute| attribute_name = attribute.name lib/fleakr/objects/contact.rb @@ -1,5 +1,5 @@ module Fleakr - module Objects + module Objects # :nodoc: class Error include Fleakr::Support::Object lib/fleakr/objects/error.rb @@ -1,5 +1,5 @@ module Fleakr - module Objects + module Objects # :nodoc: class Group include Fleakr::Support::Object lib/fleakr/objects/group.rb @@ -19,14 +19,20 @@ module Fleakr @size = size end + # Retrieve the URL for this image using the specified size def url "#{@base_url}#{Image.suffix_for(@size)}" end + # 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)) } lib/fleakr/objects/image.rb @@ -1,6 +1,6 @@ module Fleakr - module Objects - class Photo + module Objects # :nodoc: + class Photo # :nodoc: include Fleakr::Support::Object @@ -13,16 +13,17 @@ module Fleakr find_all :by_photoset_id, :call => 'photosets.getPhotos', :path => 'photoset/photo' find_all :by_user_id, :call => 'people.getPublicPhotos', :path => 'photos/photo' - def base_url - "http://farm#{self.farm_id}.static.flickr.com/#{self.server_id}/#{self.id}_#{self.secret}" - end - [:square, :thumbnail, :small, :medium, :large].each do |size| define_method(size) do Image.new(self.base_url, size) end end + private + def base_url + "http://farm#{self.farm_id}.static.flickr.com/#{self.server_id}/#{self.id}_#{self.secret}" + end + end end end \ No newline at end of file lib/fleakr/objects/photo.rb @@ -1,12 +1,25 @@ module Fleakr - module Objects + module Objects # :nodoc: class Search + # Create a new search def initialize(text = nil, search_options = {}) @text = text @search_options = search_options end + # Retrieve search results from the API + def results + if @results.nil? + response = Fleakr::Api::Request.with_response!('photos.search', self.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 @@ -18,16 +31,6 @@ module Fleakr parameters end - def results - if @results.nil? - response = Fleakr::Api::Request.with_response!('photos.search', self.parameters) - @results = (response.body/'rsp/photos/photo').map do |flickr_photo| - Photo.new(flickr_photo) - end - end - @results - end - end end end \ No newline at end of file lib/fleakr/objects/search.rb @@ -1,5 +1,5 @@ module Fleakr - module Objects + module Objects # :nodoc: class Set include Fleakr::Support::Object @@ -12,6 +12,10 @@ module Fleakr 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>, and + # <tt>:large</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) lib/fleakr/objects/set.rb @@ -1,5 +1,5 @@ module Fleakr - module Objects + module Objects # :nodoc: class User include Fleakr::Support::Object @@ -20,19 +20,17 @@ module Fleakr find_one :by_username, :call => 'people.findByUsername' find_one :by_email, :using => :find_email, :call => 'people.findByEmail' + # 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 - def load_info - response = Fleakr::Api::Request.with_response!('people.getInfo', :user_id => self.id) - self.populate_from(response.body) - 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" @@ -40,6 +38,11 @@ module Fleakr '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 lib/fleakr/objects/user.rb @@ -1,5 +1,5 @@ module Fleakr - module Support + module Support # :ndoc:all class Attribute attr_reader :name, :xpath, :attribute lib/fleakr/support/attribute.rb @@ -1,5 +1,5 @@ module Fleakr - module Support + module Support # :nodoc:all module Object module ClassMethods lib/fleakr/support/object.rb @@ -1,5 +1,5 @@ module Fleakr - module Version + module Version # :nodoc: MAJOR = 0 MINOR = 2 lib/fleakr/version.rb @@ -37,7 +37,7 @@ module Fleakr::Objects end it "should know the base URL to retrieve images" do - @photo.base_url.should == "http://farm2.static.flickr.com/3/1_secret" + @photo.send(:base_url).should == "http://farm2.static.flickr.com/3/1_secret" end end test/unit/fleakr/objects/photo_test.rb README.markdown 0121127ac48a0609eaeef18a2311773dcf321f4e Patrick Reagan patrick.reagan@viget.com http://github.com/reagent/fleakr/commit/72d796e97f256a027e01b89e7f82f8cc6dfac70e 72d796e97f256a027e01b89e7f82f8cc6dfac70e 2008-12-05T22:20:43-08:00 2008-12-05T22:20:43-08:00 Added RDoc to source files & reformatted README as RDoc 2e5ab10415eb566fcc362fc84e7a49ea42308988 Patrick Reagan patrick.reagan@viget.com