nytimes-movies 0.1.1

data/History.txt

@@ -0,0 +1,4 @@
+== 0.0.1 2008-11-13
+
+* 1 major enhancement:
+  * Initial release

data/README.rdoc

@@ -0,0 +1,55 @@
+= nytimes-movies
+
+== DESCRIPTION:
+
+A gem for accessing the NY Times' Movie Reviews API (http://developer.nytimes.com/)
+
+== FEATURES/PROBLEMS:
+
+* Still under development. Please email jharris@nytimes.com with bugs. Some methods and classes may
+change until we reach a stable 1.0 version.
+
+== SYNOPSIS:
+
+  include Nytimes::Movies
+	Base.api_key = 'YOUR API KEY'
+	reviews = Review.find(:dvd => true, :reviewer => 'A. O. Scott')
+	ao = Critic.find_by_name('A. O. Scott')
+
+== REQUIREMENTS:
+
+* The JSON gem
+* An API key for the NY Times' Movies API
+
+== INSTALL:
+
+* sudo gem install harrisj-nytimes-movies --source=http://gems.github.com/
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Jacob Harris
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+THIS LICENSE APPLIES ONLY TO THE NYTIMES-MOVIES GEM AND DOES NOT ALTER 
+OR ABROGATE THE TERMS OF SERVICE FOR THE MOVIE REVIEWS API PROVIDED BY 
+THE NEW YORK TIMES.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rake'
+
+begin 
+  require 'jeweler' 
+  Jeweler::Tasks.new do |s| 
+    s.name = "nytimes-movies" 
+    s.summary = "A gem for talking to the New York Times Movie Reviews API" 
+    s.email = "jharris@nytimes.com" 
+    s.homepage = "http://github.com/harrisj/nytimes-moves" 
+    s.description = "A gem for talking to the New York Times Movie Reviews API" 
+    s.authors = ["Jacob Harris"] 
+    s.files =  FileList["[A-Z]*", "{bin,generators,lib,test}/**/*"] 
+    s.add_dependency 'json' 
+  end 
+rescue LoadError 
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com" 
+end
+
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'nytimes-articles'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/test_*.rb'
+  t.verbose = false
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/test_*.rb']
+    t.verbose = true
+  end
+rescue LoadError
+  puts "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+end
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+end
+
+task :default => :test

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 1
+:patch: 1
+:major: 0

data/lib/nytimes-movies.rb

@@ -0,0 +1,4 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'nytimes/movies'

data/lib/nytimes/movies.rb

@@ -0,0 +1,6 @@
+require 'nytimes/movies/base'
+require 'nytimes/movies/link'
+require 'nytimes/movies/multimedia_link'
+require 'nytimes/movies/critic'
+require 'nytimes/movies/result_set'
+require 'nytimes/movies/review'

data/lib/nytimes/movies/base.rb

@@ -0,0 +1,81 @@
+require 'open-uri'
+require 'json'
+
+module Nytimes
+	module Movies
+		class Base
+			API_SERVER = 'api.nytimes.com'
+			API_VERSION = 'v2'
+			API_NAME = 'movies'
+			API_BASE = "/svc/#{API_NAME}/#{API_VERSION}"
+			
+			@@api_key = nil
+			@@copyright = nil
+			
+			class << self
+				
+				##
+				# The copyright footer to be placed at the bottom of any data from the New York Times. Note this is only set after an API call.
+				def copyright
+					@@copyright
+				end
+				
+				##
+				# Set the API key used for operations. This needs to be called before any requests against the API. To obtain an API key, go to http://developer.nytimes.com/
+				def api_key=(key)
+					@@api_key = key
+				end
+				
+				def api_key
+					@@api_key
+				end
+				
+				##
+				# Builds a request URI to call the API server
+				def build_request_url(path, params)
+					URI::HTTP.build :host => API_SERVER,
+													:path => "#{API_BASE}/#{path}",
+													:query => params.map {|k,v| "#{k}=#{v}"}.join('&')
+				end
+				
+				def invoke(path, params={})
+					begin
+						if @@api_key.nil?
+							raise "You must initialize the API key before you run any API queries"
+						end
+						
+						full_params = params.merge 'api-key' => @@api_key
+						
+						uri = build_request_url(path, full_params)
+						
+						# puts "Request  [#{uri}]"
+						
+						reply = uri.read
+						parsed_reply = JSON.parse reply
+						
+						if parsed_reply.nil?
+							# FIXME
+							raise "Empty reply returned from API"
+						end
+						
+						#case parsed_reply['status']
+						# FIXME
+						#end
+						
+						@@copyright = parsed_reply['copyright']
+						
+						parsed_reply
+					rescue OpenURI::HTTPError => e
+						if e.message =~ /^404/
+							return nil
+						end
+						
+						raise "Error connecting to URL #{uri} #{e}"
+					#rescue JSON::ParserError => e
+						# raise RuntimeError, "Invalid JSON returned from CRNR:\n#{reply}"
+					end
+				end
+			end
+		end
+	end
+end

