harrisj-nytimes-articles 0.1.1 → 0.1.2

data/VERSION.yml

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

data/lib/nytimes_articles/article.rb

@@ -2,6 +2,10 @@ require 'rubygems'
 
 module Nytimes
 	module Articles
+		##
+		# The Article class represents a single article returned from the New York Times Article Search API. Note that an article can have many attributes
+		# but these are not necessarily populated unless you explicitly request them in the reply from the server via the <tt>:fields</tt> parameter to 
+		# search (or use <tt>:fields => :all</tt>). 
 		class Article < Base
 			RAW_FIELDS = %w(url)
 			TEXT_FIELDS = %w(abstract author body byline lead_paragraph nytd_lead_paragraph nytd_title title)
@@ -10,10 +14,13 @@ module Nytimes
 			IMAGE_FIELDS = %w(small_image small_image_url small_image_height small_image_width)
 			MULTIMEDIA_FIELDS = %w(multimedia related_multimedia)
 
-			ALL_FIELDS = TEXT_FIELDS + RAW_FIELDS + NUMERIC_FIELDS + BOOLEAN_FIELDS + IMAGE_FIELDS + MULTIMEDIA_FIELDS + Facet::ALL_FACETS
+			ALL_FIELDS = TEXT_FIELDS + RAW_FIELDS + NUMERIC_FIELDS + BOOLEAN_FIELDS + MULTIMEDIA_FIELDS + Facet::ALL_FACETS + IMAGE_FIELDS
 
 			attr_reader *ALL_FIELDS
 			
+			# special additional objects
+			attr_reader :thumbnail
+			
 			# Scalar facets
 			attr_reader :page, :column, :pub_month, :pub_year, :pub_day, :day_of_week, :desk, :date, :section_page, :source
 
@@ -53,7 +60,7 @@ module Nytimes
 				:nytd_title => text_field(params['nytd_title']),
 				:nytd_lead_paragraph => text_field(params['nytd_lead_paragraph']),
 				:related_multimedia => nil, # FIXME
-				:image => nil, # FIXME
+				:thumbnail => Thumbnail.init_from_api(params),
 				:title => text_field(params['title']),
 				:url => params['url'],
 				:word_count => integer_field(params['word_count']),
@@ -151,16 +158,18 @@ module Nytimes
 			# * <tt>Facet::NYTD_SECTION</tt> - The section the article appears in (on NYTimes.com)
 			# * <tt>Facet::NYTD_WORKS_MENTIONED</tt> - Literary works mentioned (titles formatted for use on NYTimes.com)
 			#
+			# Note that for your convenience you can also search with symbol versions of the constants (<tt>:geo => ['MANHATTAN']</tt>). Even pluralization is supported. To get the string API version of the facet use Facet#symbol_name
+			#
 			# The following two search fields are used for facet searching:
-			# * <tt>:search_facets</tt> - takes a single value or array of facets to search. Facets can either be specified as array pairs (like <tt>[Facet::GEOGRAPHIC, 'CALIFORNIA']</tt>) or facets returned from a previous search can be passed directly. A single string can be passed as well if you have hand-crafted string.
-			# * <tt>:exclude_facets</tt> - similar to <tt>:search_facets</tt> but is used to specify a list of facets to exclude.
+			# * <tt>:only_facets</tt> - takes a single value or array of facets to search. Facets can either be specified as array pairs (like <tt>[Facet::GEOGRAPHIC, 'CALIFORNIA']</tt>) or facets returned from a previous search can be passed directly. A single string can be passed as well if you have hand-crafted string.
+			# * <tt>:except_facets</tt> - similar to <tt>:only_facets</tt> but is used to specify a list of facets to exclude.
 			#
 			# == OTHER SEARCH FIELDS
-			# * <tt>:fee</tt> - to be implemented
+			# * <tt>:fee</tt> - if set to true, only returns articles that must be purchased. If false, returns only free articles. If not specified, returns all articles
 			# * <tt>:begin_date</tt>, <tt>:end_date</tt> - the parameters are used to specify a start and end date for search results. BOTH of these must be provided or the API will return an error. Accepts either a Time/Date argument or a string of the format YYYYMMDD. For convenience the following alternative methods are provided
 			# * <tt>:before</tt> - an alternative to :end_date. Automatically adds a :before_date of sometime in 1980 if no :since argument is also provided; to be implemented
 			# * <tt>:since</tt> - An alternative to :begin_date. Automatically adds an :end_date of Time.now if no :before argument is provided; to be implemented.
