tomato_power 0.0.5 → 0.0.7

data/.gitignore

@@ -16,3 +16,4 @@ test/tmp
 test/version_tmp
 tmp
 spec/config/tomato_power_config.yaml
+spec/support/vcr

data/README.md

@@ -18,36 +18,45 @@ Or install it yourself as:
     $ gem install tomato_power
 
 ## Usage
-
-1. Create an instance of the `TomatoPower` client.
+Create a `TomatoPower::Client`.
   
-    client = TomatoPower.new <your_rotten_tomatoes_api_key>
+    >> client = TomatoPower.new <your_rotten_tomatoes_api_key>
 
-2. Start using the gem!
 
 ## Examples
-Searching for a movie returns an array of `TomatoPower::Movie` objects.
+
+Search for a movie by title or IMDB id.
 
     >> movies = client.search_by_title("The Dark Knight")
+
+    >> movies = client.search_by_id("0468569")
+
+Both searches would result in:
+
     >> movies[0].title
     => "The Dark Knight"
 
-Easily access information from movies and cast members. 
+Search for similar movies:
 
-    >> actors = movie.full_cast
+    >> movies = client.search_by_title("The Dark Knight")
+    >> similar_movies = movies[0].similar
+    >> similar_movies[0].title 
+    => "Batman Begins"
+
+
+Get cast of a movie:
+
+    >> actors = movie.cast
     >> actor = actors[0]
     >> actor.name
     => "Christian Bale"
     >> actor.characters
     => ["Batman/Bruce Wayne"]
 
-Search for similar movies
-
-    >> movies = client.search_by_title("The Dark Knight")
-    >> similar_movies = movies[0].similar
-    >> similar_movies[0].title 
-    => "Batman Begins"
+Get posters of a movie:
 
+    >> posters = movie.posters.thumbnail
+    => "http://content6.flixster.com/movie/11/16/51/11165160_mob.jpg"
 ## Contributing
 
 1. Fork it

data/lib/tomato_power/api/api.rb

@@ -1,29 +1,25 @@
 require 'active_support/core_ext/hash'
 require 'open-uri'
-require 'json'
 
 module TomatoPower
+  # The main API class to interface with the Rotten Tomatoes API
+  #
+  # Handles all API calls
   class API
-    API_VERSION = 'v1.0'
-    MAX_PAGE_LIMIT = 50
-    BASE_URL = "http://api.rottentomatoes.com/api/public/#{API_VERSION}"
-    MOVIE_URL = "#{ BASE_URL }/movies/"
 
     def initialize api_key
       @api_key = api_key
     end
 
-    #Defines methods in `TOMATO_METHODS`
-    # ==Parameters:
-    # options:
-    #   Hash of options allowed (#see tomato_methods.rb).
-    # 
+    #Defines methods that are in TOMATO_METHODS (tomato_methods.rb)
+    #
+    #@param method Method to be created. 
+    #@param options [Hash] optional options being passed to the function call.
+    #@note TOMATO_METHODS is a hash containing all of the Rotten Tomatoes API calls.
     def method_missing method, options={}
-      if TOMATO_METHODS.keys.include?(method)
+      if TOMATO_METHODS.key?(method)
         self.class.send(:define_method, method) do |options={}|
-          if options_valid? method, options
-            fetch api_url TOMATO_METHODS[method][:url], options
-          end
+            fetch(TOMATO_METHODS[method][:url], @api_key, options) if options_valid? method, options
         end
       else
         super
@@ -31,8 +27,12 @@ module TomatoPower
       self.send method, options
     end
 
+    # Whether or not this class responds to a function.
+    # Obligatory when dynamically creating functions with :define_method
+    # @param method method in question.
+    # @return [true, false]
     def respond_to? method
-      if TOMATO_METHODS.keys.include? method
+      if TOMATO_METHODS.key? method
         true
       else
         super
@@ -41,57 +41,21 @@ module TomatoPower
 
     private
 