data/lib/nytimes/movies/critic.rb

@@ -0,0 +1,73 @@
+module Nytimes
+	module Movies
+		class Critic < Base
+			attr_reader :display_name, :sort_name, :status, :bio, :seo_name, :photo
+			
+			def initialize(params={})
+				params.each_pair do |k,v|
+					instance_variable_set("@#{k}", v)
+				end
+			end
+			
+			##
+			# Returns reviews made by the critic. Please refer to Review#find for other optional flags that can be applied.
+			def reviews(params={})
+				Review.find(params.merge :reviewer => seo_name)
+			end
+			
+			##
+			# Create a Critic object from a hash snippet returned from the API. You should never need to call this.
+			def self.create_from_api(params={})
+				self.new :display_name => params['display_name'],
+								 :sort_name => params['sort_name'],
+								 :status => params['status'],
+								 :bio => params['bio'],
+								 :seo_name => params['seo_name'],
+								 :photo => MultimediaLink.create_from_api(params['multimedia'])
+			end
+			
+			##
+			# Returns a list of critics that match a given type. The following types are supported:
+			# * <tt>:full_time</tt> - fulltime critics at the New York Times
+			# * <tt>:part_time</tt> - part-time critics at the New York Times
+			# * <tt>:all</tt> - all critics
+			def self.find_by_type(type)
+				key = case type
+				when :full_time
+					'full-time'
+				when :part_time
+					'part-time'
+				when :all
+					'all'
+				else
+					raise ArgumentError, "Type can be :full_time, :part_time, or :all"
+				end
+				
+				reply = invoke("critics/#{key}")
+				results = reply['results']
+				results.map {|r| self.create_from_api(r)}
+			end
+			
+			##
+			# Escapes a critic's name to the SEO variation used for name searches. This is automatically used by Critic#find_by_name, so you don't need to call it.
+			def self.escape_critic_name(name)
+				return name if name =~ /^[a-z\-]+$/  # might be escaped already
+				name.downcase.gsub(/[^a-z\s]/, ' ').gsub(/\s+/, '-')
+			end
+			
+			##
+			# Find a critic record matching a given name. Both the English name (eg, 'A. O. Scott') and the SEO name ('a-o-scott') are valid keys, although the SEO name is
+			# suggested if you want to avoid ambiguity. Only exact matches are used (no last name searches). If a single matching record is found, returns a single Critic instance.
+			# In the admittedly rare chance of 2 distinct critics having the same name, returns an array. Returns nil if no matches are found. 
+			def self.find_by_name(name)
+				name = escape_critic_name(name)
+				reply = invoke("critics/#{name}")
+				return nil if reply.nil? || reply['results'].nil?
+				results = reply['results']
+				critics = results.map {|r| self.create_from_api(r)}
+				return critics.first if critics.length == 1
+				critics
+			end
+		end
+	end
+end

data/lib/nytimes/movies/link.rb

@@ -0,0 +1,24 @@
+module Nytimes
+	module Movies
+		
+		##
+		# Represents a link returned from the Reviews API. Each link has a URL, suggested text, and a link_type which gives you some idea of what the remote
+		# target of the link is. Possible link types include:
+		# FIXME
+		class Link
+			attr_reader :link_type, :url, :suggested_text
+			
+			def initialize(hash={})
+				@url = hash[:url]
+				@link_type = hash[:link_type]
+				@suggested_text = hash[:suggested_text]
+			end
+			
+			##
+			# Create a Link object from a hash snippet returned from the API. You should never need to call this.
+			def self.create_from_api(hash={})
+				Link.new :url => hash['url'], :link_type => hash['type'], :suggested_text => hash['suggested_link_text']
+			end
+		end
+	end
+end

data/lib/nytimes/movies/multimedia_link.rb

@@ -0,0 +1,30 @@
+module Nytimes
+	module Movies
+		
+		##
+		# Represents a link to a multimedia asset from the New York Times. Invariably these are images or thumbnails, but it could also be expanded to
+		# include movies or sound. The following attributes are part of the link. FIXME
+		class MultimediaLink
+			attr_reader :media_type, :url, :height, :width, :credit
+			private_class_method :new
+			
+			def initialize(hash={})
+				hash.each_pair do |k,v|
+					instance_variable_set("@#{k}", v)
+				end
+			end
+			
+			##
+			# Create a MultimediaLink object from a hash snippet returned from the API. You should never need to call this.
+			def self.create_from_api(hash={})
+				return nil if hash.nil? || hash.empty?
+				
+				if hash.key? 'resource'
+					hash = hash['resource']
+				end
+				
+				new(:media_type => hash['type'], :url => hash['src'], :height => hash['height'], :width => hash['width'], :credit => hash['credit'])
+			end
+		end
+	end
+end

data/lib/nytimes/movies/result_set.rb