-			# * <tt>:has_thumbnail</tt> - to be implemented
+			# * <tt>:has_thumbnail</tt> - returns only articles that have thumbnail images associated. Note that to see the thumbnails, you must specify either <tt>:thumbnail</tt> or <tt>:all</tt> in the <tt>:fields</tt> argument).
 			# * <tt>:has_multimedia</tt> - to be implemented
 			#
 			# == FACET SUMMARIES
@@ -193,10 +202,10 @@ module Nytimes
 				api_params = {}
 
 				add_query_params(api_params, params)
-				add_search_facets_param(api_params, params)
+				add_facet_conditions_params(api_params, params)
 				add_boolean_params(api_params, params)
-				add_fields_param(api_params, params)
 				add_facets_param(api_params, params)
+				add_fields_param(api_params, params)
 				add_rank_params(api_params, params)
 				add_date_params(api_params, params)
 				add_offset_params(api_params, params)
@@ -239,7 +248,16 @@ module Nytimes
 
 			def self.add_facets_param(out_params, in_params)
 				if in_params[:facets]
-					out_params['facets'] = in_params[:facets].to_a.join(',')
+					out_params['facets'] = in_params[:facets].to_a.map {|f| Facet.symbol_name(f)}.join(',')
+				end
+			end
+
+			def self.field_param(name)
+				case name.to_s
+				when 'thumbnail'
+					IMAGE_FIELDS.join(',')
+				else
+					name.to_s
 				end
 			end
 
@@ -249,10 +267,15 @@ module Nytimes
 					# do nothing
 				when :all
 					out_params['fields'] = ALL_FIELDS.join(',')
+				when :none
+					out_params['fields'] = ' '
+					unless out_params['facets']
+						out_params['facets'] = Facet::DEFAULT_RETURN_FACETS.join(',')
+					end
 				when String, Symbol
-					out_params['fields'] = in_params[:fields].to_s
+					out_params['fields'] = field_param(in_params[:fields])
 				when Array
-					out_params['fields'] = in_params[:fields].map {|f| f.to_s}.join(',')
+					out_params['fields'] = in_params[:fields].map {|f| field_param(f)}.join(',')
 				else
 					raise ArgumentError, "Fields must either be :all, a single field name, or an array of field names (either strings or symbols)"
 				end	
@@ -279,19 +302,23 @@ module Nytimes
 					value = [value]
 				end
 				
+				if name.is_a? Symbol
+					name = Facet.symbol_name(name)
+				end
+				
 				"#{'-' if exclude}#{name}:[#{value.join(',')}]"
 			end
 
 			def self.parse_facet_params(facets, exclude = false)
-				search_facets = []
+				facet_args = []
 						
 				case facets
 				when nil
 					# do nothing
 				when String
-					search_facets = [facets]
+					facet_args = [facets]
 				when Facet
-					search_facets = [facet_argument(facets.facet_type, facets.term, exclude)]
+					facet_args = [facet_argument(facets.facet_type, facets.term, exclude)]
 				when Array
 					unless facets.all? {|f| f.is_a? Facet }
 						raise ArgumentError, "Only Facet instances can be passed in as an array; use Hash for Facet::Name => values input"
@@ -307,22 +334,22 @@ module Nytimes
 					end
 					
 					facet_hash.each_pair do |k,v|
-						search_facets << facet_argument(k, v, exclude)
+						facet_args << facet_argument(k, v, exclude)
 					end
 				when Hash
 					facets.each_pair do |k,v|
-						search_facets << facet_argument(k, v, exclude)
+						facet_args << facet_argument(k, v, exclude)
 					end
 				end
 				
-				search_facets
+				facet_args
 			end
 			
-			def self.add_search_facets_param(out_params, in_params)
+			def self.add_facet_conditions_params(out_params, in_params)
 				query = out_params['query']
 