-    def fetch url
-      tomato = get url
-      payload = TomatoPower::Parser::parse JSON.parse(tomato) 
-    end
-
-    def get url
-      open(url) do |f|
-        f.read
-      end
-    end
-
-    def options_valid? method, options={}
-      options.keys.each do |option|
-        if option == :page_limit && options[:page_limit] > MAX_PAGE_LIMIT
-          options[:pagelimit] = MAX_PAGE_LIMIT 
-        end
-        unless TOMATO_METHODS[method][:whitelist].include?(option)
-          raise ArgumentError.new(
-            "Invalid key: #{option} for #{method}.
-            Valid keys are #{TOMATO_METHODS[method][:whitelist]}."
-          )
-          false
-        end
-      end
-      true
-    end
-
-    def api_url endpoint, options={}
-      if movie_id = options[:movie_id]
-        options.delete :movie_id
-        movie_url endpoint, movie_id, options 
-      else
-        list_url endpoint, options
-      end
-    end
-
-    def movie_url endpoint, movie_id,  options={}
-      url = "#{MOVIE_URL}#{movie_id}#{endpoint}apikey=#{@api_key}#{request_params(options)}"
-    end
-
-    def list_url endpoint, options={}
-      url = "#{BASE_URL}#{endpoint}apikey=#{@api_key}#{request_params(options)}"
-    end
-
-    def request_params options ={}
-      params = ""
-      options.each_key do |key|
-        options[key] = URI.escape(options[key]) if options[key].is_a?(String)
-        params << "&#{key}=#{options[key]}" 
-      end
-      params
+    # Fetches the API call results via APIService 
+    #
+    # @param endpoint [String] API endpoint url
+    # @param api_key [String] Client API Key
+    # @param options [Hash] options for API call
+    def fetch endpoint, api_key, options
+      APIService.fetch endpoint, api_key, options 
+    end
+
+    # Determines if options are valid for given method.
+    #
+    # @param method [Symbol] API method 
+    # @param options [Hash] options for API call
+    def options_valid? method, options
+      APIService.options_valid? method, options
     end
   end
 end

data/lib/tomato_power/api/api_service.rb

@@ -0,0 +1,115 @@
+require 'json'
+
+module TomatoPower 
+
+  # API service to interface with Rotten Tomatoes API
+  class APIService 
+
+    MAX_PAGE_LIMIT = 50
+    API_VERSION    = 'v1.0'
+    BASE_URL       = "http://api.rottentomatoes.com/api/public/#{API_VERSION}"
+    MOVIE_URL      = "#{ BASE_URL }/movies/"
+    LIST_URL       = "#{ BASE_URL }/lists/"
+
+    # Gets the url then parses results.
+    #
+    #@param endpoint [String] API url.
+    #@param api_key [String] Client API key
+    #@param options [Hash] optins for the API call
+    #@return (see #parse)
+    def self.fetch endpoint, api_key, options={}
+      tomato = get api_url(endpoint, api_key, options)
+      parse(tomato) if tomato
+    end
+
+    # Constructs the API URL path depending on the options being passed in.
+    # Since the options are being checked against a whitelist before reaching this
+    # point, it is guaranteed that the options here are valid.
+    #
+    # The URL is constructed by introspecting the options. Only search calls contain
+    # the :q symbol, therefore a search_url is created. Likewise for movie specific searches
+    # requiring a :movie_id.  
+    #
+    # @param endpoint [String] the end point of the API call.
+    # @param options [Hash<String>] options for the API call.
+    # @return url [String] constructed url for the API call. 
+    # @note see TOMATO_METHODS or {http://developer.rottentomatoes.com/ Rotten Tomatoes API} for valid options.
+    def self.api_url endpoint, api_key, options={}
+      if movie_id = options[:movie_id]
+        options.delete :movie_id
+        endpoint = endpoint.dup.insert(0, movie_id.to_s)
+        url = MOVIE_URL
+      elsif options[:q] || options[:id]
+        url = BASE_URL
+      else
+        url = LIST_URL
+      end
+      "#{url}#{endpoint}apikey=#{api_key}#{request_params(options)}"
+    end
+
+    # Checks whether or not the received options are valid for a given method.
+    # @note An option is valid when it is present in the :whitelist of the corresponding method in TOMATO_METHODS.
+    #
+    # @param method [Symbol] method being called.
+    # @param options [Hash] options for the method.
+    # @return [true, false]
+    def self.options_valid? method, options={}
+      options.each_key do |option|
+        if option == :page_limit && options[:page_limit] > MAX_PAGE_LIMIT
+          options[:pagelimit] = MAX_PAGE_LIMIT 
+        end
+        unless TOMATO_METHODS[method][:whitelist].include?(option)
+          raise ArgumentError.new(
+            "Invalid key: #{option} for #{method}.
+        Valid keys are #{TOMATO_METHODS[method][:whitelist]}."
+          )
+          false
+        end
+      end
+      true
+    end
+
+    private 
+    # Parses the GET response.
+    # 
+    # @param response [String] response from the GET request.
+    # @return result [Array] Array of the parsed results.
+    def self.parse response
+      response = JSON.parse(response)
+      TomatoPower::Parser::parse(response)
+    end
+
+    # Constructs params to be appended to the constructed URL. 
+    #
+    # @param options [Hash] options to be appended to the final URL
+    # @return params [String] params for the API call URL.
+    def self.request_params options ={}
+      params = ""
+      options.each_key do |key|
+        option = options[key]
+        option = URI.escape(option) if option.is_a?(String)
+        params << "&#{key}=#{option}" 
+      end
+      params
+    end
+
+    # Gets API URL.
+    #
+    # @param url [String] API url.
+    # @return results [Hash<String>] Results from API call.
+    def self.get url
+      if url.is_valid_url?
+        begin
+          open(url) do |f|
+            f.read
+          end
+        rescue OpenURI::HTTPError => error
+          puts "Error: #{error}\nMake sure that the API URL and your API key are valid."
+          puts "URL: #{url}"
+        end
+      else
+        raise ArgumentError.new("Invalid API URL: #{url}")
+      end
+    end
+  end
+end