@@ -0,0 +1,46 @@
+module Nytimes
+	module Movies
+		class ResultSet
+			attr_reader :num_results, :offset, :results
+			
+			def initialize(params, json_reply, coerce_type)
+				@num_results = json_reply['num_results']
+				@params = params.dup
+				@offset = @params['offset'] || 0
+				@results = json_reply['results'].map {|r| coerce_type.create_from_api(r)}
+			end
+			
+			##
+			# The first display index of the result set. Note this is a human index, not a programmer index; it starts from 1
+			def first_index
+				offset + 1
+			end
+			
+			##
+			# The last display index of the result set.
+			def last_index
+				first_index + batch_size - 1
+			end
+			
+			##
+			# The page of this result set
+			def page_number
+				offset / batch_size + 1
+			end
+			
+			##
+			# The calculated number of pages returned from the movies API.
+			def num_pages
+				(num_results.to_f / batch_size).ceil
+			end
+			
+			##
+			# The number of results returned in a result set
+			def batch_size
+				Review::BATCH_SIZE
+			end
+			
+			alias per_page batch_size
+		end
+	end
+end

data/lib/nytimes/movies/review.rb

@@ -0,0 +1,171 @@
+module Nytimes
+	module Movies
+		class Review < Base
+			attr_reader :nyt_movie_id, :display_title, :sort_name, :mpaa_rating, :byline, :headline, :summary_short, :publication_date, :opening_date, :dvd_release_date, \
+			            :date_updated, :seo_name, :critics_pick, :thousand_best, :thumbnail, :link, :related_links, :critic
+			
+			alias :updated_on :date_updated
+			alias :critics_pick? :critics_pick
+			alias :thousand_best? :thousand_best
+			
+			alias :critic_name :byline
+			alias :movie_title :display_title
+			alias :review_title :headline
+			
+			BATCH_SIZE = 20
+			
+			def initialize(params={})
+				params.each_pair do |k,v|
+					instance_variable_set("@#{k}", v)
+				end
+			end
+			
+			class <<self
+				def parse_date(value)
+					return nil if value.nil?
+					Date.parse(value)
+				end
+				
+				def rename_hash_key(hash, key, new_key)
+					hash[new_key] = hash.delete(key)
+				end
+				
+				def coerce_key_boolean(hash, key)
+					hash[key] = hash[key] == 'Y'
+				end
+				
+				def format_date_arg(arg)
+					return arg if arg.is_a? String
+		
+					unless arg.respond_to? :strftime
+						raise "Date argument must respond to strftime"
+					end
+					
+					arg.strftime "%Y-%m-%d"
+				end
+				
+				def date_to_query_arg(date_or_range)
+					return nil if date_or_range.nil?
+					if date_or_range.respond_to?(:first) && date_or_range.respond_to?(:last)
+						"#{format_date_arg(date_or_range.first)};#{format_date_arg(date_or_range.last)}"
+					else
+						format_date_arg(date_or_range)
+					end
+				end
+				
+				def boolean_to_query_arg(arg)
+					return nil if arg.nil?					
+					arg ? 'Y' : 'N'
+				end
+				
+				def create_from_api(hash)
+					hash = hash.dup
+					
+					hash['dvd_release_date'] = parse_date(hash['dvd_release_date'])
+					hash['opening_date'] = parse_date(hash['opening_date'])
+					hash['publication_date'] = parse_date(hash['publication_date'])
+					hash['date_updated'] = parse_date(hash['date_updated'])
+					
+					coerce_key_boolean hash, 'critics_pick'
+					coerce_key_boolean hash, 'thousand_best'
+					
+					multimedia = hash.delete('multimedia')
+					unless multimedia.nil?
+						hash['thumbnail'] = MultimediaLink.create_from_api(multimedia)
+					end
+					
+					if hash.has_key? 'link'
+						hash['link'] = Link.create_from_api(hash['link'])
+					end
+					
+					related = hash.delete('related_urls')
+					unless related.nil?
+						hash['related_links'] = related.map {|l| Link.create_from_api(l) }
+					end
+					
+					rename_hash_key hash, 'seo-name', 'seo_name'
+					new hash
+				end
+				
+				##
+				# Find Movie Reviews that match your parameters. Up to 3 of the following query parameters can be used in a request:
+				#  
+				# * <tt>:text</tt> - search movie title and indexed terms for the movie. To limit to exact matches, enclose parts of the query in single quotes. Otherwise, it will include include partial matches ("head words") as well as exact matches (e.g., president will match president, presidents and presidential). Multiple terms will be ORed together
+				# * <tt>:critics_pick</tt> - set to true to only search movies that are designated critics picks. Should your tastes be more lowbrow, set to false to return movies that are specifically NOT critic's picks. To get all movies, don't send this parameter at all.
+				# * <tt>:thousand_best</tt> - search only movies on the Times List of "Thousand Best Movies Ever Made". Set to false if you want to explicitly search movies not on the list. Omit if you want all movies.
+				# * <tt>:dvd</tt> - if true, search only movies out on DVD. If false, movies not on DVD. Don't specify if you want all movies.
+				# * <tt>:reviewer</tt> - search reviews made by a specific critic. The full-name or the SEO name can be used to specify the critic.
+				# * <tt>:publication_date</tt> - when the review was published. This can be either a single Date or Time object or a range of Times (anything that responds to .first and .last). If you'd prefer, you can also pass in a "YYYY-MM-DD" string
+				# * <tt>:opening_date</tt> - when the movie opened in theaters in the NY Metro area. See +:publication_date+ for argument times.
+        #
+				# In addition, you can also specify the following order and pagination values:
+				# * <tt>:offset</tt> - a maximum of 20 result are returned for queries. To retrieve further pages, an offset from the first result can be specified. This must be a multiple of 20. So +20+ means results +21 - 40+
+				# * <tt>:page</tt> - as a convenience, page will calculate the offset for here. This is not an API parameter and is translated into an offset.
+				# * <tt>:order</tt> - ordering for the results. The following four sorting options are available: <tt>:title</tt> (<em>ascending</em>), <tt>:publication_date</tt>, <tt>:opening_date</tt>, <tt>:dvd_release_date</tt> (<em>most recent first</em>). If you do not specify a sort order, the results will be ordered by closest match.
+				# * <tt>:load_critics</tt> - if true, automatically load the Critic object for each record's reviewer. Note that this requires N additional API calls (where N is the unique number of critics in the result set)
+				def find(in_params={})
+					params = {}
+					
+					if in_params[:text]
+						params['query'] = in_params[:text]
+					end
+
+					params['thousand-best'] = boolean_to_query_arg(in_params[:thousand_best])
+					params['critics-pick'] = boolean_to_query_arg(in_params[:critics_pick])
+					params['dvd'] = boolean_to_query_arg(in_params[:dvd])
+					
+					params['publication-date'] = date_to_query_arg(in_params[:publication_date])
+					params['opening-date'] = date_to_query_arg(in_params[:opening_date])
+										
+					if in_params.has_key? :reviewer
+						params['reviewer'] = Critic.escape_critic_name(in_params[:reviewer])
+					end
+					
+					params['offset'] = in_params[:offset]
+					
+					if in_params.has_key? :page
+						params['offset'] = BATCH_SIZE * (in_params[:page] - 1)
+					end
+					
+					if in_params.has_key? :order
+						params['order'] = case in_params[:order]
+						when :title, :publication_date, :opening_date, :dvd_release_date
+							"by-#{in_params[:order].to_s.gsub('_', '-')}"
+						else
+							raise ArgumentError, "Order can only be :title, :publication_date, :opening_date, or :dvd_release_date"
+						end
+					end
+					
+					params.delete_if {|k, v| v.nil? }
+					
+					reply = invoke 'reviews/search', params
+					out = ResultSet.new(params, reply, Review)			
+
+					if in_params[:load_critics]
+						critics_hash = {}
+						out.results.each do |r|
+							name = r.byline
+							
+							if critics_hash.has_key? name
+								critic = critics_hash[name]
+							else
+								critic = Critic.find_by_name(name)
+								critics_hash[name] = critic
+							end
+							
+							r.instance_variable_set '@critic', critic 
+						end
+					end	
+					
+					out				
+				end
+				
+				def find_by_type(params={})
+				end
+				
+				def find_by_reviewer(params={})
+				end
+			end
+		end
+	end
+end