-				search_facets = parse_facet_params(in_params[:search_facets])
-				exclude_facets = parse_facet_params(in_params[:exclude_facets], true)
+				search_facets = parse_facet_params(in_params[:only_facets])
+				exclude_facets = parse_facet_params(in_params[:except_facets], true)
 				
 				unless search_facets.empty? && exclude_facets.empty?
 					out_params['query'] = ([query] + search_facets + exclude_facets).compact.join(' ')

data/lib/nytimes_articles/exceptions.rb

@@ -1,23 +1,37 @@
 module Nytimes
 	module Articles
+		##
+		# The generic Error class from which all other Errors are derived.
 		class Error < ::RuntimeError
 		end
 		
+		##
+		# This error is thrown if there are problems authenticating your API key.
 		class AuthenticationError < Error
 		end
 		
+		##
+		# This error is thrown if the request was not parsable by the API server.
 		class BadRequestError < Error
 		end
 		
+		##
+		# This error is thrown if the response from the API server is not parsable.
 		class BadResponseError < Error
 		end
 		
+		##
+		# This error is thrown if there is an error connecting to the API server.
 		class ServerError < Error
 		end
 		
+		##
+		# This error is thrown if there is a timeout connecting to the server (to be implemented).
 		class TimeoutError < Error
 		end
 		
+		##
+		# This error is thrown for general connection errors to the API server.
 		class ConnectionError < Error
 		end
 	end

data/lib/nytimes_articles/facet.rb

@@ -1,7 +1,24 @@
 module Nytimes
 	module Articles
+		
+		##
+		# This class represents a Facet used in the ArticleSearch API. Facets can be used to both search for matching articles (see Article#search) and
+		# are also returned as article and search metadata. Facets are made up of 3 parts:
+		# * <tt>facet_type</tt> - a string; see Article#search for a list of facet types
+		# * <tt>term</tt> - a string as well
+		# * <tt>count</tt> - Facets returned as search metadata (via the <tt>:facets</tt> parameter to Article#search) also include a non-nil count of matching articles for that facet
 		class Facet
-			attr_reader :term, :count, :facet_type
+			##
+			# The term for the facet
+			attr_reader :term
+			
+			##
+			# The number of times this facet has appeared in the search results (note: this only applies for facets returned in the facets header on an Article#search)
+			attr_reader :count
+			
+			##
+			# The facet type
+			attr_reader :facet_type
 			
 			# Facet name constants
 			CLASSIFIERS = 'classifiers_facet'
@@ -31,23 +48,64 @@ module Nytimes
 			NYTD_SECTION = 'nytd_section_facet'
 			NYTD_WORKS_MENTIONED = 'nytd_works_mentioned_facet'
 			
-			# The best 5 facets to return
-		  DEFAULT_RETURN_FACETS = [NYTD_DESCRIPTION, NYTD_GEO, NYTD_ORGANIZATION, NYTD_PERSON, NYTD_SECTION]
+			# The default 5 facets to return
+		  DEFAULT_RETURN_FACETS = [DESCRIPTION, GEO, ORGANIZATION, PERSON, DESK]
 		
 			ALL_FACETS = [CLASSIFIERS, COLUMN, DATE, DAY_OF_WEEK, DESCRIPTION, DESK, GEO, MATERIAL_TYPE, ORGANIZATION, PAGE, PERSON, PUB_DAY,
 														PUB_MONTH, PUB_YEAR, SECTION_PAGE, SOURCE, WORKS_MENTIONED, NYTD_BYLINE, NYTD_DESCRIPTION, NYTD_GEO,
 														NYTD_ORGANIZATION, NYTD_PERSON, NYTD_SECTION, NYTD_WORKS_MENTIONED]
 			
+			##
+			# Initializes the facet. There is seldom a reason for you to call this.
 			def initialize(facet_type, term, count)
 				@facet_type = facet_type
 				@term = term
 				@count = count
 			end
 			