data/lib/tomato_power/api/tomato_methods.rb

@@ -1,12 +1,13 @@
-# List of methods and whitelist of allowed options for the corresponding
-# RottenTomatoes API call.
-# ==
-#    rotten_tomatoes_api_method => 
-#    { 
-#       :url => "resource_url", 
-#       :whitelist => [allowed options] 
-#    }
 module TomatoPower
+  # List of urls and whitelist of allowed API methods for the corresponding
+  # RottenTomatoes API call.
+  # ==
+  #    rotten_tomatoes_api_method => 
+  #    { 
+  #       :url => "resource_url", 
+  #       :whitelist => [allowed options] 
+  #    }
+  # ==
   TOMATO_METHODS = {
     :movies_search => 
     {
@@ -15,42 +16,42 @@ module TomatoPower
     },
     :box_office_movies => 
     {
-      :url       => "/lists/movies/box_office.json?",
+      :url       => "movies/box_office.json?",
       :whitelist => [:limit, :country]
     },
       :in_theaters_movies => 
     {
-      :url       => "/lists/movies/in_theaters.json?",
+      :url       => "movies/in_theaters.json?",
       :whitelist => [:page, :page_limit, :country]
     },
       :opening_movies => 
     {
-      :url       => "/lists/movies/opening.json?",
+      :url       => "movies/opening.json?",
       :whitelist => [:limit, :country]
     },
       :upcoming_movies => 
     {
-      :url       => "/lists/movies/upcoming.json?",
+      :url       => "movies/upcoming.json?",
       :whitelist => [:page, :page_limit, :country]
     },
       :top_rentals => 
     { 
-      :url       => "/lists/dvds/top_rentals.json?",
+      :url       => "dvds/top_rentals.json?",
       :whitelist => [:limit, :country]
     },
       :current_release_dvds => 
     {
-      :url       => "/lists/dvds/current_releases.json?",
+      :url       => "dvds/current_releases.json?",
       :whitelist => [:page, :page_limit,:country]
     }, 
       :new_release_dvds => 
     {
-      :url       => "/lists/dvds/new_releases.json?",
+      :url       => "dvds/new_releases.json?",
       :whitelist => [:page, :page_limit, :country]
     },
       :upcoming_dvds => 
     {
-      :url       => "/lists/dvds/upcoming.json?",
+      :url       => "dvds/upcoming.json?",
       :whitelist => [:page, :page_limit, :country]
     },
       :movie_cast => 

data/lib/tomato_power/client.rb

@@ -3,6 +3,11 @@ require 'forwardable'
 module TomatoPower
   class Client
 
+    # Main entry point for end users.
+    # Client handles interactions from the user and delegates API calls to the 
+    # API class.
+    #
+    # Certain functions are not delegated due to usability design deicisons.
     extend Forwardable
 
     def initialize 
@@ -19,11 +24,19 @@ module TomatoPower
       :upcoming_dvds
     def_delegator :@api, :in_theaters_movies, :movies_in_theaters
 
+    # Searches for a movie by title.
+    #
+    # @param movie_title [String] The movie title to search for
+    # @param options [Hash] An optional hash for passing options to the API.
+    # @note See {http://developer.rottentomatoes.com/ Rotten Tomatoes API} possible options.
     def search_by_title(movie_title, options={})
       options[:q] = movie_title
       @api.movies_search(options)
     end
 
+    # Searches for a movie by IMDB id. 
+    # @note As of Rotten Tomatoes API v1.0,they only support ID look up via IMDB ids.
+    # @param movie_id [String] movie's id
     def search_by_id(movie_id)
       options = {}
       options[:type] = 'imdb' #current only supports 'imdb' type

data/lib/tomato_power/helpers/helpers.rb

@@ -1,6 +1,8 @@
 require 'yaml'
 
+# Contains helper functions 
 module Helpers
+  # Determines whether or not a string is a valid url
   String.class_eval do
     def is_valid_url?
       uri = URI.parse self

data/lib/tomato_power/helpers/parsers.rb

@@ -1,6 +1,11 @@
 module TomatoPower
+  # Handles parsing of the returned results from an API call.
   module Parser
-    def self.parse json={}
+    #Parses a json object into a Tomato Power object.
+    #
+    #@param json [JSON] json object from API call response
+    #@return payload [Array] array of parsed Tomato Power objects
+    def self.parse json
       payload =[]
       if json["movies"]
         json["movies"].each do |movie|
@@ -24,5 +29,25 @@ module TomatoPower
       payload << "No Results" if payload.length < 1
       payload
     end
+
+    # Parses TomatoPower::Movie posters
+    #
+    # @param poster_types [Hash] types of posters 
+    # @return [TomatoPower::Poster] poster links
+    def self.parse_posters poster_types
+      Poster.new(poster_types)
+    end
+
+    # Parses TomatoPower::Movie abridged cast members
+    #
+    # @param abridged_cast [Hash] abridged cast from a movie 
+    # @return parsed_cast [Array] array of TomatoPower::Actor objects 
+    def self.parse_cast abridged_cast
+      parsed_cast =[]
+      abridged_cast.each do |cast_member|
+        parsed_cast << Actor.new( cast_member )
+      end
+      parsed_cast
+    end
   end
 end

data/lib/tomato_power/movie/actor.rb

@@ -1,4 +1,5 @@
 module TomatoPower
+  # Actor of a movie.
   class Actor
 
     attr_reader :id, :name, :characters

data/lib/tomato_power/movie/clip.rb

@@ -1,4 +1,5 @@
 module TomatoPower
+  # Clip of a movie
   class Clip
     attr_reader :title, :duration, :thumbnail
     def initialize clip={}

data/lib/tomato_power/movie/movie.rb

@@ -1,8 +1,9 @@
 module TomatoPower
+  # A Movie
   class Movie
 
-    attr_reader :id, :info, :abridged_cast, :title, :ratings, :mpaa_rating,
-      :runtime,:release_dates, :synopsis, :posters, :alternate_ids, :links, 
+    attr_reader :id, :info, :title, :ratings, :mpaa_rating,
+      :runtime,:release_dates, :synopsis, :alternate_ids, :links, 
       :studio, :abridged_directors
 
     def initialize movie={}
@@ -24,6 +25,7 @@ module TomatoPower
       @studio = movie["studio"]
     end
 
+    # Aliased API methods for a better interface. 
     MOVIE_METHOD_ALIAS = {
       :full_cast => :movie_cast,
       :clips => :movie_clips,
@@ -32,17 +34,29 @@ module TomatoPower
       :alias => :movie_alias
     }
 
+    # Poster for a movie
+    # @return poster links
+    def posters
+      posters ||= TomatoPower::Parser::parse_posters @posters
+    end
+
+    # cast from a movie
+    # 
+    # @note this returns the abridged cast.
+    def cast 
+      actors ||= TomatoPower::Parser::parse_cast @abridged_cast
+    end
+
     def method_missing method, options={}
       if MOVIE_METHOD_ALIAS.keys.include?(method)
-        method = MOVIE_METHOD_ALIAS[method]
         self.class.send(:define_method, method) do |options={}|
-          options[:movie_id] = @id 
-          @api.send(method, options )
+          options[:movie_id] = @id
+          @api.send(MOVIE_METHOD_ALIAS[method], options)
         end
       else
         super
       end
-      self.send method
+      self.send method, options
     end
 
     def respond_to? method

data/lib/tomato_power/movie/poster.rb

@@ -0,0 +1,14 @@
+module TomatoPower
+  class Poster
+
+    attr_reader :thumbnail, :profile, :detailed, :original
+
+    def initialize posters={}
+      @thumbnail = posters["thumbnail"]
+      @profile = posters["profile"]
+      @detailed = posters["detailed"]
+      @original = posters["originall"]
+    end
+
+  end
+end

data/lib/tomato_power/movie/review.rb

@@ -1,4 +1,5 @@
 module TomatoPower
+  # Review for a movie
   class Review
 
     attr_reader :critic, :date, :freshness, :publication, :quote, :links

data/lib/tomato_power/version.rb

@@ -1,3 +1,3 @@
 module TomatoPower
-  VERSION = "0.0.5"
+  VERSION = "0.0.7"
 end

data/lib/tomato_power.rb

@@ -1,21 +1,28 @@
 require "tomato_power/version"
 
 module TomatoPower
+
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power', 'client')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power','api', 'api')
+  require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power','api', 'api_service')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power','api', 'tomato_methods')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power','movie', 'actor')
+  require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power','movie', 'poster')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power', 'movie','clip')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power', 'movie','movie')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power', 'movie','review')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power','helpers', 'helpers')
   require File.join(File.expand_path(File.dirname(__FILE__)), 'tomato_power', 'helpers','parsers')
 