data/test/nytimes/movies/test_critic.rb

@@ -0,0 +1,105 @@
+require File.dirname(__FILE__) + '/../../test_helper.rb'
+
+CRITIC_HASH = {"display_name" => "A. O. Scott",
+							 "sort_name" => "A. O. Scott",
+							 "status" => "full-time",
+							 "bio" => "A. O. Scott joined The New York Times as a film critic in January 2000. Previously, Mr. Scott was a Sunday book reviewer for Newsday and a frequent contributor to Slate, The New York Review of Books, and many other publications.  He has served on the editorial staffs of Lingua Franca and The New York Review of Books.  He also edited \"A Bolt from the Blue and Other Essays,\" a collection by Mary McCarthy, which was published by The New York Review of Books in 2002. In addition to his film-reviewing duties, Mr. Scott often writes for the Times Magazine and the Book Review.  He was born on July 10, 1966, in Northampton, Mass., and now lives in Brooklyn, N.Y. with his wife and two children.",
+							 "seo_name" => "A-O-Scott",
+							 "multimedia" => {"resource" => {"type" => "image","src" => "http:\/\/graphics8.nytimes.com\/images\/2007\/03\/02\/movies\/scott.163.jpg", "height" => nil,"width" => nil,"credit" => "Tony Cenicola\/<br>The New York Times"}}}
+
+FIND_BY_NAME_REPLY = <<-EOF
+{"status":"OK","copyright":"Copyright (c) 2008 The New York Times Company.  All Rights Reserved.","results":[{"display_name":"A. O. Scott","sort_name":"A. O. Scott","status":"full-time","bio":"A. O. Scott joined The New York Times as a film critic in January 2000. Previously, Mr. Scott was a Sunday book reviewer for Newsday and a frequent contributor to Slate, The New York Review of Books, and many other publications.  He has served on the editorial staffs of Lingua Franca and The New York Review of Books.  He also edited \\\"A Bolt from the Blue and Other Essays,\\\" a collection by Mary McCarthy, which was published by The New York Review of Books in 2002. In addition to his film-reviewing duties, Mr. Scott often writes for the Times Magazine and the Book Review.  He was born on July 10, 1966, in Northampton, Mass., and now lives in Brooklyn, N.Y. with his wife and two children.","seo_name":"A-O-Scott","multimedia":{"resource":{"type":"image","src":"http://graphics8.nytimes.com/images/2007/03/02/movies/scott.163.jpg","height":null,"width":null,"credit":"Tony Cenicola/<br>The New York Times"}}}]}
+EOF
+
+class TestNytimes::TestMovies::TestCritic < Test::Unit::TestCase
+	include Nytimes::Movies
+	
+	# global setup
+	def setup
+		FakeWeb.clean_registry
+		FakeWeb.block_uri_pattern(Base::API_SERVER)
+	end
+	
+	context "Critic.create_from_api" do
+		setup do
+			@critic = Critic.create_from_api(CRITIC_HASH)
+		end
+		
+		should "return an object of the Critic type" do
+			assert_kind_of(Critic, @critic)
+		end
+		
+		%w(display_name sort_name status bio).each do |attr|
+			should "assign the value of the @#{attr} attribute from the '#{attr}' key in the hash" do
+				assert_equal(CRITIC_HASH[attr], @critic.send(attr))
+			end
+		end
+		
+		context "for the multimedia hash value" do
+			should "assign it to the @photo attribute" do
+				assert_not_nil @critic.photo
+			end
+			
+			should "return a Nytimes::Movies::MultimediaLink instance" do
+				assert_kind_of(MultimediaLink, @critic.photo)
+			end
+		end
+	end
+	
+	context "Critic.escape_critic_name" do
+		should "not escape a name that looks like it's escaped" do
+			assert_equal 'a-o-scott', Critic.escape_critic_name('a-o-scott')
+		end
+			
+		should "downcase a name and replace spaces with hyphens" do
+			assert_equal 'mahnola-dargis', Critic.escape_critic_name('Mahnola Dargis')
+		end
+			
+		should "not include punctuation characters in the escaped name" do
+			assert_equal 'a-o-scott', Critic.escape_critic_name('A.O. Scott')
+		end
+	end
+		
+	context "Critic.find_by_name" do
+		context "for a valid critic" do
+			setup do
+				FakeWeb.register_uri(api_url_for('critics/a-o-scott'), :string => FIND_BY_NAME_REPLY)
+				@critic = Critic.find_by_name('a-o-scott')			
+			end
+				
+			should "return a single Nytimes::Movies::Critic instance" do	
+				assert_kind_of(Critic, @critic)
+				assert_equal 'A. O. Scott', @critic.display_name
+			end
+		end
+			
+		context "for a nonexistant critic" do
+			setup do
+				FakeWeb.register_uri(api_url_for('critics/unknown-person'), :string => FIND_BY_NAME_REPLY, :status => [ 404, "Not Found" ])
+				@critic = Critic.find_by_name('Unknown Person')
+			end
+				
+			should "return nil" do
+				assert_nil @critic
+			end
+		end
+	end
+		
+	context "Critic.find_by_type" do
+		setup do
+			FakeWeb.register_uri(api_url_for('critics/full-time'), :string => FIND_BY_NAME_REPLY)
+		end
+			
+		should "raise an ArgumentError if passed anything besides :full_time, :part_time, or :all" do
+			assert_raise(ArgumentError) { Critic.find_by_type(:foo) }
+		end
+			
+		should "return an array of Nytimes::Movies::Critic instances" do
+			@critics = Critic.find_by_type(:full_time)
+						
+			assert_kind_of(Array, @critics)
+			assert @critics.all? {|c| c.is_a? Critic}
+			assert_equal 'A. O. Scott', @critics.first.display_name
+		end
+	end
+end