-			# def self.init_from_api(type, hash)
-			# 	self.new(type, hash['term'], hash['count'].to_i)
-			# end
+			##
+			# Takes a symbol name and subs it to a string constant
+			def self.symbol_name(facet)
+				case facet
+				when String
+					return facet
+				when Facet
+					return facet.facet_type
+				when Symbol
+					# fall through
+				else
+					raise ArgumentError, "Unsupported type to Facet#symbol_to_api_name"
+				end
+				
+				case facet
+				when :geography
+					GEO
+				when :org, :orgs
+					ORGANIZATION
+				when :people
+					PERSON
+				when :nytd_geography
+					NYTD_GEO
+				when :nytd_org, :nytd_orgs
+					NYTD_ORGANIZATION
+				when :nytd_people
+					NYTD_PERSON
+				else
+					name = facet.to_s.upcase
+					
+					if const_defined?(name)
+						const_get(name)
+					elsif name =~ /S$/ && const_defined?(name.gsub(/S$/, ''))
+						const_get(name.gsub(/S$/, ''))
+					else
+						raise ArgumentError, "Unable to find a matching facet key for symbol :#{facet}"
+					end
+				end
+			end
 			
+			##
+			# Initializes a selection of Facet objects returned from the API. Used for marshaling Facets in articles and metadata from search results
+			# (Note: some facets are returned as scalar values)
 			def self.init_from_api(api_hash)
 				return nil if api_hash.nil?
 				

data/lib/nytimes_articles/result_set.rb

@@ -3,9 +3,29 @@ require 'forwardable'
 
 module Nytimes
 	module Articles
+		##
+		# The ResultSet is returned by Article#search and contains an array of up to 10 results out of the total matches. For your convenience, this
+		# object provides a selection of array methods on the underlying collection of articles.
 		class ResultSet < Base
 			extend Forwardable
-			attr_reader :offset, :total_results, :results, :facets
+
+			##
+			# The offset of the result_set. Note that this is essentially the ordinal position of the batch among all results. First 10 results are offset
+			# 0, the next 10 are offset 1, etc.
+			attr_reader :offset
+			
+			##
+			# The total results that matched the query.
+			attr_reader :total_results
+			
+			##
+			# The results array of articles returned. Note that if you call Articles#find with :fields => :none, this will return nil even if 
+			# there are matching results.
+			attr_reader :results
+			
+			##
+			# If you have specified a list of <tt>:facets</tt> for Article#search, they will be returned in a hash keyed by the facet name here.
+			attr_reader :facets
 			
 			BATCH_SIZE = 10
 			
@@ -18,16 +38,22 @@ module Nytimes
 				@facets = params[:facets]
 			end
 			
+			##
+			# For your convenience, the page_number method is an alternate version of #offset that counts up from 1.
 			def page_number
 				return 0 if @total_results == 0
 				@offset + 1
 			end
 			
+			##
+			# Calculates the total number of pages in the results based on the standard batch size and total results.
 			def total_pages
 				return 0 if @total_results == 0
 				(@total_results.to_f / BATCH_SIZE).ceil
 			end
 			
+			##
+			# Used to initialize a new result_set from Article#search.
 			def self.init_from_api(api_hash)
 				self.new(:offset => integer_field(api_hash['offset']),
 								 :total_results => integer_field(api_hash['total']),

data/lib/nytimes_articles/thumbnail.rb

@@ -0,0 +1,30 @@
+module Nytimes
+	module Articles
+		##
+		# If requested in <tt>:fields</tt> for an article search, some articles are returned with a matching thumbnail image. The several thumbnail
+		# fields are collected together into a single Thumbnail instance for your convenience. 
+		class Thumbnail
+			attr_reader :url, :width, :height
+			
+			def initialize(url, width, height)
+				@url = url
+				@width = width
+				@height = height
+			end
+			
+			def self.init_from_api(api_hash)
+				return nil unless !api_hash.nil? && api_hash['small_image_url']
+				
+				unless api_hash['small_image_width'].nil?
+					width = api_hash['small_image_width'].to_i
+				end
+				
+				unless api_hash['small_image_height'].nil?
+					height = api_hash['small_image_height'].to_i
+				end
+				
+				new(api_hash['small_image_url'], width, height)
+			end
+		end
+	end
+end

data/lib/nytimes_articles.rb

@@ -4,5 +4,6 @@ $KCODE = 'UTF8'
 require File.join(File.dirname(__FILE__), 'nytimes_articles', 'exceptions')
 require File.join(File.dirname(__FILE__), 'nytimes_articles', 'base')
 require File.join(File.dirname(__FILE__), 'nytimes_articles', 'facet')
+require File.join(File.dirname(__FILE__), 'nytimes_articles', 'thumbnail')
 require File.join(File.dirname(__FILE__), 'nytimes_articles', 'article')
 require File.join(File.dirname(__FILE__), 'nytimes_articles', 'result_set')

data/test/nytimes/articles/test_article.rb

@@ -81,26 +81,26 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 			end
 		end
 		
-		context "search_facets" do
+		context "only_facets" do
 			should "accept a String" do
 				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA]"))
