flickrmocks 0.8.15 → 0.9.0

data/.gitignore

@@ -21,3 +21,6 @@ pkg
 ## PROJECT::SPECIFIC
 nbproject
 config.yml
+
+## documentation
+doc

data/Gemfile.lock

@@ -0,0 +1,123 @@
+PATH
+  remote: .
+  specs:
+    flickrmocks (0.8.15)
+      chronic
+      flickraw (>= 0.8.2)
+      ruby-debug19 (>= 0.11.6)
+      will_paginate (>= 3.0.pre2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionmailer (3.0.3)
+      actionpack (= 3.0.3)
+      mail (~> 2.2.9)
+    actionpack (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.6)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+    activesupport (3.0.3)
+    archive-tar-minitar (0.5.2)
+    arel (2.0.6)
+    builder (2.1.2)
+    chronic (0.3.0)
+    columnize (0.3.2)
+    diff-lcs (1.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    factory_girl (1.3.2)
+    factory_girl_rails (1.0)
+      factory_girl (~> 1.3)
+      rails (>= 3.0.0.beta4)
+    faker (0.3.1)
+    flickraw (0.8.3)
+      json (>= 1.1.1)
+    flickraw-cached (20100707.1)
+      flickraw
+    i18n (0.5.0)
+    json (1.4.6)
+    linecache19 (0.5.11)
+      ruby_core_source (>= 0.1.4)
+    mail (2.2.12)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.16)
+    polyglot (0.3.1)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rails (3.0.3)
+      actionmailer (= 3.0.3)
+      actionpack (= 3.0.3)
+      activerecord (= 3.0.3)
+      activeresource (= 3.0.3)
+      activesupport (= 3.0.3)
+      bundler (~> 1.0)
+      railties (= 3.0.3)
+    railties (3.0.3)
+      actionpack (= 3.0.3)
+      activesupport (= 3.0.3)
+      rake (>= 0.8.7)
+      thor (~> 0.14.4)
+    rake (0.8.7)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+    ruby-debug-base19 (0.11.24)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.4)
+      archive-tar-minitar (>= 0.5.2)
+    thor (0.14.6)
+    treetop (1.4.9)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.23)
+    will_paginate (3.0.pre2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  chronic
+  factory_girl_rails (>= 1.0)
+  faker (>= 0.3.1)
+  flickraw (>= 0.8.2)
+  flickraw-cached (>= 0.8.2)
+  flickrmocks!
+  rspec (>= 2.2.0)
+  ruby-debug19 (>= 0.11.6)
+  will_paginate (>= 3.0.pre2)

data/README.rdoc

@@ -1,41 +1,116 @@
-== Welcome to FlickrMocks
+= FlickrMocks
 
-FlickrMocks makes it possible to Marshal responses generated from the FLickRaw
-gem. This is useful for Mocking/Stubbing the Flickr interface for testing
-purposes.
+Wiki[http://wiki.github.com/takaltoo/flickrmocks] | RDocs[http://rdoc.info/projects/takaltoo/flickrmocks]
 
-The FlickRaw::Response and FlickRaw::ResponseList objects can not be Marshaled
-because they contain singleton's.
+FlickrMocks simplifies access to the Flickr API by providing wrappers and helpers on top of
+the FlickRaw[https://github.com/hanklords/flickraw] gem.
 
-== Getting Started
+== Installation
+In a standalone ruby project:
+    gem install flickrmocks
 
-1. Install flickrmocks:
-       <tt>gem install flickrmocks</tt>
+    # in your code
+    require 'flickrmocks
 
-2. require 'flickrmocks'
+In <b>Rails 3</b>, add this to your Gemfile.
 
-3. You should be able to Marshal/Unmarshal FlickRaw::Response and FlickRaw::ResponseList
-	classes. 
+    gem "flickrmocks"
 
-	FlickRaw.api_key = 'xxx your flickr api key goes here'
-	a = flickr.photos.search :tags => 'dog'
-	b = Marshal.dump(a)
-	
-	Marshal.load(b) 
-		
-== Rails Installation (Test::Unit)
+In <b>Rails 2</b>, add this to your environment.rb file.
+
+    config.gem "flickrmocks"
+
+Alternatively, you can install it as a plugin.
 
-Specify the gem dependency in your config/environment.rb file:
+    rails plugin install git://github.com/takaltoo/flickrmocks.git
 
-  Rails::Initializer.run do |config|
-    config.gem "flickrmocks", :lib => "flickrmocks"
-  end
+== Getting Started
+FlickrMocks API helpers expect the FlickRaw.api_key to be initialized before they are called:
+    FlickRaw.api_key = your_flickr_api_key
+
+In Rails you can automate the initialization by creating the initializer file
+config/initializers/flickraw_config.rb with the content:
+
+    FlickRaw.api_key = your_flickr_api_key[http://www.flickr.com/services/api/misc.api_keys.html]
+
+Alternatively, your flickr api key can be placed into a separate
+YAML[http://railscasts.com/episodes/85-yaml-configuration-file] configuration file.
+In this scenario the contents of the config/initializers/flickrwa_config.rb would be something like:
+
+    FlickRaw.api_key = APP_CONFIG['flickr_api_key']
+
+Your config/config.yml could look something similar to this (Note: you can use
+this file to place all your custom configurations):
+
+    development:
+      flickr_api_key: xyz
+    test:
+      flickr_api_key: xyz
+    production:
+      flickr_api_key: xyz
+
+== Using the search API
+FlickrMocks::Api.photo(options_hash), returns object of class FlickrMocks::Photo.
+The options accepted include:
+    :photo_id => "id for photo"
+    :secret => "secret for photo"
+FlickrMocks::Api.photo_details(options_hash), returns object of class FlickrMocks::PhotoDetails.
+The options accepted include:
+    :photo_id => "id for photo"
+    :secret => "secret for photo"
+FlickrMocks::Api.photos(options_hash), returns object of class FlickrMocks::PhotoSearch.
+The options accepted include:
+    :search_terms => 'search terms' # comma separated list of search terms 'happy cow, pasture'
+    :owner_id => 'id for owner of photo' # either :owner_id or :search_terms must be specified
+    :tag_mode => 'all' # optional argument, can be either all or any
+    :per_page =>  '50' # optional argument, can be any number greater than 0
+    :page =>  '1' # optional argument, can be any number greater than 0
+    :base_url => 'url' # optional argument
+FlickrMocks::Api.photo_sizes(options_hash), returns object of class FlickrMocks::PhotoSizes.
+The options accepted include:
+    :photo_id => "id for photo"
+    :secret => "secret for photo" # optional argument
+FlickrMocks::Api.interesting_photos(options_hash), returns object of class FlickrMocks::PhotoSearch.
+The options accepted include:
+    :date => '2010-10-10' # date of format YYYY-MM-DD
+    :per_page => 'number' # optional argument
+    :page =>  'number' # optional argument
+FlickrMocks::Api.commons_institutions(options_hash), returns object of class FlickrMocks::CommonsInstitutions.
+The options accepted include:
+    :per_page => 'number' # optional argument
+    :current_page => 'number' # optional argument
+
+== Stubs for testing
+FlickrMocks provides Rspec 2.0 stubs for the search API routines. To stub all the routines simply call:
+
+    FlickrMocks::Stubs::Api.all
+
+By calling FlickrMocks::Stubs::Api.all the following methods will be stubbed. 
+     FlickrMocks::Api.photo
+     FlickrMocks::Api.photos
+     FlickrMocks::Api.photo_details
+     FlickrMocks::Api.photo_sizes
+     FlickrMocks::Api.interesting_photos
+     FlickrMocks::Api.commons_institutions
+
+NOTE: the stubs return errors when not called with proper options. Moreover, some of the stubs return
+different objects depending on how they are called. For additional details please
+refer RDocs[http://rdoc.info/projects/takaltoo/flickrmocks].
+
+== Additional Docs
+
+* {RDOCs}[http://rdoc.info/projects/takaltoo/flickrmocks]
+* {See more}[http://wiki.github.com/takaltoo/flickrmocks/]
+* Run the specs manually once you've checked out the repository:
+   rspec spec -f d
 
-Then:
+		
+== Questions or Problems?
 
-  $ rake gems:install
-  $ rake gems:unpack
+If you have any issues with FlickrMocks which you cannot find the solution to in the documentation,
+please add an {issue on GitHub}[http://github.com/takaltoo/flickrmocks/issues] or fork the project and send a pull request.
 
+To get the specs running you should call +bundle+ and then +rake+.
 
 
 == Note on Patches/Pull Requests
@@ -45,15 +120,14 @@ Then:
 * Add tests for it. This is important so I don't break it in a
   future version unintentionally.
 * Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+  (if you want to have your own version, that is fine but bump version in a commit
+ by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
-
-
 == License
 
 FlickrMocks is released under the MIT license.
 
 == Copyright
 
-Copyright (c) 2010 Takaltoo.
+Copyright (c) 2010 Takaltoo

data/Rakefile

@@ -1,2 +1,14 @@
 require 'bundler'
+require 'rubygems'
+require 'rake'
+require 'rspec/core/rake_task'
+
 Bundler::GemHelper.install_tasks
+
+desc "Run RSpec"
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
+end
+
+task :default => :spec
+

data/flickrmocks.gemspec

@@ -27,9 +27,11 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.add_runtime_dependency(%q<flickraw>, [">= 0.8.2"])
   s.add_runtime_dependency(%q<chronic>, [">= 0"])
+  s.add_runtime_dependency(%q<ruby-debug19>, [">= 0.11.6"])
+  s.add_runtime_dependency(%q<will_paginate>, [">= 3.0.pre2"])
   s.add_development_dependency(%q<rspec>, [">= 2.2.0"])
-  s.add_development_dependency(%q<capybara>, [">= 0"])
   s.add_development_dependency(%q<factory_girl_rails>, [">= 1.0"])
   s.add_development_dependency(%q<faker>, [">= 0.3.1"])
+  s.add_development_dependency(%q<flickraw-cached>, [">= 0.8.2"])
 end
 

data/lib/flickr_mocks/api/api.rb

@@ -1,53 +1,106 @@
-module FlickrMocks
-
+module FlickrMocks  
+  # Wrappers for performing queries against the Flickr API's. Uses the
+  # FlickRaw gem to perform the queries. Query results are encapsulated in easy-to-use
+  # Ruby classes.
+  #
+  # Before calling the API methods you must initialize FlickRaw with your api_key:
+  #
+  #   FlickRaw.api_key = your_flickr_api_key
   class Api
     @defaults = {
+      :page => '1',
       :per_page => '200',
       :license => '4,5,6,7',
       :media => 'photos',
       :extras => 'license',
+      :max_entries => '4000',
       :tag_mode => 'any',
-      :flickr_tag_modes => ['any','all']
+      :possible_tag_modes => ['any','all'],
+      :possible_sizes => [:square, :thumbnail, :small, :medium, :medium_640, :large, :original],
     }
-  
+
     class << self
       attr_accessor :defaults
     end
 
-    def self.photos(params)
-      raise ArgumentError.new("Expecting a Hash argument.") unless params.is_a?(Hash)
-      photos = Api.flickr_photos(params)
-      PhotoSearch.new photos,Api.search_params(params)
+    # returns the default value stored in the class instance variable @defaults hash.
+    def self.default(value)
+      Api.defaults[value.to_sym]
     end
 
-    def self.photo_details(params)
-      raise ArgumentError.new("Expecting a Hash argument.") unless params.is_a?(Hash)
-      photo = Api.flickr_photo(params)
-      sizes = Api.flickr_photo_sizes(params)
-      @this = @photo = PhotoDetails.new(photo,sizes)
+    # Searches for photos that match the user provided parameters.
+    # Sample usage:
+    #  Api.photos(:search_terms => 'france') 
+    # Options hash accepts:
+    #   :search_terms : string with comma separated list of terms 'france,lyon'
+    #   :owner_id : pptional string containing the id for the owner of the photo.
+    #   :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
+    #   :page : optional string containing the page for search results to be returned. The default is '1'
+    #   :tag_mode : optionsl string containing either 'any' or 'all'. Affects the interpretation of the search terms to the FlickRaw API.
+    def self.photos(options)
+      raise ArgumentError.new("Expecting a Hash argument.") unless options.is_a?(Hash)
+      photos = Api::Flickr.photos(options)
+      Models::PhotoSearch.new photos,options
     end
 
-    def self.photo(params)
-      raise ArgumentError.new("Expecting a Hash argument") unless params.is_a?(Hash)
-      Photo.new Api.flickr_photo(params)
+    # Retrieves detailed information for a photo. A PhotoDetails object that encapsulates
+    # the retrieved data into an easy-to-use Ruby class is returned. Sample usage:
+    #  Api.photo_details(:photo_id => '1234'
+    # Options hash accepts:
+    #   :photo_id : required string that contains the id for the photo
+    #   :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+    def self.photo_details(options)
+      raise ArgumentError.new("Expecting a Hash argument.") unless options.is_a?(Hash)
+      photo = Api::Flickr.photo(options)
+      sizes = Api::Flickr.photo_sizes(options)
+      Models::PhotoDetails.new(photo,sizes)
     end
 
-    def self.photo_sizes(params)
-      raise ArgumentError.new("Expecting a Hash argument") unless params.is_a?(Hash)
-      PhotoSizes.new Api.flickr_photo_sizes(params)
+    # Retrieve basic information for a photo. Returns object of class Photo.
+    # Sample usage:
+    #  Api.photo(:photo_id => '1234')
+    # Options hash accepts:
+    #   :photo_id : required string that contains the id for the photo
+    #   :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+    def self.photo(options)
+      raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
+      Models::Photo.new Api::Flickr.photo(options)
     end
 
-    def self.interesting_photos(params)
-      raise ArgumentError.new("Expecting a Hash argument") unless params.is_a?(Hash)
-      photos = Api.flickr_interestingness(params)
-      PhotoSearch.new photos,Api.interesting_params(params)
+    # Retrieves available sizes for a given photo. Returns object of class PhotoSize.
+    # Sample usage:
+    #  Api.photo_sizes(:photo_id => '1234')
+    # Options hash accepts:
+    #   :photo_id : required string that contains the id for the photo
+    #   :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+    def self.photo_sizes(options)
+      raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
+      Models::PhotoSizes.new Api::Flickr.photo_sizes(options)
     end
 
-    def self.commons_institutions(params)
-      raise ArgumentError.new("Expecting a Hash argument") unless params.is_a?(Hash)
-      institutions = Api.flickr_commons_institutions
-      CommonsInstitutions.new institutions,Api.commons_institutions_params(params)
+    # Retrieves interesting photos for a given date. Returns object of class PhotoSearch.
+    # Sample usage:
+    #  Api.interesting_photos(:date => '2000-01-01'
+    # Options hash accepts:
+    #  :date : string with date in the format yyyy-mm-dd
+    #  :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
+    #  :page : optional string containing the page for search results to be returned. The default is '1'
+    def self.interesting_photos(options)
+      raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
+      photos = Api::Flickr.interestingness(options)
+      Models::PhotoSearch.new photos,options
     end
 
+    # Retrieves list of commons institutions. Returns object of class CommonsInstitutions.
+    # Sample usage:
+    #  Api.commons_institutions({})
+    # Options hash accepts:
+    #  :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
+    #  :page : optional string containing the page for search results to be returned. The default is '1'
+    def self.commons_institutions(options)
+      raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
+      institutions = Api::Flickr.commons_institutions
+      Models::CommonsInstitutions.new institutions,options
+    end
   end
 end

data/lib/flickr_mocks/api/flickr.rb

@@ -1,31 +1,77 @@
 module FlickrMocks
-
   class Api
-    # Not required for testing, simple wrappers for flickr* methods
-    def self.flickr_photos(params)
-      flickr.photos.search self.search_options(params)
-    end
+    # Wrapper methods for accessing Flickr Api. Module is used internally.
+    module Flickr
+      # Wrapper for flickr.photos.search Flickr API call.  Sample usage:
+      #
+      #   self.photos(:search_terms => 'france')
+      #
+      # Options hash accepts:
+      #  :search_terms : string with comma separated list of terms 'france,lyon'
+      #  :owner_id : pptional string containing the id for the owner of the photo.
+      #  :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
+      #  :page : optional string containing the page for search results to be returned. The default is '1'
+      #  :tag_mode : optionsl string containing either 'any' or 'all'. Affects the interpretation of the search terms to the FlickRaw API.
+      def self.photos(options)
+        flickr.photos.search Api::Options.search(options)
+      end
 
-    def self.flickr_photo(params)
-      flickr.photos.getInfo self.photo_options(params)
-    end
+      # Wrapper for flickr.photos.getInfo Flickr API call.  Sample usage:
+      #
+      #   self.photo(:photo_id => '123')
+      #
+      # Options hash accepts:
+      #  :photo_id : required string that contains the id for the photo
+      #  :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+      def self.photo(options)
+        flickr.photos.getInfo Api::Options.photo(options)
+      end
 
-    def self.flickr_photo_sizes(params)
-      flickr.photos.getSizes self.photo_options(params)
-    end
+      # Wrapper for flickr.photos-getSizes Flickr API call. Sample usage:
+      #
+      #   self.photo_sizes(:photo_id => '1', :secret => 'abcdef')
+      #
+      # Options hash accepts:
+      #  :photo_id : required string that contains the id for the photo
+      #  :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+      def self.photo_sizes(options)
+        flickr.photos.getSizes Api::Options.photo(options)
+      end
 
-    def self.flickr_interestingness(params)
-      flickr.interestingness.getList self.interesting_options(params)
-    end
+      # Wrapper for flickr.interestingness.getList Flickr API call. Sample usage:
+      #
+      #   self.interestingness(:dage => '2010-10-10')
+      #
+      # Options hash accepts:
+      #   :date : string containing date of format 'YYYY-MM-DD'
+      #   :per_page : optional string containing maximum number of items per page
+      #   :page : optional string containing the page to retrieve for the query
+      def self.interestingness(options)
+        flickr.interestingness.getList Api::Options.interesting(options)
+      end
 
-    def self.flickr_author(params)
-      flickr.photos.search self.author_options(params)
-    end
-    
-    def self.flickr_commons_institutions
-      flickr.commons.getInstitutions
+      # Wrapper for flickr.photos-search Flickr API call. Sample usage:
+      #
+      #   self.author(:owner_id => '20')
+      #
+      # Options hash accepts:
+      #  :owner_id : string containing owner for the photo. This gets mapped to :user_id
+      #  :per_page : optional string containing maximum number of items per page
+      #  :page : optional string containing the page to retrieve for the query
+      def self.author(options)
+        flickr.photos.search Api::Options.author(options)
+      end
+
+      # wrapper for flickr.commons.getInstitutions Flickr API call. Sample usage:
+      #
+      #   self.commons_institutions
+      #
+      # Options hash accepts:
+      #  :per_page : optional string containing maximum number of items per page
+      #  :page : optional string containing the page to retrieve for the query
+      def self.commons_institutions
+        flickr.commons.getInstitutions
+      end
     end
   end
-end
-  
-
+end

data/lib/flickr_mocks/api/helpers.rb

@@ -1,19 +1,32 @@
 module FlickrMocks
   class Api
-    # default control values
-    def self.default(value)
-      Api.defaults[value.to_sym]
-    end
-
-    def self.time(date=nil)
-      begin
-        date = Chronic.parse(date).strftime('%Y-%m-%d')
-        date ? date : Chronic.parse('yesterday').strftime('%Y-%m-%d')
-      rescue
-        Chronic.parse('yesterday').strftime('%Y-%m-%d')
+    module Helpers
+      # returns a date string of format YYYY-MM-DD. If the supplied date is ambiguous
+      # it returns yesterday's date in the format YYYY-MM-DD. Sample usage:
+      #
+      #  self.date('2010-10-10')
+      #  self.date('yesterday')
+      def self.date(date=nil)
+        self.valid_date?(date) ? self.parse_date(date) : self.parse_date('yesterday')
+      end
+      
+      # returns true when supplied date is of format YYYY-MM-DD. Sample usage:
+      #
+      #   self.valid_date?('2010-10-10')
+      def self.valid_date?(date)
+        begin
+          self.parse_date(date)
+          true
+        rescue
+          false
+        end
       end
-    end
 
+      private
+      def self.parse_date(date)
+        Chronic.parse(date).strftime('%Y-%m-%d')
+      end
 
+    end
   end
 end