data/test/nytimes/movies/test_link.rb

@@ -0,0 +1,29 @@
+require File.dirname(__FILE__) + '/../../test_helper.rb'
+
+class TestNytimes::TestMovies::TestLink < Test::Unit::TestCase
+	context "Link.create" do
+		setup do
+			@url = 'http://foo.com'
+			@type = 'article'
+			@suggest_text = 'Suggested Text'
+			
+			@link = Nytimes::Movies::Link.create_from_api('url' => @url, 'type' => @type, 'suggested_link_text' => @suggest_text)
+		end
+		
+		should "return an object of type Nytimes::Movies::Link" do
+			assert_kind_of(Nytimes::Movies::Link, @link)
+		end
+		
+		should "assign the @url attribute from the 'url' key in the hash" do
+			assert_equal(@url, @link.url)
+		end
+		
+		should "assign the @link_type attribute from the 'type' key in the hash" do
+		  assert_equal(@type, @link.link_type)
+		end
+		
+		should "assign the @suggested_text attribute from the 'suggested_link_text' key in the hash" do
+		  assert_equal(@suggest_text, @link.suggested_text)
+		end
+	end
+end

data/test/nytimes/movies/test_multimedia_link.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../../test_helper.rb'
+
+LINK_HASH = {"resource" => {"type" => "image","src" => "http:\/\/graphics8.nytimes.com\/images\/2007\/03\/02\/movies\/scott.163.jpg", "height" => 234, "width" => 345,"credit" => "Tony Cenicola\/<br>The New York Times"}}.freeze
+
+
+class TestNytimes::TestMovies::TestMultimediaLink < Test::Unit::TestCase
+	context "MultimediaLink.create_from_api" do
+		setup do
+			@link = Nytimes::Movies::MultimediaLink.create_from_api(LINK_HASH)
+		end
+		
+		should "return an instance of MultimediaLink" do
+		  assert_kind_of(Nytimes::Movies::MultimediaLink, @link)
+		end
+		
+		should "assign the @media_type attribute from the 'type' key in the hash" do
+		  assert_equal(LINK_HASH['resource']['type'], @link.media_type)
+		end
+		
+		should "assign the @url attribute from the 'src' key in the hash" do
+		  assert_equal(LINK_HASH['resource']['src'], @link.url)
+		end
+		
+		should "assign the @height attribute from the 'height' key in the hash" do
+		  assert_equal(LINK_HASH['resource']['height'], @link.height)
+		end
+		
+		should "assign the @width attribute from the 'width' key in the hash" do
+		  assert_equal(LINK_HASH['resource']['width'], @link.width)
+		end
+		
+		should "assign the @credit attribute from the 'credit' key in the hash" do
+		  assert_equal(LINK_HASH['resource']['credit'], @link.credit)
+		end
+	end
+end