-				Article.search :search_facets => "#{Facet::GEO}:[CALIFORNIA]"
+				Article.search :only_facets => "#{Facet::GEO}:[CALIFORNIA]"
 			end
 			
 			should "accept a single hash value Facet string to a term" do
 				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA]"))
-				Article.search :search_facets => {Facet::GEO => 'CALIFORNIA'}
+				Article.search :only_facets => {Facet::GEO => 'CALIFORNIA'}
 			end
 			
 			should "accept an Facet string hashed to an array terms" do
 				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA,GREAT BRITAIN]"))
-				Article.search :search_facets => {Facet::GEO => ['CALIFORNIA', 'GREAT BRITAIN']}
+				Article.search :only_facets => {Facet::GEO => ['CALIFORNIA', 'GREAT BRITAIN']}
 			end
 			
 			should "accept a single Facet object" do
 				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
 				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA]"))
-				Article.search :search_facets => f
+				Article.search :only_facets => f
 			end
 			
 			should "accept an array of Facet objects" do
@@ -108,7 +108,7 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 				f2 = Facet.new(Facet::NYTD_ORGANIZATION, 'University Of California', 12)
 				
 				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA] #{Facet::NYTD_ORGANIZATION}:[University Of California]"))
-				Article.search :search_facets => [f, f2]
+				Article.search :only_facets => [f, f2]
 			end
 			
 			should "merge multiple Facets objects in the array of the same type into one array" do
@@ -116,35 +116,35 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 				f2 = Facet.new(Facet::GEO, 'IOWA', 12)
 				
 				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA,IOWA]"))
-				Article.search :search_facets => [f, f2]
+				Article.search :only_facets => [f, f2]
 			end
 			
 			should "not stomp on an existing query string" do
 				Article.expects(:invoke).with(has_entry("query", "ice cream #{Facet::GEO}:[CALIFORNIA]"))
-				Article.search "ice cream", :search_facets => {Facet::GEO => "CALIFORNIA"}
+				Article.search "ice cream", :only_facets => {Facet::GEO => "CALIFORNIA"}
 			end
 		end
 
-		context "exclude_facets" do
+		context "except_facets" do
 			should "accept a String" do
 				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA]"))
-				Article.search :exclude_facets => "-#{Facet::GEO}:[CALIFORNIA]"
+				Article.search :except_facets => "-#{Facet::GEO}:[CALIFORNIA]"
 			end
 			
 			should "accept a single hash value Facet string to a term" do
 				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA]"))
-				Article.search :exclude_facets => {Facet::GEO => 'CALIFORNIA'}
+				Article.search :except_facets => {Facet::GEO => 'CALIFORNIA'}
 			end
 			
 			should "accept an Facet string hashed to an array terms" do
 				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA,GREAT BRITAIN]"))
-				Article.search :exclude_facets => {Facet::GEO => ['CALIFORNIA', 'GREAT BRITAIN']}
+				Article.search :except_facets => {Facet::GEO => ['CALIFORNIA', 'GREAT BRITAIN']}
 			end
 			
 			should "accept a single Facet object" do
 				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
 				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA]"))
-				Article.search :exclude_facets => f
+				Article.search :except_facets => f
 			end
 			
 			should "accept an array of Facet objects" do
@@ -152,7 +152,7 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 				f2 = Facet.new(Facet::NYTD_ORGANIZATION, 'University Of California', 12)
 				
 				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA] -#{Facet::NYTD_ORGANIZATION}:[University Of California]"))
-				Article.search :exclude_facets => [f, f2]
+				Article.search :except_facets => [f, f2]
 			end
 			
 			should "merge multiple Facets objects in the array of the same type into one array" do
@@ -160,12 +160,12 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 				f2 = Facet.new(Facet::GEO, 'IOWA', 12)
 				
 				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA,IOWA]"))