+  # Handles Rotten Tomatoes API key assignment and creates a new client for the
+  # end user.
   def self.new api_key=ENV.fetch("ROTTEN_TOMATOES_API_KEY")
     self.api = API.new api_key
     Client.new 
   end
 
+  # Sets class level accessor
+  # @api : API object
   class << self
     attr_accessor :api
   end

data/spec/spec_helper.rb

@@ -2,4 +2,4 @@ $: << File.join(File.dirname(__FILE__), "/../lib")
 require 'rubygems'
 require 'support/vcr'
 require 'tomato_power'
-require 'unit_specs/helpers'
+require 'unit_specs/helpers/helpers'

data/spec/support/sample_data/sample_posters

@@ -0,0 +1,6 @@
+{
+  "thumbnail": "http://content9.flixster.com/movie/10/93/18/10931807_mob.jpg",
+    "profile": "http://content9.flixster.com/movie/10/93/18/10931807_pro.jpg",
+    "detailed": "http://content9.flixster.com/movie/10/93/18/10931807_det.jpg",
+    "original": "http://content9.flixster.com/movie/10/93/18/10931807_ori.jpg"
+}

data/spec/unit_specs/api/api_services_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+module TomatoPower
+  describe "APIService" do
+    before do
+    end
+
+    describe "fetch" do
+    end
+
+    describe "api_url" do
+    end
+
+    describe "API options validation" do
+
+      describe "valid options" do
+
+        it "should not raise error" do
+          expect { APIService.options_valid?(:movies_search, {:q => "movie", :page => 1})}.
+            not_to raise_error
+        end
+
+        it "should consider 0 options valid" do
+
+          expect { APIService.options_valid?(:movies_search)}.
+            not_to raise_error
+        end
+
+      end
+
+      describe "invalid options" do
+        it "should raise error" do
+          expect { APIService.options_valid?(:movies_search, {:invalid => "movie"})}.
+            to raise_error
+        end
+      end
+    end
+  end
+end