data/test/nytimes/movies/test_result_set.rb

@@ -0,0 +1,48 @@
+require File.dirname(__FILE__) + '/../../test_helper.rb'
+
+class TestNytimes::TestMovies::TestResultSet < Test::Unit::TestCase
+	include Nytimes::Movies
+
+	def setup
+		@reply = MOVIE_RESULT_HASH
+		@params = {'offset' => 40}
+		@result_set = ResultSet.new(@params, @reply, Review)
+	end
+	
+	context "first_index" do
+		should "equal the offset + 1" do
+			assert_equal 41, @result_set.first_index
+		end
+	end
+	
+	context "last_index" do
+		should "equal the first_index + batch_size - 1" do
+			assert_equal 60, @result_set.last_index
+		end
+	end
+
+	context "num_pages" do
+		should "equal the ceiling of num_results / batch_size" do
+			@result_set.instance_variable_set '@num_results', 123
+			
+			assert_equal 7, @result_set.num_pages
+		end
+		
+		should "equal 1 if the number of results < batch_size" do
+			@result_set.instance_variable_set '@num_results', 1
+			assert_equal 1, @result_set.num_pages
+		end
+		
+		should "not erroneously round up if the num_results % batch_size = 0" do
+			@result_set.instance_variable_set '@num_results', 120
+			assert_equal 6, @result_set.num_pages
+		end
+	end
+	
+	context "page_number" do
+		should "equal the offset / batch_size + 1" do
+			assert_equal 3, @result_set.page_number
+		end
+	end
+	
+end

data/test/nytimes/movies/test_review.rb