-				Article.search :exclude_facets => [f, f2]
+				Article.search :except_facets => [f, f2]
 			end
 			
 			should "not stomp on an existing query string" do
 				Article.expects(:invoke).with(has_entry("query", "ice cream -#{Facet::GEO}:[CALIFORNIA]"))
-				Article.search "ice cream", :exclude_facets => {Facet::GEO => "CALIFORNIA"}
+				Article.search "ice cream", :except_facets => {Facet::GEO => "CALIFORNIA"}
 			end
 		end
 
@@ -190,15 +190,32 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 			end
 			
 			context "for the :none argument" do
-				should "request a blank space for the fields argument"
-				should "request the standard :facets if no :facets have been explicitly provided"
-				should "request the given :facets field if provided"
+				should "request a blank space for the fields argument" do
+					Article.expects(:invoke).with(has_entry('fields', ' '))
+					Article.search "FOO BAR", :fields => :none
+				end
+				
+				should "request the standard :facets if no :facets have been explicitly provided" do
+					Article.expects(:invoke).with(has_entry('facets', Facet::DEFAULT_RETURN_FACETS.join(',')))
+					Article.search "FOO BAR", :fields => :none	
+				end
+				
+				should "request the given :facets field if provided" do
+					Article.expects(:invoke).with(has_entry('facets', "#{Facet::GEO}"))
+					Article.search "FOO BAR", :fields => :none, :facets => Facet::GEO
+				end
 			end
 			
 			context ":thumbnail" do
-				should "accept the symbol version of the argument"
-				should "accept the string version of the argument"
-				should "request all the thumbnail image fields from the API"
+				should "accept the symbol version of the argument" do
+					Article.expects(:invoke).with(has_entry('fields', Article::IMAGE_FIELDS.join(',')))
+					Article.search "FOO BAR", :fields => :thumbnail
+				end
+				
+				should "accept the string version of the argument" do
+					Article.expects(:invoke).with(has_entry('fields', Article::IMAGE_FIELDS.join(',')))
+					Article.search "FOO BAR", :fields => 'thumbnail'
+				end				
 			end
 			
 			context ":multimedia" do
@@ -449,6 +466,23 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 				assert_nil article.page
 			end
 		end
+		
+		context "@thumbnail" do
+			should "assign nil to thumbnail otherwise" do
+				article = Article.init_from_api({"foo" => "bar"})
+				assert_nil article.thumbnail
+			end
+
+			should "create a thumbnail object if a small_image_url is part of the return hash" do
+				article = Article.init_from_api(ARTICLE_API_HASH2)
+				thumbnail = article.thumbnail
+				assert_not_nil thumbnail
+				assert_kind_of Thumbnail, thumbnail
+				assert_equal ARTICLE_API_HASH2['small_image_url'], thumbnail.url
+				assert_equal ARTICLE_API_HASH2['small_image_width'].to_i, thumbnail.width
+				assert_equal ARTICLE_API_HASH2['small_image_height'].to_i, thumbnail.height
+			end
+		end
 	end
 end
 

data/test/nytimes/articles/test_facet.rb

@@ -43,4 +43,67 @@ class TestNytimes::TestArticles::TestFacet < Test::Unit::TestCase
 			assert @facets[first_key].all? {|f| f.facet_type == first_key }
 		end
 	end