@@ -0,0 +1,198 @@
+require File.dirname(__FILE__) + '/../../test_helper.rb'
+
+class TestNytimes::TestMovies::TestReview < Test::Unit::TestCase
+	include Nytimes::Movies
+	
+	# global setup
+	def setup
+		FakeWeb.clean_registry
+		FakeWeb.block_uri_pattern(Base::API_SERVER)
+	end
+	
+	def expects_invoke_arg(key, value)
+		Review.expects(:invoke).with(anything, has_entry(key, value)).returns(MOVIE_RESULT_HASH)
+	end
+	
+	context "Review.create_from_api" do
+		setup do
+			@review = Review.create_from_api(MOVIE_REVIEW_HASH)
+		end
+		
+		should "rename seo-name to seo_name" do
+			assert_equal MOVIE_REVIEW_HASH['seo-name'], @review.seo_name
+		end
+
+		should "return a MultimediaLink object for thumbnail" do
+			assert_kind_of MultimediaLink, @review.thumbnail
+		end
+		
+		context "link" do
+			should "return a Link object" do
+				assert_kind_of Link, @review.link
+			end
+			
+			should "map the URL" do
+				assert_equal MOVIE_REVIEW_HASH['link']['url'], @review.link.url
+			end
+		end
+		
+		context "related links" do
+			should "return an array of Link objects" do
+				assert_kind_of Array, @review.related_links
+				@review.related_links.all? {|l| assert_kind_of(Link, l)}
+			end
+			
+			should "be one for each link object" do
+				assert_equal MOVIE_REVIEW_HASH["related_urls"].length, @review.related_links.length
+			end
+		end
+		
+		should "map the critics_pick to a boolean" do
+			assert_equal true, @review.critics_pick?
+		end
+		
+		should "map the thousand_best to a boolean" do
+			assert_equal false, @review.thousand_best?
+		end
+		
+		%w(nyt_movie_id display_title sort_name mpaa_rating byline headline summary_short).each do |field|
+			should "copy the #{field} from the hash into a class attribute" do
+				assert_equal MOVIE_REVIEW_HASH[field], @review.send(field)
+			end
+		end
+
+		%w(dvd_release_date opening_date date_updated publication_date).each do |date|		
+			should "parse the #{date} from the hash into a Ruby Date" do
+				assert_kind_of Date, @review.send(date)
+				assert_equal Date.parse(MOVIE_REVIEW_HASH[date]), @review.send(date)
+			end
+		end
+	end
+
+	context "Review.find" do
+		setup do
+			FakeWeb.register_uri(api_url_for('reviews/search', 'query' => 'constantine'), :string => MOVIE_RESULT_REPLY)
+		end
+		
+		should "call the reviews/search endpoint"
+		
+		should "return an instance of ResultSet" do
+			result_set = Review.find(:text => 'constantine')
+			assert_kind_of(ResultSet, result_set)
+		end
+		
+		context "input parameters" do
+			%w(critics_pick dvd thousand_best).each do |flag|
+				context flag do
+					should "send Y if the #{flag} is true" do
+						expects_invoke_arg(flag.gsub('_','-'), 'Y')
+						Review.find(flag.to_sym => true)
+					end
+				
+					should "send N if the #{flag} is false" do
+						expects_invoke_arg(flag.gsub('_','-'), 'N')
+						Review.find(flag.to_sym => false)
+					end
+				end
+			end
+
+			%w(opening_date publication_date).each do |field|
+				context field do
+					should "accept a single Date object" do
+						d = Date.parse('1/1/2008')
+						expects_invoke_arg(field.gsub('_','-'), d.strftime('%Y-%m-%d'))
+						Review.find(field.to_sym => d)
+					end
+					
+					should "accept a single Time object" do
+						t = Time.parse('1/1/2008')
+						expects_invoke_arg(field.gsub('_','-'), t.strftime('%Y-%m-%d'))
+						Review.find(field.to_sym => t)	
+					end
+					
+					should "accept a range of Date objects" do
+						d1 = Date.parse('1/1/2008')
+						d2 = Date.parse('1/30/2008')
+						expects_invoke_arg(field.gsub('_','-'), "#{d1.strftime('%Y-%m-%d')};#{d2.strftime('%Y-%m-%d')}")
+						Review.find(field.to_sym => d1..d2)
+					end
+					
+					should "accept a range of Time objects" do
+						t1 = Time.parse('1/1/2008')
+						t2 = Time.parse('1/30/2008')
+						expects_invoke_arg(field.gsub('_','-'), "#{t1.strftime('%Y-%m-%d')};#{t2.strftime('%Y-%m-%d')}")
+						Review.find(field.to_sym => t1..t2)	
+					end
+					
+					should "accept an array of Date objects" do
+						d1 = Date.parse('1/1/2008')
+						d2 = Date.parse('1/30/2008')
+						expects_invoke_arg(field.gsub('_','-'), "#{d1.strftime('%Y-%m-%d')};#{d2.strftime('%Y-%m-%d')}")
+						Review.find(field.to_sym => [d1,d2])
+					end
+					
+					should "accept an array of Time objects" do
+						t1 = Time.parse('1/1/2008')
+						t2 = Time.parse('1/30/2008')
+						expects_invoke_arg(field.gsub('_','-'), "#{t1.strftime('%Y-%m-%d')};#{t2.strftime('%Y-%m-%d')}")
+						Review.find(field.to_sym => [t1,t2])
+					end
+				end
+			end
+
+			context "offset" do
+				should "send the offset argument through" do
+					expects_invoke_arg('offset', 60)
+					Review.find(:offset => 60)
+				end
+			end
+			
+			context "page" do
+				should "set the offset to be batchsize * page-1" do
+					expects_invoke_arg('offset', 40)
+					Review.find(:page => 3)
+				end
+			end
+		
+			context "ordering parameters" do
+				should "send a by-title to the API for :title order" do
+					expects_invoke_arg('order', 'by-title')
+					Review.find(:order => :title)
+				end
+				
+				should "send a by-publication-date to the API for :publication_date order" do
+					expects_invoke_arg('order', 'by-publication-date')
+					Review.find(:order => :publication_date)
+				end
+				
+				should "send a by-opening-date to the API for :opening_date order" do
+					expects_invoke_arg('order', 'by-opening-date')
+					Review.find(:order => :opening_date)
+				end
+				
+				should "send a by-dvd-release-date to the API for :dvd_release_date order" do
+					expects_invoke_arg('order', 'by-dvd-release-date')
+					Review.find(:order => :dvd_release_date)
+				end
+				
+				should "raise an ArgumentError if the ordering is not one of those allowed" do
+					assert_raise(ArgumentError) do
+						Review.find(:order => :random)
+					end
+				end
+			end
+			
+			context "reviewer" do
+				should "escape the Critic Name to the SEO form" do
+					expects_invoke_arg('reviewer', 'a-o-scott')
+					Review.find(:reviewer => 'A. O. Scott')
+				end
+				
+				should "not escape again if already in SEO form" do
+					expects_invoke_arg('reviewer', 'a-o-scott')
+					Review.find(:reviewer => 'A. O. Scott')
+				end
+			end			
+		end
+	end
+end