+	
+	context "Facet.symbol_name" do
+		[:geo, :geography].each do |sym|
+			should "return Facet::GEO for #{sym}" do
+				assert_equal Facet::GEO, Facet.symbol_name(sym)
+			end
+		end
+
+		[:org, :orgs, :organization, :organizations].each do |sym|
+			should "return Facet::ORGANIZATION for #{sym}" do
+				assert_equal Facet::ORGANIZATION, Facet.symbol_name(sym)
+			end
+		end
+		
+		[:people, :person, :persons].each do |sym|
+			should "return Facet::PERSON for #{sym}" do
+				assert_equal Facet::PERSON, Facet.symbol_name(sym)
+			end
+		end
+		
+		[:nytd_geo, :nytd_geography].each do |sym|
+			should "return Facet::NYTD_GEO for #{sym}" do
+				assert_equal Facet::NYTD_GEO, Facet.symbol_name(sym)
+			end
+		end
+
+		[:nytd_org, :nytd_orgs, :nytd_organization, :nytd_organizations].each do |sym|
+			should "return Facet::NYTD_ORGANIZATION for #{sym}" do
+				assert_equal Facet::NYTD_ORGANIZATION, Facet.symbol_name(sym)
+			end
+		end
+		
+		[:nytd_people, :nytd_person, :nytd_persons].each do |sym|
+			should "return Facet::NYTD_PERSON for #{sym}" do
+				assert_equal Facet::NYTD_PERSON, Facet.symbol_name(sym)
+			end
+		end
+		
+		should "look for a matching constant and use that value" do
+			assert_equal Facet::SOURCE, Facet.symbol_name(:source)
+		end
+		
+		should "singularize the symbol when looking for a constant if no match for the plural form" do
+			assert_equal Facet::PAGE, Facet.symbol_name(:pages)
+		end
+		
+		should "return the string passed in if passed a string" do
+			assert_equal "FOOBAR", Facet.symbol_name('FOOBAR')
+		end
+		
+		should "return the facet's facet_type if passed a Facet object" do
+			f = Facet.new(Facet::ORGANIZATION, 'THE NEW YORK TIMES', nil)
+			assert_equal Facet::ORGANIZATION, Facet.symbol_name(f)
+		end
+		
+		should "raise an ArgumentError if not passed a symbol" do
+			assert_raise(ArgumentError) { Facet.symbol_name(23) }
+		end
+		
+		should "raise an ArgumentError if unable to find a matching Facet constant" do
+			assert_raise(ArgumentError) { Facet.symbol_name(:clown) }
+		end
+	end
 end

data/test/nytimes/articles/test_thumbnail.rb

@@ -0,0 +1,47 @@
+require File.dirname(__FILE__) + '/../../test_helper.rb'
+
+class TestNytimes::TestArticles::TestThumbnail < Test::Unit::TestCase
+	include Nytimes::Articles
+	
+	context "read-only attributes" do
+		setup do
+			@thumbnail = Thumbnail.new("http://www.foo.com", 400, 600)
+		end
+		
+		%w(url width height).each do |field|
+			should "have a #{field} attribute" do
+				assert @thumbnail.respond_to?(field)
+			end
+			
+			should "be read-only for the #{field} attribute" do
+				assert_raise(NoMethodError) do
+					@thumbnail.send "#{field}=", "new value"
+				end
+			end
+		end
+	end
+	
+	context "Facet.init_from_api" do
+		setup do
+			@hash = {"small_image_url" => "http://foo.com/", 'small_image_width' => '400', 'small_image_height' => '600'}
+		end
+		
+		should "return nil if reply from API has no URL" do
+			assert_nil Thumbnail.init_from_api(nil)
+			assert_nil Thumbnail.init_from_api({})
+		end
+		
+		%w(width height).each do |dimension|
+			should "set to nil if it is nil in the array" do
+				@hash["small_image_#{dimension}"] = nil
+				thumbnail = Thumbnail.init_from_api(@hash)
+				assert_nil thumbnail.send(dimension)
+			end
+			
+			should "cast to an Integer value if passed a string" do
+				thumbnail = Thumbnail.init_from_api(@hash)
+				assert_equal @hash["small_image_#{dimension}"].to_i, thumbnail.send(dimension)
+			end
+		end
+	end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: harrisj-nytimes-articles
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Jacob Harris
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-02-14 00:00:00 -08:00
+date: 2009-02-17 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -38,6 +38,7 @@ files:
 - lib/nytimes_articles/exceptions.rb
 - lib/nytimes_articles/facet.rb
 - lib/nytimes_articles/result_set.rb
+- lib/nytimes_articles/thumbnail.rb
 - lib/nytimes_articles.rb
 - test/nytimes
 - test/nytimes/articles
@@ -45,6 +46,7 @@ files:
 - test/nytimes/articles/test_base.rb
 - test/nytimes/articles/test_facet.rb
 - test/nytimes/articles/test_result_set.rb
+- test/nytimes/articles/test_thumbnail.rb
 - test/test_helper.rb
 has_rdoc: true
 homepage: http://github.com/harrisj/nytimes-articles