data/test/test_helper.rb

@@ -0,0 +1,46 @@
+require 'test/unit'
+require 'rubygems'
+gem 'thoughtbot-shoulda'
+require 'shoulda'
+gem 'FakeWeb'
+require 'fake_web'
+require 'mocha'
+require 'json'
+
+require File.dirname(__FILE__) + '/../lib/nytimes/movies'
+
+API_KEY = '13e234323232222'
+Nytimes::Movies::Base.api_key = API_KEY
+
+def api_url_for(path, params = {})
+	full_params = params.merge 'api-key' => API_KEY
+	Nytimes::Movies::Base.build_request_url(path, full_params).to_s
+end
+
+module TestNytimes
+	module TestMovies
+	end
+end
+
+MOVIE_REVIEW_HASH =  {"dvd_release_date"=>"2008-09-16", "opening_date"=>"2008-04-18", 
+											"multimedia"=>{"resource"=>{"src"=>"http://graphics8.nytimes.com/images/2008/04/18/arts/18sword-75.jpg", "type"=>"thumbnail", "height"=>75, "width"=>75}}, 
+											"byline"=>"Stephen Holden", 
+											"nyt_movie_id"=>405736, 
+											"publication_date"=>"2008-04-18", "critics_pick"=>"Y", "sort_name"=>"Constantine's Sword", "headline"=>"", 
+											"summary_short"=>"u201cConstantineu2019s Swordu201d asks: When your core beliefs conflict with church doctrine, how far should your loyalty to the church extend?", 
+											"thousand_best"=>"N",
+											"mpaa_rating"=>"NR", 
+											"related_urls"=>[{"suggested_link_text"=>"Overview of Constantine's Sword", "url"=>"http://movies.nytimes.com/movie/405736/Constantine-s-Sword/overview", "type"=>"overview"}, {"suggested_link_text"=>"Tickets & Showtimes for Constantine's Sword", "url"=>"http://movies.nytimes.com/movie/405736/Constantine-s-Sword/showtimes", "type"=>"showtimes"}, {"suggested_link_text"=>"Cast, Credits & Awards for Constantine's Sword", "url"=>"http://movies.nytimes.com/movie/405736/Constantine-s-Sword/details", "type"=>"awards"}, {"suggested_link_text"=>"Readers' Reviews of Constantine's Sword", "url"=>"http://movies.nytimes.com/movie/405736/Constantine-s-Sword/rnr", "type"=>"community"}, {"suggested_link_text"=>"Trailers & Clips for Constantine's Sword", "url"=>"http://movies.nytimes.com/movie/405736/Constantine-s-Sword/trailers", "type"=>"trailers"}], 
+											"seo-name"=>"Constantine-s-Sword",
+											"display_title"=>"Constantine's Sword", 
+											"link"=>{"suggested_link_text"=>"Read the New York Times Review of Constantine's Sword", "url"=>"http://movies.nytimes.com/", "type"=>"article"}, 
+											"date_updated"=>"2008-08-21 12:10:38"}
+
+MOVIE_RESULT_HASH = {
+	"status" => "OK",
+	"copyright" => "Copyright (c) 2008 The New York Times Company.  All Rights Reserved.",
+	"num_results" => 1,
+	"results" => [MOVIE_REVIEW_HASH]
+}
+
+MOVIE_RESULT_REPLY = MOVIE_RESULT_HASH.to_json

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: nytimes-movies
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Jacob Harris
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-12 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A gem for talking to the New York Times Movie Reviews API
+email: jharris@nytimes.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- History.txt
+- Rakefile
+- README.rdoc
+- VERSION.yml
+- lib/nytimes/movies/base.rb
+- lib/nytimes/movies/critic.rb
+- lib/nytimes/movies/link.rb
+- lib/nytimes/movies/multimedia_link.rb
+- lib/nytimes/movies/result_set.rb
+- lib/nytimes/movies/review.rb
+- lib/nytimes/movies.rb
+- lib/nytimes-movies.rb
+- test/nytimes/movies/test_critic.rb
+- test/nytimes/movies/test_link.rb
+- test/nytimes/movies/test_multimedia_link.rb
+- test/nytimes/movies/test_result_set.rb
+- test/nytimes/movies/test_review.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/harrisj/nytimes-moves
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.2
+signing_key: 
+specification_version: 2
+summary: A gem for talking to the New York Times Movie Reviews API
+test_files: []
+